Library¶

Constants.

livecheck.constants.RSS_NS¶

Namespace for RSS feeds.

livecheck.constants.SUBMODULES : Mapping[str, set[str | tuple[str, str] | tuple[str, str, str]]]¶

Currently, submodule handling is hard-coded for specific packages.

livecheck.constants.TAG_NAME_FUNCTIONS : Mapping[str, Callable[[str], str]]¶

Functions to prefix tag names for specific packages.

Utility functions.

class livecheck.utils.TextDataResponse(text: str, status_code: int = HTTPStatus.OK)¶

Used for data URI responses.

raise_for_status() → None¶: Do nothing.

status_code : int = 200¶: Defaults to 200 OK.

text : str¶: Text content.

livecheck.utils.assert_not_none(x: T | None) → T¶

Assert that the value is not None.

Returns:¶: The same value when it is not None.
Return type:¶: T
Raises:¶: AssertionError – If x is None.

livecheck.utils.check_program(cmd: str, args: Iterable[str] | None = None, min_version: str | None = None) → bool¶

Check if a program is installed.

Optionally check if the installed version is at least the specified minimum version.

Parameters:¶

cmd : str¶: The command to check.
args : str¶: The arguments to pass to the command.
min_version : str | None¶: The minimum version required. If None, only checks if the program is installed.

Returns:¶

True if the program is installed and the version is at least the minimum version.

Return type:¶

bool

async livecheck.utils.close_sessions() → None¶: Close all cached HTTP sessions.

livecheck.utils.dash_to_underscore(s: str) → str¶

Convert dashes in a string to underscores.

Parameters:¶

s : str¶: Input string.

Returns:¶

String with - replaced by _.

Return type:¶

str

livecheck.utils.dotize(s: str) → str¶

Convert dashes and underscores in a string to full stops.

Parameters:¶

s : str¶: Input string.

Returns:¶

String with - and _ replaced by ..

Return type:¶

str

livecheck.utils.extract_sha(text: str) → str¶

Extract the first valid SHA-1 hash (7 or 40 characters) found in the given string.

Parameters:¶

text : str¶: The input string to search for a SHA-1 hash.

Returns:¶

The SHA-1 hash if found, otherwise empty string.

Return type:¶

str | None

async livecheck.utils.get_content(url: str, headers: Mapping[str, str] | None = None, params: Mapping[str, str] | None = None, method: str = 'GET', data: Mapping[str, str] | None = None, *, allow_redirects: bool = True) → niquests.Response¶

Fetch content from a URL.

Parameters:¶

url : str¶: URL to request.
headers : Mapping[str, str] | None¶: Optional extra HTTP headers.
params : Mapping[str, str] | None¶: Optional query string parameters.
method : str¶: HTTP method name (for example GET).
data : Mapping[str, str] | None¶: Optional form body for the request.
allow_redirects : bool¶: Whether to follow redirects.

Returns:¶

Response object, or a synthetic response on failure or unimplemented schemes.

Return type:¶

niquests.Response

async livecheck.utils.get_last_modified(url: str, headers: Mapping[str, str] | None = None, params: Mapping[str, str] | None = None) → str¶

Get the last modified date of a URL.

Parameters:¶

url : str¶: URL to request with HEAD.
headers : Mapping[str, str] | None¶: Optional HTTP headers.
params : Mapping[str, str] | None¶: Optional query string parameters.

Returns:¶

Last-Modified as YYYYMMDD, or an empty string if unavailable or on error.

Return type:¶

str

async livecheck.utils.hash_url(url: str, headers: Mapping[str, str] | None = None, params: Mapping[str, str] | None = None) → tuple[str, str, int]¶

Hash the content of a URL using BLAKE2b and SHA-512.

Parameters:¶

url : str¶: URL whose body will be hashed.
headers : Mapping[str, str] | None¶: Optional HTTP headers for the GET request.
params : Mapping[str, str] | None¶: Optional query string parameters.

Returns:¶

