mafw.tools.gitlab_tools

Helpers for interacting with the GitLab generic package registry.

This tool module is meant to serve development tools like the doc_versioning.py and the release_mgt.py scripts.

Should you need to use it for other generic MAFw related tasks, you might find limitations.

The module centralizes the small HTTP and naming helpers used by the release and documentation maintenance scripts. This keeps registry interactions consistent while allowing each command group to define its own user-facing policy, such as whether uploads should skip or replace pre-existing files.

author:: Bulgheroni Antonio (antonio.bulgheroni@ec.europa.eu)

Functions

`build_gitlab_api_configuration`(api_url, ...)	Build a GitLab API configuration from provided values and environment context.
`build_gitlab_auth_headers`(api_config)	Build authentication headers for GitLab API requests.
`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_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.tools.gitlab_tools.GitlabAPIConfiguration(api_url: str, on_ci: bool, project_id: int, token: str, token_type: Literal['job_token', 'api_token'])[source]

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.tools.gitlab_tools.build_gitlab_api_configuration(api_url: str | None, project_id: int | None, token: str | None) → GitlabAPIConfiguration[source]

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.tools.gitlab_tools.build_gitlab_auth_headers(api_config: GitlabAPIConfiguration) → MutableMapping[str, str | bytes][source]

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.tools.gitlab_tools.delete_generic_package_version(api_config: GitlabAPIConfiguration, package_id: int, package_name: str, package_version: str) → bool[source]

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 logging/error reporting).
package_version (str) – The version of the package (for logging/error reporting).

Returns:

True if the package was successfully deleted, False if not found or forbidden.

Return type:

bool

Raises:

RuntimeError – If the API request fails.

mafw.tools.gitlab_tools.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[source]

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.tools.gitlab_tools.iter_local_pylock_reference_files(directory: Path) → list[tuple[str, Path]][source]

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.tools.gitlab_tools.list_generic_packages(api_config: GitlabAPIConfiguration, package_name: str) → list[dict[str, Any]][source]

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.tools.gitlab_tools.normalize_dependency_registry_item(item: str) → tuple[str, str][source]

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.tools.gitlab_tools.normalize_mafw_version(version_text: str) → str[source]

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.tools.gitlab_tools.parse_pylock_reference_filename(file_name: str) → tuple[str, str] | None[source]

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.tools.gitlab_tools.resolve_package_ids_by_version(api_config: GitlabAPIConfiguration, package_name: str) → dict[str, int][source]

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.tools.gitlab_tools.upload_generic_file(api_config: GitlabAPIConfiguration, package_name: str, package_version: str, file_path: Path, *, replace_existing: bool = False, timeout_s: float = 60.0) → bool[source]

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 in the registry.
timeout_s (float) – Request timeout in seconds.

Returns:

True if the file was uploaded, False if skipped because it already exists.

Return type:

bool

Raises:

FileNotFoundError – If the file_path does not exist.
RuntimeError – If the API request fails.

mafw.tools.gitlab_tools._MAFW_VERSION_RE: Final[Pattern[str]] = re.compile('^(?:v)?(?P<version>\\d+\\.\\d+\\.\\d+)$'): Pattern for accepted MAFw version overrides.

mafw.tools.gitlab_tools._PYLOCK_RE: Final[Pattern[str]] = re.compile('^pylock\\.py(?P<python_version>3\\.\\d+)_ref\\.toml$'): Pattern for MAFw reference dependency lock files.