flip_api.db.seed.roles
======================

.. py:module:: flip_api.db.seed.roles


Attributes
----------

.. autoapisummary::

   flip_api.db.seed.roles.CURRENT_ROLES


Classes
-------

.. autoapisummary::

   flip_api.db.seed.roles.RoleSeed


Functions
---------

.. autoapisummary::

   flip_api.db.seed.roles.seed_roles


Module Contents
---------------

.. py:class:: RoleSeed

   Bases: :py:obj:`TypedDict`


   A predefined role to seed; ``id`` is the stable :class:`RoleRef` identity.


   .. py:attribute:: id
      :type:  uuid.UUID


   .. py:attribute:: name
      :type:  str


   .. py:attribute:: description
      :type:  str


.. py:data:: CURRENT_ROLES
   :type:  list[RoleSeed]

.. py:function:: seed_roles(session: sqlmodel.Session) -> list[str]

   Seed roles into the database, idempotently.

   Idempotency is keyed on the role ``id`` (the stable :class:`RoleRef`), not the
   name. A role may be renamed across releases while keeping its id — e.g. the
   ``observer`` → ``viewer`` rename — so matching on the (mutable) name would miss
   the existing row and collide on the primary key when re-seeding a live database.
   An existing role has its name/description refreshed in place (bumping
   ``updated_at``) so renames apply; an unchanged re-seed is left untouched.

   :param session: The SQLModel session used for reads and writes.
   :type session: Session

   :returns: All role names present after seeding.
   :rtype: list[str]