BLAKE2b hex digest, SHA-512 hex digest, and byte length; or two empty strings and 0 on failure.

Return type:¶

tuple[str, str, int]

livecheck.utils.init_sessions(semaphore: asyncio.Semaphore) → None¶

Initialise the module-level HTTP semaphore and clear the session cache.

Must be called once at the start of the async entry point before any HTTP requests.

Parameters:¶

semaphore : asyncio.Semaphore¶: Shared semaphore bounding concurrent in-flight HTTP requests.

livecheck.utils.is_sha(url: str) → 40 | 7 | 0¶

Extract the last part of a URL and checks if it is a valid SHA-1 hash.

Parameters:¶

url : str¶: The input URL string.

Returns:¶

Returns 7 if it’s a short SHA, 40 if it’s a full SHA, 0 otherwise.

Return type:¶

int

livecheck.utils.prefix_v(s: str) → str¶

Prefix a version string with v.

Parameters:¶

s : str¶: Version string without a leading v.

Returns:¶

Version string with a leading v.

Return type:¶

str

livecheck.utils.session_init(module: str) → AsyncSession¶

Get or create a cached HTTP session for the given module.

Parameters:¶

module : str¶: Module name determining default headers and authentication (for example github).

Returns:¶

Configured HTTP session with caching and concurrency limiting.

Return type:¶

niquests.AsyncSession

Raises:¶

RuntimeError – If init_sessions() has not been called.

Portage utilities.

livecheck.utils.portage.P¶

Portage tree database API instance.

livecheck.utils.portage.catpkg_catpkgsplit(atom: str) → tuple[str, str, str, str]¶

Split an atom string into category, package, and version, but also return CP.

Parameters:¶

atom : str¶: Atom string to split.

Returns:¶

Tuple consisting of CP, category, PN, and PV.

Return type:¶

tuple[str, str, str, str]

Raises:¶

ValueError – If the atom has no category after splitting.

livecheck.utils.portage.catpkgsplit2(atom: str) → tuple[str | None, str, str, str]¶

Split an atom string. This function always returns a four-string tuple.

Parameters:¶

atom : str¶: String to split.

Returns:¶

Tuple consisting of four strings. If category is not set, the first item is None.

Return type:¶

tuple[str | None, str, str, str]

Raises:¶

ValueError – If catpkgsplit() returns None or a tuple of size not equal to 4.

livecheck.utils.portage.compare_versions(old: str, new: str) → bool¶

Compare two version strings using Portage’s vercmp().

Parameters:¶

old : str¶: The old version string.
new : str¶: The new version string.

Returns:¶

True if the old version is less than the new version, False otherwise.

Return type:¶

bool

livecheck.utils.portage.fetch_ebuild(ebuild_path: str) → bool¶

Perform ebuild fetch operation.

Parameters:¶

ebuild_path : str¶: Path to the ebuild file.

Returns:¶

True if the fetch succeeded.

Return type:¶

bool

async livecheck.utils.portage.get_aux(match: str, keys: Iterable[_AuxKey], mytree: str | None = None) → list[str]¶

Get ebuild metadata values via P.async_aux_get().

Parameters:¶

match : str¶: CPV string to look up.
keys : Iterable[str]¶: Ebuild metadata keys to fetch (e.g. SRC_URI, HOMEPAGE).
mytree : str | None¶: Canonical path of the tree in which the ebuild is located, or None for automatic lookup.

Returns:¶

Values for the requested keys, in order.

Return type:¶

list[str]

livecheck.utils.portage.get_distdir() → Path¶

Get the DISTDIR path from Portage settings.

Falls back to default /var/cache/distfiles.

Returns:¶: The distfiles directory path.
Return type:¶: Path

async livecheck.utils.portage.get_fetch_map(cpv: str) → dict[str, tuple[str, ...]]¶

Get the SRC_URI fetch map via P.async_fetch_map().

Parameters:¶

cpv : str¶: CPV string for an ebuild.

Returns:¶

Mapping of each file name to a tuple of alternative URIs.

