plesty.server.services.catalogue
================================

.. py:module:: plesty.server.services.catalogue

.. autoapi-nested-parse::

   Fetch and search the hub catalogue (hub-registry ``/api/modules/``).

   The registry describes a module's repository and tags; whether its release
   reached PyPI is PyPI's own business, and :func:`pypi_release` asks it. That
   one request decides a real difference on a bench: a release install needs
   nothing but ``uv``, a repository install needs ``git``.



Attributes
----------

.. autoapisummary::

   plesty.server.services.catalogue.Fetcher
   plesty.server.services.catalogue.PYPI_RELEASE_URL


Exceptions
----------

.. autoapisummary::

   plesty.server.services.catalogue.CatalogueError


Classes
-------

.. autoapisummary::

   plesty.server.services.catalogue.Catalogue


Functions
---------

.. autoapisummary::

   plesty.server.services.catalogue.http_fetch
   plesty.server.services.catalogue.pypi_release
   plesty.server.services.catalogue._canonical


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

.. py:data:: Fetcher

.. py:data:: PYPI_RELEASE_URL
   :value: 'https://pypi.org/pypi/{package}/json'


.. py:exception:: CatalogueError

   Bases: :py:obj:`RuntimeError`


   The catalogue could not be fetched or read.

   Initialize self.  See help(type(self)) for accurate signature.


.. py:function:: http_fetch(url: str, timeout: float = 15.0) -> bytes

   GET *url* with the standard library (the bench may have no ``requests``).


.. py:function:: pypi_release(package: str, fetch: Fetcher | None = None) -> str | None

   The newest release of *package* on PyPI, or ``None`` when it has none there.

   :param package: Distribution name.
   :param fetch: Reads a URL; injected by tests.


.. py:class:: Catalogue(index_url: str | None = None, fetch: Fetcher | None = None)

   The hub catalogue at one index URL.

   Bind to an index.

   :param index_url: ``/api/modules/`` endpoint; the public hub by default.
   :param fetch: Reads a URL; injected by tests.


   .. py:attribute:: index_url
      :value: 'https://hub.plesty.net/api/modules/'



   .. py:attribute:: _fetch


   .. py:attribute:: _cache
      :type:  list[plesty.server.model.catalogue.CatalogueEntry] | None
      :value: None



   .. py:method:: entries(refresh: bool = False) -> list[plesty.server.model.catalogue.CatalogueEntry]

      Every module the index lists (fetched once, then cached).

      :raises CatalogueError: When the index cannot be fetched or is not JSON.



   .. py:method:: search(query: str = '', vendor: str = '', category: str = 'devices', standard: str = REQUIRED_STANDARD) -> list[plesty.server.model.catalogue.CatalogueEntry]

      Entries matching *query*, filtered by vendor, category and standard (``""`` = any).



   .. py:method:: vendors(category: str = 'devices') -> list[str]

      The vendor groups present in *category*.



   .. py:method:: lookup(package: str) -> plesty.server.model.catalogue.CatalogueEntry | None

      The entry named *package* (any category, any standard), or ``None``.



.. py:function:: _canonical(name: str) -> str