Skip to content

livery.forge._registry

livery.forge._registry

The package-index reader: livery.forge.Registry over the simple API.

One backend for every simple-API index, PyPI and the forges' own registries alike: the simple API is the one interface they share, and "which versions of this name are published" needs nothing more. An index that answers PEP 691 JSON is read as JSON; one that answers only PEP 503 HTML (Gitea's registry does) is read from its anchors' filenames. The release train's receipt probe reads through this, so the answer must be the index's own, never a cache's.

Classes:

Name Description
SimpleRegistry

A simple-API index, addressed by its simple root.

Functions:

Name Description
purge_gitlab_packages

Delete every PyPI package version the GitLab project at base/project holds.

purge_packages

Delete every kind package version owner holds on the Gitea at base.

SimpleRegistry

SimpleRegistry(base: str, *, token: str = '', username: str = '')

A simple-API index, addressed by its simple root.

Parameters:

Name Type Description Default
base str

The index's simple root (https://pypi.org/simple, or a forge registry's equivalent), with or without a trailing slash.

required
token str

Sent as HTTP basic auth when the index needs it; empty reads anonymously. Basic covers the union: a forge registry takes its account name and token, and an API-token index takes __token__ as the user.

''
username str

The basic-auth user beside token; __token__ when empty, which is what an API-token index expects. Meaningless without a token.

''

Methods:

Name Description
versions

The published versions of name, oldest first.

Source code in packages/forge/src/livery/forge/_registry.py
def __init__(self, base: str, *, token: str = "", username: str = "") -> None:
    self._base = base.rstrip("/")
    self._token = token
    self._username = username

versions

versions(name: str) -> tuple[str, ...]

The published versions of name, oldest first.