Return type:¶

dict[str, tuple[str, …]]

async livecheck.utils.portage.get_first_src_uri(match: str, search_dir: Path | None = None) → str¶

Get the first source URI for a match string.

Parameters:¶

match : str¶: Match string passed to P.async_aux_get().
search_dir : Path | None¶: Directory to search in, or None to use the default.

Returns:¶

The first source URI, or an empty string if none is found.

Return type:¶

str

async livecheck.utils.portage.get_highest_matches(names: Iterable[str], repo_root: Path | None, settings: LivecheckSettings) → list[str]¶

Get the highest matching versions for an iterable of package names.

Parameters:¶

names : Iterable[str]¶: Package names to search for.
repo_root : Path | None¶: Repository root path to filter matches, or None to accept any repository.
settings : LivecheckSettings¶: Livecheck settings instance.

Returns:¶

List of highest matching package version strings.

Return type:¶

list[str]

livecheck.utils.portage.get_last_version(results: Collection[Mapping[str, str]], repo: str, ebuild: str, settings: LivecheckSettings, version_reference: str = '') → dict[str, str]¶

Get the latest version from the results.

Parameters:¶

results : Collection[Mapping[str, str]]¶: Collection of result mappings containing version information.
repo : str¶: Repository name.
ebuild : str¶: Ebuild atom string.
settings : LivecheckSettings¶: Livecheck settings instance.
version_reference : str¶: Current upstream tag or filename whose versioned pattern candidates must match.

Returns:¶

Dictionary with the latest version information, or an empty dictionary if no update found.

Return type:¶

dict[str, str]

livecheck.utils.portage.get_repository_root_if_inside(directory: Path) → tuple[str, str]¶

Get the repository root if the current working directory is inside a repository.

Parameters:¶

directory : Path¶: Directory path to check.

Returns:¶

Tuple of repository root path and repository name, or empty strings if not found.

Return type:¶

tuple[str, str]

livecheck.utils.portage.remove_leading_zeros(ver: str) → str¶

Remove leading zeros from date-like version components.

Parameters:¶

ver : str¶: The version string to process.

Returns:¶

The version string with leading zeros removed from date-like components.

Return type:¶

str

livecheck.utils.portage.sanitize_version(ver: str, repo: str = '') → str¶

Sanitise a version string.

Parameters:¶

ver : str¶: The version string to sanitise.
repo : str¶: Repository name used to strip matching prefixes.

Returns:¶

The sanitised version string.

Return type:¶

str

livecheck.utils.portage.unpack_ebuild(ebuild_path: str) → str¶

Perform ebuild unpack operation and return the WORKDIR path.

Parameters:¶

ebuild_path : str¶: Path to the ebuild file.

Returns:¶

The WORKDIR path, or an empty string on failure.

Return type:¶

str

Settings¶

Settings.

class livecheck.settings.LivecheckSettings(branches: dict[str, str] = <factory>, custom_livechecks: dict[str, tuple[str, str]] = <factory>, dotnet_packages: dict[str, bool] = <factory>, dotnet_projects: dict[str, str] = <factory>, dist_github_repositories: dict[str, str] = <factory>, dist_github_releases: dict[str, str] = <factory>, go_sum_uri: dict[str, str] = <factory>, type_packages: dict[str, str] = <factory>, no_auto_update: set[str] = <factory>, sha_sources: dict[str, str] = <factory>, transformations: Mapping[str, Callable[[str], str]] = <factory>, yarn_base_packages: dict[str, str] = <factory>, yarn_packages: dict[str, set[str]] = <factory>, jetbrains_packages: dict[str, bool] = <factory>, keep_old: dict[str, bool] = <factory>, gomodule_packages: dict[str, bool] = <factory>, gomodule_path: dict[str, str] = <factory>, nodejs_packages: dict[str, bool] = <factory>, nodejs_path: dict[str, str] = <factory>, nodejs_package_managers: dict[str, str] = <factory>, development: dict[str, bool] = <factory>, composer_packages: dict[str, bool] = <factory>, composer_path: dict[str, str] = <factory>, maven_packages: dict[str, bool] = <factory>, maven_path: dict[str, str] = <factory>, regex_version: dict[str, tuple[str, str]] = <factory>, restrict_version: dict[str, str] = <factory>, sync_version: dict[str, str] = <factory>, stable_version: dict[str, str] = <factory>, request_headers: dict[str, dict[str, str]] = <factory>, request_params: dict[str, dict[str, str]] = <factory>, request_method: dict[str, str] = <factory>, request_data: dict[str, dict[str, str]] = <factory>, regex_multiline: dict[str, bool] = <factory>, auto_update_flag: bool = False, debug_flag: bool = False, development_flag: bool = False, git_flag: bool = False, keep_old_flag: bool = False, progress_flag: bool = False, default_package_manager: str = 'npm', dist_github_repository: str = '', dist_github_release: str = '', dist_force_upload_flag: bool = False, restrict_version_process: str = '')¶

