orangeqs.juice.client.package_registry#

Generic package update checking against a Python package registry.

This module is intentionally package-agnostic: the registry call, version comparison and the cache-aware checker all take a package name, registry URL and documentation link, so they can be reused for any Python package. OrangeQS Juice is just the first caller.

Module Contents#

Classes#

UpdateCheckResult

Result of an update check for a single package.

Functions#

fetch_release_versions

Fetch all release version strings of a package from a registry.

latest_stable_version

Return the highest stable version from a list of version strings.

is_newer_version

Return True if latest is a newer version than current.

check_for_update

Check whether a newer stable version of a package is available.

Data#

DEFAULT_REGISTRY_URL

Default registry, the PyPI JSON API. {registry_url}/{package}/json.

DEFAULT_MIN_INTERVAL

Minimum time between registry polls for the same package.

API#

orangeqs.juice.client.package_registry.DEFAULT_REGISTRY_URL#

‘https://pypi.org/pypi’

Default registry, the PyPI JSON API. {registry_url}/{package}/json.

orangeqs.juice.client.package_registry.DEFAULT_MIN_INTERVAL#

‘timedelta(…)’

Minimum time between registry polls for the same package.

class orangeqs.juice.client.package_registry.UpdateCheckResult(/, **data: Any)#

Bases: pydantic.BaseModel

Result of an update check for a single package.

current_version: str#

None

The currently installed version of the package.

latest_version: str | None#

None

Latest stable version found in the registry, or last known value. None if never successfully retrieved.

last_checked: datetime.datetime | None#

None

Timestamp of the last successful registry check, if any.

update_available: bool#

None

True if latest_version is newer than current_version.

check_failed: bool#

None

True if the most recent check failed (showing a cached/fallback result).

orangeqs.juice.client.package_registry.fetch_release_versions(package_name: str, registry_url: str = DEFAULT_REGISTRY_URL, timeout: float = 5.0) → list[str]#

Fetch all release version strings of a package from a registry.

This is a thin wrapper around the registry’s JSON API; filtering and version comparison are left to the pure helpers below so they can be tested without a network call.

Parameters#

  • package_name (str): The name of the package to look up.

  • registry_url (str, optional): Base URL of the registry JSON API. Defaults to PyPI.

  • timeout (float, optional): Request timeout in seconds. Defaults to 5 seconds.

Returns#

  • (list[str]): All release version strings published for the package.

Raises#

  • (requests.RequestException): If the registry cannot be reached or returns an error status.

orangeqs.juice.client.package_registry.latest_stable_version(versions: collections.abc.Iterable[str]) → str | None#

Return the highest stable version from a list of version strings.

Ignores pre-release versions (alpha, beta, release candidate), development releases, and any strings that cannot be parsed as a version. Returns None if there are no stable versions.

orangeqs.juice.client.package_registry.is_newer_version(current: str, latest: str) → bool#

Return True if latest is a newer version than current.

Returns False if either version string cannot be parsed.

orangeqs.juice.client.package_registry.check_for_update(package_name: str, current_version: str, registry_url: str = DEFAULT_REGISTRY_URL, min_interval: datetime.timedelta = DEFAULT_MIN_INTERVAL, now: datetime.datetime | None = None) → orangeqs.juice.client.package_registry.UpdateCheckResult#

Check whether a newer stable version of a package is available.

Uses a cached result stored in runtime data when the previous successful check is within min_interval, so the registry is polled at most once per interval. Network and registry failures are caught and logged; in that case a fallback status is returned using the last known result instead of raising.

Parameters#

  • package_name (str): The name of the package to check.

  • current_version (str): The currently installed version of the package.

  • registry_url (str, optional): Base URL of the registry JSON API. Defaults to PyPI.

  • min_interval (timedelta, optional): Minimum time between registry polls. Defaults to 24 hours.

  • now (datetime, optional): Current time, injectable for testing. Defaults to the current UTC time.

Returns#

  • (UpdateCheckResult): The current update status for the package.