luplo.core.actors
=================

.. py:module:: luplo.core.actors

.. autoapi-nested-parse::

   CRUD operations for the actors table.

   Actors are attribution labels — "who wrote this" metadata referenced as
   FK on items, history, and audit rows. They are not authenticated
   principals: luplo core does not know about passwords, sessions, or
   OAuth. A deployment that needs authentication layers it on top and
   translates its own user identities into ``actor_id`` before calling
   luplo.

   After 0002 migration, ``actors.id`` is a UUID (string in Python).
   After 0006 migration, ``password_hash`` / ``is_admin`` / ``last_login_at``
   / ``oauth_provider`` / ``oauth_subject`` are removed.



Functions
---------

.. autoapisummary::

   luplo.core.actors.create_actor
   luplo.core.actors.get_actor
   luplo.core.actors.get_actor_by_email


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

.. py:function:: create_actor(conn: psycopg.AsyncConnection[Any], *, name: str, email: str, role: str | None = None, external_ids: dict[str, str] | None = None, id: str | None = None) -> luplo.core.models.Actor
   :async:


   Create a new actor.

   :param conn: Async psycopg connection.
   :param name: Display name.
   :param email: Unique email (required after 0002). Used as an attribution
                 label, not an authentication identifier.
   :param role: Optional role description.
   :param external_ids: Optional mapping of external system IDs.
   :param id: Optional UUID string; auto-generated UUID4 if omitted.

   :returns: The newly created ``Actor``.

   :raises psycopg.errors.UniqueViolation: If *email* already exists.


.. py:function:: get_actor(conn: psycopg.AsyncConnection[Any], actor_id: str) -> luplo.core.models.Actor | None
   :async:


   Fetch an actor by ID. Returns ``None`` if not found.


.. py:function:: get_actor_by_email(conn: psycopg.AsyncConnection[Any], email: str) -> luplo.core.models.Actor | None
   :async:


   Look up an actor by email. Returns ``None`` if not found.