All settings.

dist_force_upload_flag : bool = False¶: Force re-upload even when an asset with the same name already exists.

dist_github_release : str = ''¶: Global release tag for dist archive uploads (from --dist-github-release).

dist_github_releases : dict[str, str]¶: Dictionary of catpkg to release tag override for dist archive uploads.

dist_github_repositories : dict[str, str]¶: Dictionary of catpkg to owner/repo override for dist archive uploads.

dist_github_repository : str = ''¶: Global owner/repo for dist archive uploads (from --dist-github-repository).

dist_settings_for(catpkg: str) → DistGitHubSettings | None¶

Resolve GitHub dist upload settings for a package.

Parameters:¶

catpkg : str¶: Category-package atom.

Returns:¶

Effective dist settings (per-package overriding global), or None if neither is fully configured.

Return type:¶

DistGitHubSettings | None

dotnet_packages : dict[str, bool]¶: Dictionary of catpkg to whether a NuGet packages vendor archive should be built.

dotnet_projects : dict[str, str]¶: Dictionary of catpkg to project or solution file (base name only).

get_package_manager(catpkg: str) → str¶

Return the package manager configured for a package.

Parameters:¶

catpkg : str¶: Category-package atom.

Returns:¶

Package manager command name for Node.js fetches.

Return type:¶

str

go_sum_uri : dict[str, str]¶: Dictionary of catpkg to full URI to go.sum with @PV@ used for where version gets placed.

is_devel(catpkg: str) → bool¶

Check if the package is a development version.

Parameters:¶

catpkg : str¶: Category-package atom.

Returns:¶

Whether the package is treated as a development version.

Return type:¶

bool

no_auto_update : set[str]¶: Disable auto-detection of semantic versioning.

regex_multiline : dict[str, bool]¶: Dictionary of catpkg to multiline flag for regex.

request_data : dict[str, dict[str, str]]¶: Dictionary of catpkg to form data for POST requests.

request_headers : dict[str, dict[str, str]]¶: Dictionary of catpkg to custom HTTP headers.

request_method : dict[str, str]¶: Dictionary of catpkg to HTTP method (GET, POST, etc).

request_params : dict[str, dict[str, str]]¶: Dictionary of catpkg to query parameters.

livecheck.settings.gather_settings(search_dir: Path) → LivecheckSettings¶

Gather settings from livecheck.json files in the given directory.

Parameters:¶

search_dir : Path¶: Directory tree to scan for configuration files.

Returns:¶

Merged settings loaded from discovered configuration.

Return type:¶

LivecheckSettings

Raises:¶

UnknownTransformationFunction – If a transformation function is invalid.

Typing¶

Typing helpers.

livecheck.typing.PropTuple¶

A tuple for properties category, PN, PV, last version, top hash, hash date, and URL.

alias of tuple[str, str, str, str, str, str, str]

livecheck.typing.Response = livecheck.utils.requests.TextDataResponse | niquests.models.Response¶: Special response type.