mainframe.endpoints.report
==========================

.. py:module:: mainframe.endpoints.report


Attributes
----------

.. autoapisummary::

   mainframe.endpoints.report.logger
   mainframe.endpoints.report.router


Functions
---------

.. autoapisummary::

   mainframe.endpoints.report._lookup_package
   mainframe.endpoints.report._validate_inspector_url
   mainframe.endpoints.report._validate_additional_information
   mainframe.endpoints.report._validate_pypi
   mainframe.endpoints.report.report_package


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

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

.. py:data:: router

.. py:function:: _lookup_package(name: str, version: str, session: sqlalchemy.orm.Session) -> mainframe.models.orm.Scan

   Checks if the package is valid according to our database.

   :returns: True if the package exists in the database.

   :raises HTTPException: 404 Not Found if the name was not found in the database,
       or the specified name and version was not found in the database. 409
       Conflict if another version of the same package has already been
       reported.


.. py:function:: _validate_inspector_url(name: str, version: str, body_url: Optional[str], scan_url: Optional[str]) -> str

   Coalesce inspector_urls from ReportPackageBody and Scan.

   :returns: The inspector_url for the package.

   :raises HTTPException: 400 Bad Request if the inspector_url was not passed in
       `body` and not found in the database.


.. py:function:: _validate_additional_information(body: mainframe.models.schemas.ReportPackageBody, scan: mainframe.models.orm.Scan)

   Validates the additional_information field.

   :returns: None if `body.additional_information` is valid.

   :raises HTTPException: 400 Bad Request if `additional_information` was required
       and was not passed


.. py:function:: _validate_pypi(name: str, version: str, http_client: httpx.Client)

.. py:function:: report_package(body: mainframe.models.schemas.ReportPackageBody, session: Annotated[sqlalchemy.orm.Session, Depends(get_db)], auth: Annotated[mainframe.json_web_token.AuthenticationData, Depends(validate_token)], httpx_client: Annotated[httpx.Client, Depends(get_httpx_client)])

   Report a package to PyPI.

   The optional `use_email` field can be used to send reports by email. This
   defaults to `False`.

   There are some restrictions on what packages can be reported. They must:
   - exist in the database
   - exist on PyPI
   - not already be reported

   While the `inspector_url` and `additional_information` fields are optional
   in the schema, the API requires you to provide them in certain cases. Some
   of those are outlined below.

   `inspector_url` and `additional_information` both must be provided if the
   package being reported is in a `QUEUED` or `PENDING` state. That is, the
   package has not yet been scanned and therefore has no records for
   `inspector_url` or any matched rules

   If the package has successfully been scanned (that is, it is in
   a `FINISHED` state), and it has been determined to be malicious, then
   neither `inspector_url` nor `additional_information` is required. If the
   `inspector_url` is omitted, then it will default to a URL that points to
   the file with the highest total score.

   If the package has successfully been scanned (that is, it is in
   a `FINISHED` state), and it has been determined NOT to be malicious (that
   is, it has no matched rules), then you must provide `inspector_url` AND
   `additional_information`.