mafw.devtools.gitlab.registry

GitLab Generic Package Registry operations.

This module centralizes the HTTP helpers for uploading, downloading, listing, and deleting files in the GitLab Generic Package Registry.

author:

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

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.
mafw.devtools.gitlab.registry._infer_content_type(file_path: Path) → str[source]

Infer a Content-Type from the file extension.

Parameters:

file_path (Path) – Path to the file.

Returns:

A MIME type string.

Return type:

str

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

Delete a single file from a package version.

Parameters:

  • api_config (gitlab.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.registry.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 (gitlab.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.registry.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 (gitlab.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.registry.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.devtools.gitlab.registry.list_generic_package_files(api_config: GitlabAPIConfiguration, package_id: int, *, timeout_s: float = 60.0) → list[dict[str, Any]][source]

List files belonging to a specific package version.

Parameters:

  • api_config (gitlab.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.registry.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:
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.registry.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.devtools.gitlab.registry.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.devtools.gitlab.registry.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.devtools.gitlab.registry.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:
Returns:

A mapping of version strings to package IDs.

Return type:

dict[str, int]

mafw.devtools.gitlab.registry.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[source]

Upload a file to the GitLab Generic Package Registry.

Parameters:

  • api_config (gitlab.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.

mafw.devtools.gitlab.registry._CONTENT_TYPE_MAP: Final[dict[str, str]] = {'.gz': 'application/gzip', '.json': 'application/json', '.tar': 'application/x-tar', '.toml': 'application/toml', '.zip': 'application/zip'}

Mapping of file extensions to Content-Type values for registry uploads.

mafw.devtools.gitlab.registry._MAFW_VERSION_RE: Final[Pattern[str]] = re.compile('^(?:v)?(?P<version>\\d+\\.\\d+\\.\\d+)$')

Pattern for accepted MAFw version overrides.

mafw.devtools.gitlab.registry._PYLOCK_RE: Final[Pattern[str]] = re.compile('^pylock\\.py(?P<python_version>3\\.\\d+)_ref\\.toml$')

Pattern for MAFw reference dependency lock files.