plesty.server.services.catalogue

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 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. The version drop-downs offer every release (pypi_releases()) and every release tag (remote_tags()), so an older one is picked rather than typed.

Attributes

`Fetcher`
`PYPI_RELEASE_URL`
`_RELEASE`
`_PHASES`

Exceptions

CatalogueError

The catalogue could not be fetched or read.

Classes

Catalogue

The hub catalogue at one index URL.

Functions

`http_fetch`(→ bytes)	GET url with the standard library (the bench may have no `requests`).
`pypi_release`(→ str \| None)	The newest release of package on PyPI, or `None` when it has none there.
`pypi_releases`(→ tuple[str, Ellipsis])	Every release of package on PyPI, newest first; none when it has none or PyPI is out.
`remote_tags`(→ tuple[str, Ellipsis])	The release tags (`v0.3.1`) of the repository at url, newest first.
`release_order`(→ tuple[tuple[int, Ellipsis], int, int])	A sort key for release versions: a snapshot or pre-release before its release.
`_canonical`(→ str)

Module Contents

plesty.server.services.catalogue.Fetcher

plesty.server.services.catalogue.PYPI_RELEASE_URL = 'https://pypi.org/pypi/{package}/json'

exception plesty.server.services.catalogue.CatalogueError

Bases: RuntimeError

The catalogue could not be fetched or read.

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

plesty.server.services.catalogue.http_fetch(url: str, timeout: float = 15.0) → bytes

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

Parameters:

url (str)
timeout (float)

Return type:

bytes

plesty.server.services.catalogue.pypi_release(package: str, fetch: Fetcher | None = None) → str | None

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

Parameters:

package (str) – Distribution name.
fetch (Fetcher | None) – Reads a URL; injected by tests.

Return type:

str | None

plesty.server.services.catalogue.pypi_releases(package: str, fetch: Fetcher | None = None) → tuple[str, Ellipsis]

Every release of package on PyPI, newest first; none when it has none or PyPI is out.

A release whose files were all yanked is left out: uv would refuse to install it unpinned, and offering it pinned offers what its author withdrew.

Parameters:

package (str) – Distribution name.
fetch (Fetcher | None) – Reads a URL; injected by tests.

Return type:

tuple[str, Ellipsis]

plesty.server.services.catalogue.remote_tags(git: str, url: str, timeout: float = 20.0) → tuple[str, Ellipsis]

The release tags (v0.3.1) of the repository at url, newest first.

One git ls-remote; none when it fails or takes longer than timeout. Git is told never to prompt: a repository that wants credentials is one whose tags are not listed, not a console that hangs on a hidden prompt.

Parameters:

git (str) – The git executable.
url (str) – Clone URL.
timeout (float) – Seconds before giving up.

Return type:

tuple[str, Ellipsis]

plesty.server.services.catalogue._RELEASE

plesty.server.services.catalogue._PHASES

plesty.server.services.catalogue.release_order(version: str) → tuple[tuple[int, Ellipsis], int, int]

A sort key for release versions: a snapshot or pre-release before its release.

Plain string or chunk-wise order puts 0.5.0.dev6 above 0.5.0 and 0.10.0 below 0.9.0. Trailing zeros are dropped, so 1.0 and 1.0.0 are the same release. Anything unparseable sorts last.

Parameters:: version (str)
Return type:: tuple[tuple[int, Ellipsis], int, int]

class plesty.server.services.catalogue.Catalogue(index_url: str | None = None, fetch: Fetcher | None = None)

The hub catalogue at one index URL.

Bind to an index.

Parameters:

index_url (str | None) – /api/modules/ endpoint; the public hub by default.
fetch (Fetcher | None) – Reads a URL; injected by tests.

index_url = 'https://hub.plesty.net/api/modules/'

_fetch

_cache: list[plesty.server.model.catalogue.CatalogueEntry] | None = None

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.
Parameters:: refresh (bool)
Return type:: list[plesty.server.model.catalogue.CatalogueEntry]

search(query: str = '', vendor: str = '', category: str = 'devices', standard: str = REQUIRED_STANDARD, refresh: bool = False) → list[plesty.server.model.catalogue.CatalogueEntry]

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

refresh asks the index again instead of answering from the cache — what a module published while the bench runs needs to be seen.

Parameters:

query (str)
vendor (str)
category (str)
standard (str)
refresh (bool)

Return type:

list[plesty.server.model.catalogue.CatalogueEntry]

vendors(category: str = 'devices') → list[str]

The vendor groups present in category.

Parameters:: category (str)
Return type:: list[str]

lookup(package: str) → plesty.server.model.catalogue.CatalogueEntry | None

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

Parameters:: package (str)
Return type:: plesty.server.model.catalogue.CatalogueEntry | None

plesty.server.services.catalogue._canonical(name: str) → str

Parameters:: name (str)
Return type:: str