Forms
=====

The ``coins`` app provides a single user-facing form -- the
coin creation / edit form. It is one of the per-app
subclasses of :class:`~richy.core.forms.BaseUserItemForm` (see
:doc:`/modules/core/forms`), narrowed to :class:`Coin`, with
an extra ``coin_id`` field and cross-field validation that
disambiguates colliding ticker symbols against
`CoinGecko <https://www.coingecko.com>`_ via the
`Karpet <https://gitlab.com/imn1/karpet>`_ library.

UserCoinForm
------------

Concrete coin variant of
:class:`~richy.core.forms.BaseUserItemForm`. Sets
``item_model = Coin``. The extra ``coin_id`` field carries
the unambiguous CoinGecko slug (see
:doc:`/modules/coins/index`). On edit, both ``symbol`` and
``coin_id`` are rendered read-only so the asset identity
cannot change after creation.

The form-level :meth:`~UserCoinForm.clean` performs the
symbol-disambiguation handshake:

* If the user did not enter a ``coin_id`` and the symbol
  resolves to more than one slug, the form raises a
  validation error asking for an explicit ``coin_id``.
* If the symbol resolves to nothing -- or the entered
  ``coin_id`` is not among the slugs found -- the form
  raises a "Coin ID wasn't found." error.

.. autoclass:: richy.coins.forms.UserCoinForm
   :show-inheritance:

.. automethod:: richy.coins.forms.UserCoinForm.clean