mainframe.endpoints.package
===========================

.. py:module:: mainframe.endpoints.package


Attributes
----------

.. autoapisummary::

   mainframe.endpoints.package.router
   mainframe.endpoints.package.logger


Functions
---------

.. autoapisummary::

   mainframe.endpoints.package.submit_results
   mainframe.endpoints.package.lookup_package_info
   mainframe.endpoints.package._deduplicate_packages
   mainframe.endpoints.package._get_packages_metadata
   mainframe.endpoints.package.batch_queue_package
   mainframe.endpoints.package.queue_package


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

.. py:data:: router

.. py:data:: logger
   :type:  structlog.stdlib.BoundLogger

.. py:function:: submit_results(result: mainframe.models.schemas.PackageScanResult | mainframe.models.schemas.PackageScanResultFail, session: Annotated[sqlalchemy.orm.Session, Depends(get_db)], auth: Annotated[mainframe.json_web_token.AuthenticationData, Depends(validate_token)])

.. py:function:: lookup_package_info(session: Annotated[sqlalchemy.orm.Session, Depends(get_db)], since: Optional[int] = None, name: Optional[str] = None, version: Optional[str] = None, page: Optional[int] = None, size: Optional[int] = None) -> fastapi_pagination.Page[mainframe.models.schemas.Package] | collections.abc.Sequence[mainframe.models.schemas.Package]

   Lookup information on scanned packages based on name, version, or time
   scanned. If multiple packages are returned, they are ordered with the most
   recently queued package first.

   :param since: A int representing a Unix timestamp representing when to begin the search from.
   :param name: The name of the package.
   :param version: The version of the package.
   :param session: DB session.

   Only certain combinations of parameters are allowed. A query is valid if any of the following combinations are used:
       - `name` and `version`: Return the package with name `name` and version `version`, if it exists.
       - `name` and `since`: Find all packages with name `name` since `since`.
       - `since`: Find all packages since `since`.
       - `name`: Find all packages with name `name`.
   All other combinations are disallowed.

   In more formal terms, a query is valid
       iff `((name and not since) or (not version and since))`
   where a given variable name means that query parameter was passed. Equivalently, a request is invalid
       iff `(not (name or since) or (version and since))`


.. py:function:: _deduplicate_packages(packages: list[mainframe.models.schemas.PackageSpecifier], session: sqlalchemy.orm.Session) -> set[tuple[str, str]]

.. py:function:: _get_packages_metadata(pypi_client: letsbuilda.pypi.PyPIServices, packages_to_check: set[tuple[str, str]]) -> collections.abc.Iterable[letsbuilda.pypi.Package]

.. py:function:: batch_queue_package(packages: list[mainframe.models.schemas.PackageSpecifier], session: Annotated[sqlalchemy.orm.Session, Depends(get_db)], auth: Annotated[mainframe.json_web_token.AuthenticationData, Depends(validate_token)], pypi_client: Annotated[letsbuilda.pypi.PyPIServices, Depends(get_pypi_client)])

.. py:function:: queue_package(package: mainframe.models.schemas.PackageSpecifier, session: Annotated[sqlalchemy.orm.Session, Depends(get_db)], auth: Annotated[mainframe.json_web_token.AuthenticationData, Depends(validate_token)], pypi_client: Annotated[letsbuilda.pypi.PyPIServices, Depends(get_pypi_client)]) -> mainframe.models.schemas.QueuePackageResponse

   Queue a package to be scanned when the next runner is available
   :param Body: Request body paramters
   :param session: Database session
   :param pypi_client: client instance used to interact with PyPI JSON API

   :returns: The given package and version combination was not found on PyPI
             409: The given package and version combination has already been queued
   :rtype: 404