luplo.core.systems
==================

.. py:module:: luplo.core.systems

.. autoapi-nested-parse::

   CRUD operations for the systems table.

   Systems represent game systems or software components within a project
   (e.g. "karma", "vendor", "banking").  The ``depends_on_system_ids`` array
   tracks cross-system dependencies for impact analysis.



Functions
---------

.. autoapisummary::

   luplo.core.systems.create_system
   luplo.core.systems.get_system
   luplo.core.systems.list_systems
   luplo.core.systems.update_system


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

.. py:function:: create_system(conn: psycopg.AsyncConnection[Any], *, project_id: str, name: str, description: str | None = None, depends_on_system_ids: list[str] | None = None, id: str | None = None) -> luplo.core.models.System
   :async:


   Create a new system within a project.

   :param conn: Async psycopg connection.
   :param project_id: Owning project.
   :param name: Unique name within the project.
   :param description: Optional description.
   :param depends_on_system_ids: IDs of systems this one depends on.
   :param id: Optional ID override; auto-generated UUID4 if omitted.

   :returns: The newly created ``System``.

   :raises psycopg.errors.UniqueViolation: If *(project_id, name)* already exists.


.. py:function:: get_system(conn: psycopg.AsyncConnection[Any], system_id: str, *, project_id: str | None = None) -> luplo.core.models.System | None
   :async:


   Fetch a system by ID or hex prefix (≥8 chars).

   Returns ``None`` when nothing matches; raises
   :class:`AmbiguousIdError` when a prefix matches multiple rows.
   Pass *project_id* to scope prefix lookups to a single project.


.. py:function:: list_systems(conn: psycopg.AsyncConnection[Any], project_id: str) -> list[luplo.core.models.System]
   :async:


   List all systems for a project, ordered by name.


.. py:function:: update_system(conn: psycopg.AsyncConnection[Any], system_id: str, *, description: Any = _SENTINEL, depends_on_system_ids: Any = _SENTINEL, status: Any = _SENTINEL) -> luplo.core.models.System | None
   :async:


   Update a system.  Only fields explicitly passed are changed.

   Pass ``None`` to clear a field.  Omit (or pass nothing) to leave it
   unchanged.

   :param conn: Async psycopg connection.
   :param system_id: ID of the system to update.
   :param description: New description, ``None`` to clear, or omit.
   :param depends_on_system_ids: New dependency list, ``None`` to clear, or omit.
   :param status: New status, ``None`` to clear, or omit.

   :returns: The updated ``System``, or ``None`` if not found.