flip_api.project_services.get_projects
======================================

.. py:module:: flip_api.project_services.get_projects


Attributes
----------

.. autoapisummary::

   flip_api.project_services.get_projects.router


Functions
---------

.. autoapisummary::

   flip_api.project_services.get_projects.get_projects_paginated_orm
   flip_api.project_services.get_projects._load_latest_query_per_project
   flip_api.project_services.get_projects._load_latest_audit_at_per_project
   flip_api.project_services.get_projects._load_user_counts
   flip_api.project_services.get_projects.get_projects_endpoint


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

.. py:data:: router

.. py:function:: get_projects_paginated_orm(session: sqlmodel.Session, user_id: uuid.UUID | None, paging_details: flip_api.utils.paging_utils.PagingInfo, filter_details: flip_api.utils.paging_utils.FilterInfo) -> flip_api.utils.paging_utils.IPagedResponse[flip_api.domain.interfaces.project.IProject]

   Fetches paginated project data from the database using SQLModel ORM.

   :param session: The SQLModel session used for the database queries.
   :type session: Session
   :param user_id: The requesting user's ID. When provided, results are restricted to
                   projects the user owns or has explicit access to.
   :type user_id: UUID | None
   :param paging_details: Page size, offset, and optional search string.
   :type paging_details: PagingInfo
   :param filter_details: Additional filter criteria (e.g. owner ID).
   :type filter_details: FilterInfo

   :returns: Paginated list of projects and total row count.
   :rtype: IPagedResponse[IProject]


.. py:function:: _load_latest_query_per_project(project_ids: list[uuid.UUID], session: sqlmodel.Session) -> dict[uuid.UUID, flip_api.domain.interfaces.project.IProjectQuery]

   Batch-load most-recent cohort query + cohort size for each project.

   Avoids the N+1 cost of calling the per-project query loader on every row.
   Three queries total: pick the latest Queries row per project, then batch the
   trust counts and the cohort totals for the picked query IDs.

   :param project_ids: Project IDs to load queries for.
   :param session: Active SQLModel session.

   :returns: Mapping project_id → ``IProjectQuery`` for projects that have at least
             one cohort query. Projects without one are omitted from the result.


.. py:function:: _load_latest_audit_at_per_project(project_ids: list[uuid.UUID], action: flip_api.domain.schemas.actions.ProjectAuditAction, session: sqlmodel.Session) -> dict[uuid.UUID, str]

   Batch-load the most recent ``projects_audit`` timestamp per project for a given action.

   One SQL round-trip — useful for surfacing stage transition dates (STAGE,
   APPROVE, UNSTAGE, etc.) without paying the N+1 cost of per-project audit
   lookups.


.. py:function:: _load_user_counts(project_ids: list[uuid.UUID], session: sqlmodel.Session) -> dict[uuid.UUID, int]

   Per-project user count.

   The owner is auto-added to ``ProjectUserAccess`` on project creation, so
   this count includes them and the UI doesn't need to ``+1``.


.. py:function:: get_projects_endpoint(request: fastapi.Request, session: sqlmodel.Session = Depends(get_session), user_id: uuid.UUID = Depends(verify_token)) -> flip_api.utils.paging_utils.IPagedData[flip_api.domain.interfaces.project.IProject]

   Get a paginated and filtered list of projects.

   :param request: The HTTP request object, used to access query parameters.
   :type request: Request
   :param session: The database session for querying.
   :type session: Session
   :param user_id: The ID of the user making the request.
   :type user_id: UUID

   :returns: A paginated response containing the projects.
   :rtype: IPagedData[IProject]

   :raises HTTPException: If an error occurs while fetching projects.