Models
======

The ``etfs`` app has two models: the concrete asset type ``Etf`` and
its dividend records.

Etf
---

Concrete subclass of :class:`~richy.core.models.Item` via Django
multi-table inheritance. Adds an ``indexes`` many-to-many to
:class:`~richy.indexes.models.Index` so an ETF can be tagged with the
indexes it tracks.

Holdings (the ETF's underlying basket) live as JSON on
:class:`~richy.core.models.ItemData` under the ``holdings`` key and
are accessed exclusively through the two helpers below -- never via
``ItemData`` directly.

The ``update_cache`` override invalidates the ETF-specific
transaction-performance / profit-performance cache keys and re-warms
them by re-running ``Performance``.

.. autoclass:: richy.etfs.models.Etf
   :show-inheritance:

.. automethod:: richy.etfs.models.Etf.set_holdings
.. automethod:: richy.etfs.models.Etf.get_holdings
.. automethod:: richy.etfs.models.Etf.update_cache

Dividend
--------

A dividend record for an :class:`Etf`. Inherits all fields from
:class:`~richy.core.models.BaseDividend` and adds only the ``etf``
foreign key. Records are downloaded by
:meth:`~richy.core.scraper.Manager.get_dividends` (which wraps the
``rug`` library); ETFs with no dividends produce an empty list.

Field semantics:

- ``ex_date`` -- the first date on which the ETF is traded without
  the right to receive the next dividend payment (equals the
  ``record_date`` since 2024).
- ``record_date`` -- the day the fund finalizes which shareholders
  receive the dividend.
- ``payment_date`` -- the date the dividend is paid out.
- ``yield_value`` -- dividend in %.
- ``amount_value`` -- dividend as a value in currency.

.. autoclass:: richy.etfs.models.Dividend
   :show-inheritance: