mafw.devtools.gitlab

GitLab integration helpers for MAFw development tools.

This package provides HTTP helpers for communicating with the GitLab API and the Generic Package Registry.

Functions

delete_generic_package_file(api_config, ...)	Delete a single file from a package version.
delete_generic_package_version(api_config, ...)	Delete a package version from the GitLab Package Registry.
download_generic_file(api_config, ...[, ...])	Download a file from the GitLab Generic Package Registry.
iter_local_pylock_reference_files(directory)	List local reference dependency files in a directory.
list_generic_package_files(api_config, ...)	List files belonging to a specific package version.
list_generic_packages(api_config, package_name)	List generic packages for a given name in the GitLab Package Registry.
normalize_dependency_registry_item(item)	Normalize a registry item into a Python version and dependency file name.
normalize_mafw_version(version_text)	Normalize a MAFw version override and strip an optional leading v.
parse_pylock_reference_filename(file_name)	Parse a reference dependency filename into the Python version and normalized file name.
resolve_package_ids_by_version(api_config, ...)	Resolve package IDs for a package name by version.
upload_generic_file(api_config, ...[, ...])	Upload a file to the GitLab Generic Package Registry.

Classes

GitlabAPIConfiguration(api_url, on_ci, ...)

Configuration needed to communicate with the GitLab API.

class mafw.devtools.gitlab.GitlabAPIConfiguration(api_url: str, on_ci: bool, project_id: int, token: str, token_type: Literal['job_token', 'api_token'])

Bases: object

Configuration needed to communicate with the GitLab API.

Parameters:

• api_url (str) – Base GitLab API v4 URL.

• on_ci (bool) – Whether the process runs on GitLab CI.

• project_id (int) – GitLab project numeric ID.

• token (str) – Authentication token value.

• token_type (Literal['job_token', 'api_token']) – Token kind used for authentication.

mafw.devtools.gitlab.build_gitlab_api_configuration(api_url: str | None, project_id: int | None, token: str | None) → GitlabAPIConfiguration

Build a GitLab API configuration from provided values and environment context.

Parameters:

• api_url (str | None) – Optional override for the GitLab API URL.

• project_id (int | None) – Optional override for the GitLab project ID.

• token (str | None) – Optional override for the authentication token.

Returns:

The validated GitLab API configuration.

Return type:

GitlabAPIConfiguration

Raises:

ValueError – If any required configuration value is missing.

mafw.devtools.gitlab.build_gitlab_auth_headers(api_config: GitlabAPIConfiguration) → MutableMapping[str, str | bytes]

Build authentication headers for GitLab API requests.

Parameters:

api_config (GitlabAPIConfiguration) – The GitLab API configuration.

Returns:

A mutable mapping of HTTP headers.

Return type:

MutableMapping[str, str | bytes]

mafw.devtools.gitlab.delete_generic_package_file(api_config: GitlabAPIConfiguration, package_id: int, file_id: int, *, timeout_s: float = 60.0) → bool

Delete a single file from a package version.

Parameters:

• api_config (GitlabAPIConfiguration) – The GitLab API configuration.

• package_id (int) – The numeric ID of the package version.

• file_id (int) – The numeric ID of the package file to delete.

• timeout_s (float) – Request timeout in seconds.

Returns:

True if deleted, False if not found or forbidden.

Return type:

bool

Raises:

RuntimeError – If the API request fails.

mafw.devtools.gitlab.delete_generic_package_version(api_config: GitlabAPIConfiguration, package_id: int, package_name: str, package_version: str) → bool

Delete a package version from the GitLab Package Registry.

Parameters:

• api_config (GitlabAPIConfiguration) – The GitLab API configuration.

• package_id (int) – The numeric ID of the package version.

• package_name (str) – The name of the package (for error reporting).

• package_version (str) – The version of the package (for error reporting).

Returns:

True if deleted, False if not found or forbidden.

Return type:

bool

Raises:

RuntimeError – If the API request fails.

mafw.devtools.gitlab.download_generic_file(api_config: GitlabAPIConfiguration, package_name: str, package_version: str, file_name: str, download_dir: Path, *, timeout_s: float = 60.0) → Path | None

Download a file from the GitLab Generic Package Registry.

Parameters:

• api_config (GitlabAPIConfiguration) – The GitLab API configuration.

• package_name (str) – The name of the generic package.

• package_version (str) – The version of the generic package.

• file_name (str) – The name of the file to download.

• download_dir (Path) – The local directory where to save the file.

• timeout_s (float) – Request timeout in seconds.

Returns:

The Path to the downloaded file, or None if not found.

Return type:

Path | None

Raises:

RuntimeError – If the API request fails.

mafw.devtools.gitlab.iter_local_pylock_reference_files(directory: Path) → list[tuple[str, Path]]

List local reference dependency files in a directory.

Parameters:

directory (Path) – The directory to search for reference files.

Returns:

A list of (python_version, file_path) tuples, sorted by version.

Return type:

list[tuple[str, Path]]

mafw.devtools.gitlab.list_generic_package_files(api_config: GitlabAPIConfiguration, package_id: int, *, timeout_s: float = 60.0) → list[dict[str, Any]]

List files belonging to a specific package version.

Parameters:

• api_config (GitlabAPIConfiguration) – The GitLab API configuration.

• package_id (int) – The numeric ID of the package version.

• timeout_s (float) – Request timeout in seconds.

Returns:

A list of file metadata dictionaries.

Return type:

list[dict[str, Any]]

Raises:

RuntimeError – If the API request fails.

mafw.devtools.gitlab.list_generic_packages(api_config: GitlabAPIConfiguration, package_name: str) → list[dict[str, Any]]

List generic packages for a given name in the GitLab Package Registry.

Parameters:

• api_config (GitlabAPIConfiguration) – The GitLab API configuration.

• package_name (str) – The name of the package to list.

Returns:

A list of package dictionaries from the API.

Return type:

list[dict[str, Any]]

Raises:

RuntimeError – If the API request fails.

mafw.devtools.gitlab.normalize_dependency_registry_item(item: str) → tuple[str, str]

Normalize a registry item into a Python version and dependency file name.

Parameters:

item (str) – A filename or a version string.

Returns:

A tuple of (python_version, reference_filename).

Return type:

tuple[str, str]

Raises:

ValueError – If the item is invalid or unsupported.

mafw.devtools.gitlab.normalize_mafw_version(version_text: str) → str

Normalize a MAFw version override and strip an optional leading v.

Parameters:

version_text (str) – The version string to normalize.

Returns:

The normalized version string.

Return type:

str

Raises:

ValueError – If the version string is invalid.

mafw.devtools.gitlab.parse_pylock_reference_filename(file_name: str) → tuple[str, str] | None

Parse a reference dependency filename into the Python version and normalized file name.

Parameters:

file_name (str) – The filename to parse.

Returns:

A tuple of (python_version, filename) if matched, else None.

Return type:

tuple[str, str] | None

mafw.devtools.gitlab.resolve_package_ids_by_version(api_config: GitlabAPIConfiguration, package_name: str) → dict[str, int]

Resolve package IDs for a package name by version.

Parameters:

• api_config (GitlabAPIConfiguration) – The GitLab API configuration.

• package_name (str) – The name of the package.

Returns:

A mapping of version strings to package IDs.

Return type:

dict[str, int]

mafw.devtools.gitlab.upload_generic_file(api_config: GitlabAPIConfiguration, package_name: str, package_version: str, file_path: Path, *, replace_existing: bool = False, package_id: int | None = None, timeout_s: float = 60.0) → bool

Upload a file to the GitLab Generic Package Registry.

Parameters:

• api_config (GitlabAPIConfiguration) – The GitLab API configuration.

• package_name (str) – The name of the generic package.

• package_version (str) – The version of the generic package.

• file_path (Path) – The local path to the file to upload.

• replace_existing (bool) – Whether to overwrite if the file already exists.

• package_id (int | None) – Optional numeric package ID to avoid extra API calls.

• timeout_s (float) – Request timeout in seconds.

Returns:

True if the file was uploaded, False if skipped.

Return type:

bool

Raises:

• FileNotFoundError – If the file_path does not exist.

• RuntimeError – If the API request fails.

Modules

api	GitLab API configuration and authentication helpers.
docs_registry	Documentation-specific GitLab Generic Package Registry operations.
registry	GitLab Generic Package Registry operations.