An unpublished name answers the empty tuple (the index's 404 is that answer, not an error); an unreachable index raises livery.forge.ForgeError with the reason, and so does an index whose answer is neither PEP 691 JSON nor PEP 503 HTML.

Source code in packages/forge/src/livery/forge/_registry.py
def versions(self, name: str) -> tuple[str, ...]:
    """The published versions of *name*, oldest first.

    An unpublished name answers the empty tuple (the index's 404
    is that answer, not an error); an unreachable index raises
    livery.forge.ForgeError with the reason, and so does an index
    whose answer is neither PEP 691 JSON nor PEP 503 HTML.
    """
    canonical = name.replace("_", "-").lower()
    if self._token:
        pair = f"{self._username or '__token__'}:{self._token}".encode()
        authorization = {
            "Authorization": f"Basic {base64.b64encode(pair).decode()}"
        }
    else:
        authorization = {}
    request = urllib.request.Request(
        f"{self._base}/{canonical}/",
        headers={
            # HTML is the fallback, declared so an index honouring
            # content negotiation still answers JSON first.
            "Accept": "application/vnd.pypi.simple.v1+json, text/html;q=0.1",
            **authorization,
        },
    )
    try:
        with urllib.request.urlopen(request, timeout=30) as answer:
            body = answer.read()
    except urllib.error.HTTPError as exc:
        if exc.code == 404:
            return ()
        raise ForgeError(
            f"the index refused {canonical}: HTTP {exc.code}",
            status=exc.code,
        ) from exc
    except (urllib.error.URLError, TimeoutError) as exc:
        raise ForgeError(
            f"the index at {self._base} is unreachable: {exc}"
        ) from exc
    text = body.decode("utf-8", errors="replace")
    try:
        payload = json.loads(text)
    except json.JSONDecodeError:
        found = _versions_from_html(text, canonical)
        if found or "<a" in text.lower() or "<html" in text.lower():
            return found
        raise ForgeError(
            f"the index at {self._base} answered neither PEP 691"
            f" JSON nor PEP 503 HTML for {canonical}"
        ) from None
    return tuple(str(v) for v in payload.get("versions") or [])

purge_gitlab_packages

purge_gitlab_packages(base: str, project: str, *, token: str, names: Collection[str] | None = None, api: Callable[[str, str, str], tuple[int, object]] | None = None) -> list[str]

Delete every PyPI package version the GitLab project at base/project holds.

The GitLab half of purge_packages: a project's packages are listed and deleted by id through /projects/:id/packages, the project addressed by its URL-encoded path. With names, only those packages go. Returns name==version per deleted package.

Source code in packages/forge/src/livery/forge/_registry.py
def purge_gitlab_packages(
    base: str,
    project: str,
    *,
    token: str,
    names: Collection[str] | None = None,
    api: Callable[[str, str, str], tuple[int, object]] | None = None,
) -> list[str]:
    """Delete every PyPI package version the GitLab project at *base*/*project* holds.

    The GitLab half of `purge_packages`: a project's packages are
    listed and deleted by id through ``/projects/:id/packages``, the
    project addressed by its URL-encoded path. With *names*, only
    those packages go. Returns ``name==version`` per deleted package.
    """
    from urllib.parse import quote

    call = api or _gitlab_call
    encoded = quote(project, safe="")
    wanted = {_normalise_name(n) for n in names} if names is not None else None
    deleted: list[str] = []
    page = 1
    listed: list[dict[str, object]] = []
    while True:
        status, body = call(
            "GET",
            f"{base}/api/v4/projects/{encoded}/packages?package_type=pypi"
            f"&per_page=100&page={page}",
            token,
        )
        if status != 200 or not isinstance(body, list) or not body:
            break
        listed.extend(item for item in body if isinstance(item, dict))
        if len(body) < 100:
            break
        page += 1
    for item in listed:
        name = str(item.get("name", ""))
        if wanted is not None and _normalise_name(name) not in wanted:
            continue
        status, _ = call(
            "DELETE",
            f"{base}/api/v4/projects/{encoded}/packages/{item.get('id')}",
            token,
        )
        if status in (200, 202, 204):
            deleted.append(f"{name}=={item.get('version', '')}")
    return deleted

purge_packages

purge_packages(base: str, owner: str, *, token: str, kind: str = 'pypi', api: Callable[[str, str, str], tuple[int, object]] | None = None, names: Collection[str] | None = None) -> list[str]

Delete every kind package version owner holds on the Gitea at base.

The workshop's CI loop publishes rehearsal releases into its dev forge's registry, and a rebirth of the loop must publish the same versions again, which the registry refuses while they exist. With names, only those packages go: the loop pins a released member to its release, and the member's stale rehearsal wheels would shadow that release on a first-index resolve. Returns name==version for each deleted release. api is the call seam, (method, path, token) to (status, body), with path below /api/v1; the default speaks to base.

Source code in packages/forge/src/livery/forge/_registry.py
def purge_packages(
    base: str,
    owner: str,
    *,
    token: str,
    kind: str = "pypi",
    api: Callable[[str, str, str], tuple[int, object]] | None = None,
    names: Collection[str] | None = None,
) -> list[str]:
    """Delete every *kind* package version *owner* holds on the Gitea at *base*.

    The workshop's CI loop publishes rehearsal releases into its dev
    forge's registry, and a rebirth of the loop must publish the same
    versions again, which the registry refuses while they exist.
    With *names*, only those packages go: the loop pins a released
    member to its release, and the member's stale rehearsal wheels
    would shadow that release on a first-index resolve. Returns
    ``name==version`` for each deleted release. *api* is the call
    seam, ``(method, path, token)`` to ``(status, body)``, with
    *path* below ``/api/v1``; the default speaks to *base*.
    """
    call = api or (lambda method, path, token: _api_json(base, method, path, token))
    purged: list[str] = []
    while True:
        status, body = call("GET", f"/packages/{owner}?type={kind}&limit=50", token)
        if status == 404 or not isinstance(body, list) or not body:
            return purged
        for item in body:
            if not isinstance(item, dict):
                continue
            name, version = str(item.get("name", "")), str(item.get("version", ""))
            if not name or not version:
                continue
            if names is not None and name not in names:
                continue
            gone, _ = call(
                "DELETE", f"/packages/{owner}/{kind}/{name}/{version}", token
            )
            if gone not in (204, 404):
                raise SystemExit(
                    f"the registry refused to delete {name}=={version}: HTTP {gone}"
                )
            purged.append(f"{name}=={version}")
        if len(body) < 50:
            return purged