mafw.devtools.gitlab.docs_registry

Documentation-specific GitLab Generic Package Registry operations.

This module wraps the generic GitLab registry helpers with MAFw-docs-specific defaults (package name, filename conventions).

Functions

download_docs_zip_from_gitlab_generic_registry(...)

Download a documentation zip archive from the GitLab Generic Package Registry.

list_mafw_docs_generic_packages(api_config)

List generic packages for mafw-docs in the GitLab Package Registry.

resolve_mafw_docs_package_ids_by_version(...)

Resolve package IDs for mafw-docs generic packages by version.

upload_docs_zip_to_gitlab_generic_registry(...)

Upload a documentation zip archive to the GitLab Generic Package Registry.
mafw.devtools.gitlab.docs_registry.download_docs_zip_from_gitlab_generic_registry(api_config: GitlabAPIConfiguration, package_version: str, download_dir: Path, package_name: str = 'mafw-docs', file_name: str | None = None, timeout_s: float = 60.0) → Path | None[source]

Download a documentation zip archive from the GitLab Generic Package Registry.

The equivalent GitLab API endpoint is:

GET /projects/:id/packages/generic/:package_name/:package_version/:file_name

The function first issues a HEAD request to determine if the file exists: - 404: the package file does not exist (cache miss) and None is returned. - 200: the file exists and is downloaded. - otherwise: a warning is printed and None is returned.

Authentication headers: - JOB-TOKEN when running on CI (api_config.on_ci is True) - PRIVATE-TOKEN for local execution

Parameters:

  • api_config (gitlab.GitlabAPIConfiguration) – GitLab API configuration

  • package_version (str) – Package version (typically the git tag, e.g. v2.1.0)

  • download_dir (Path) – Directory where the downloaded zip is stored

  • package_name (str) – Generic package name, defaults to mafw-docs

  • file_name (str | None) – File name to retrieve, defaults to mafw-docs-<version>.zip

  • timeout_s (float) – Request timeout in seconds, defaults to 60.0

Returns:

Path to the downloaded zip archive, or None if it does not exist or cannot be retrieved

Return type:

Path | None

mafw.devtools.gitlab.docs_registry.list_mafw_docs_generic_packages(api_config: GitlabAPIConfiguration, package_name: str = 'mafw-docs') → list[dict[str, Any]][source]

List generic packages for mafw-docs in the GitLab Package Registry.

Uses the Packages API: GET /projects/:id/packages and filters for package_type=generic and exact name == package_name.

Parameters:
Returns:

List of package dictionaries from the API

Return type:

list[dict[str, Any]]

mafw.devtools.gitlab.docs_registry.resolve_mafw_docs_package_ids_by_version(api_config: GitlabAPIConfiguration, package_name: str = 'mafw-docs') → dict[str, int][source]

Resolve package IDs for mafw-docs generic packages by version.

Parameters:
Returns:

Mapping from version string to package id

Return type:

dict[str, int]

mafw.devtools.gitlab.docs_registry.upload_docs_zip_to_gitlab_generic_registry(api_config: GitlabAPIConfiguration, package_version: str, zip_path: Path, package_name: str = 'mafw-docs', timeout_s: float = 60.0) → bool[source]

Upload a documentation zip archive to the GitLab Generic Package Registry.

The equivalent GitLab API endpoint is:

PUT /projects/:id/packages/generic/:package_name/:package_version/:file_name

Authentication headers: - JOB-TOKEN when running on CI (api_config.on_ci is True) - PRIVATE-TOKEN for local execution

Parameters:

  • api_config (gitlab.GitlabAPIConfiguration) – GitLab API configuration

  • package_version (str) – Package version (typically the git tag, e.g. v2.1.0)

  • zip_path (Path) – Path to the zip file to upload

  • package_name (str) – Generic package name, defaults to mafw-docs

  • timeout_s (float) – Request timeout in seconds, defaults to 60.0

Returns:

True if the file was uploaded, False if the upload was skipped because the target already exists

Return type:

bool

Raises:

  • FileNotFoundError – If zip_path does not exist

  • RuntimeError – If the upload fails (non-2xx response)