Skip to content

cmem_client.components.marketplace.component¤

eccenca Marketplace server integration.

This module provides the Marketplace component for interacting with the eccenca Marketplace server. The component handles package downloads, uploads and version queries, abstracting the marketplace REST API into a convenient Python interface.

The eccenca Marketplace is a central repository for distributing Corporate Memory packages, including vocabularies, ontologies, and Python plugins. This component enables automated package retrieval for installation and dependency resolution. Packages and licensing each live in their own module of this package; the Marketplace facade delegates to them.

Classes:

  • Marketplace – Interface for eccenca Marketplace server operations.

Attributes:

LICENSE_HEADER¤

LICENSE_HEADER = _LICENSE_HEADER

Header carrying the encrypted license on outbound marketplace requests.

MARKETPLACE_CACHE_DIR¤

MARKETPLACE_CACHE_DIR = xdg_cache_home() / 'eccenca-marketplace'

Marketplace¤

Marketplace(client, marketplace_url='https://eccenca.market', cache_dir=MARKETPLACE_CACHE_DIR, credentials=None, timeout=30, license_issuer_url=None)

Interface for eccenca Marketplace server operations.

The Marketplace component provides methods for downloading, uploading and deleting packages from the eccenca Marketplace server. It handles version resolution, package retrieval, and writing downloaded content to the filesystem.

Attributes:

  • _client (Client) – The Corporate Memory client instance used for HTTP communication.
  • _marketplace_url (HttpUrl) – Default marketplace server URL for package operations.
  • _cache_dir (Path | None) – Directory to use for cached downloads.

Functions:

Parameters:

  • client (Client) – The Corporate Memory client instance.
  • marketplace_url (HttpUrl | str) – Default marketplace server URL. Defaults to the public eccenca Marketplace.
  • cache_dir (Path | None) – Directory to use for cached downloads. If set to None, caching is disabled.
  • credentials (BaseCredentials | None) – The credentials used to authenticate with the marketplace server. Setting this attribute is needed for write operations on the server.
  • timeout (int) – The timeout to wait for a response from the marketplace server. Defaults to 30 seconds.
  • license_issuer_url (HttpUrl | str | None) – The local marketplace whose /api/session mints the encrypted license token attached as x-eccenca-auth to outbound requests. Defaults to client.config.url_marketplace (the marketplace bundled beside Corporate Memory).

cache_dir¤

cache_dir: Path | None

Get the cache directory.

credentials¤

credentials: BaseCredentials | None

Get the marketplace credentials.

delete_package¤

delete_package(package_id)

Delete a package from the marketplace server.

Parameters:

  • package_id (PackageIdentifier) – Marketplace package identifier of the package to be deleted.

Raises:

  • MarketplaceAuthError – If the token could not be provided.
  • MarketplaceDeleteError – If the deletion was rejected by the marketplace server.
  • HTTPError – If the marketplace server request fails.

download_package¤

download_package(package_id, path=None, package_version=None, use_cache=True)

Download a package from the marketplace server to a specified directory.

Queries the marketplace server for available versions and downloads the requested package version. If no version is specified, downloads the latest available version. The package is saved with the naming convention: {package_id}-v{version}.cpa

If the package already exists in the cache, it will be reused instead of re-downloading.

Parameters:

  • package_id (PackageIdentifier) – Marketplace package identifier (e.g., “semanticarts-gist-vocab”).
  • path (Path | None) – Target directory where the package will be saved. If None, uses the cache directory. Must be a directory, not a file path.
  • package_version (PackageVersionIdentifier | None) – Specific version to download. If None, downloads the latest version.
  • use_cache (bool) – If True, use cached version if available instead of downloading.

Returns:

  • Path – The full file path where the package was saved (e.g.,
  • Path – /path/to/cache/semanticarts-gist-vocab-v13.0.0.cpa).

Raises:

  • MarketplaceReadError – If the marketplace server request fails or the package/version is not found.

get_available_packages¤

get_available_packages()

Get the available packages from the marketplace server.

get_available_packages_page¤

get_available_packages_page(package_type=None, search=None, tags=None, sort_by=SortField.package_id, sort_order=SortOrder.asc, offset=0, limit=20, package_license=None, language=None, dependency=None)

Get a filtered, sorted and paginated page of packages from the marketplace server.

Marketplace servers older than the paginated route answer 404; for those the plain package listing is fetched and filtered, sorted and paged here, so callers see the same result shape regardless of the server version. A server that predates one of the filters ignores it, so the result is then wider than asked for.

Parameters:

  • package_type (str | None) – Restrict the result to one package type.
  • search (str | None) – Case-insensitive substring matched against name, description and id.
  • tags (list[str] | None) – Only packages carrying all of these tags.
  • sort_by (SortField) – Metadata field to sort by.
  • sort_order (SortOrder) – Sort direction.
  • offset (int) – Number of items to skip.
  • limit (int) – Maximum number of items to return.
  • package_license (str | None) – Restrict the result to one license identifier.
  • language (list[str] | None) – Only packages available in all of these languages. An empty list leaves the language filter unset.
  • dependency (str | None) – Restrict the result to packages depending on this package id.

Returns:

  • PackageListResponse – The requested page, including paging position and facet counts.

Raises:

  • MarketplaceReadError – If the marketplace server request fails.

get_dependencies_from_package¤

get_dependencies_from_package(package_id, package_version)

Get the dependencies declared by a package version.

Parameters:

  • package_id (PackageIdentifier) – Marketplace package identifier.
  • package_version (PackageVersionIdentifier) – The version to read the dependencies of.

Returns:

  • list[ValidDependency] – The marketplace package and python package dependencies of that version.

Raises:

  • MarketplaceReadError – If the package version is unknown or the request fails.

get_health¤

get_health()

Report version and health of the local marketplace, the one beside Corporate Memory.

Reads api/info of the marketplace at client.config.url_marketplace, which also serves as its health probe; the configured marketplace_url does not matter here.

Returns:

get_manifest_from_package¤

get_manifest_from_package(package_id, package_version)

Get the manifest of a package version.

Parameters:

  • package_id (PackageIdentifier) – Marketplace package identifier.
  • package_version (PackageVersionIdentifier) – The version to read the manifest of.

Returns:

  • ValidManifest – The manifest of that version.

Raises:

  • MarketplaceReadError – If the package version is unknown or the request fails.

get_marketplace_keycloak_token¤

get_marketplace_keycloak_token(credentials=None)

Get the marketplace keycloak token from the marketplace server provided keycloak instance.

This method first fetches the keycloak token URL needed from the marketplace server. After this it fetches a token with the given credentials and provides it for further authentication of protected routes.

When no credentials parameter is given, it uses the class attribute of the marketplace component.

Parameters:

  • credentials (BaseCredentials | None) – Marketplace keycloak credentials.

Returns:

  • str – The marketplace keycloak token.

Raises:

  • MarketplaceAuthError – If no token could be provided.

get_package¤

get_package(package_id)

Get the metadata of a single package from the marketplace server.

Parameters:

  • package_id (PackageIdentifier) – Marketplace package identifier.

Returns:

  • PackageMetadata – The package metadata of the latest version.

Raises:

  • MarketplaceReadError – If the package is unknown or the request fails.

get_versions_from_package¤

get_versions_from_package(package_id)

Get the available versions of a package from the marketplace server.

Parameters:

  • package_id (PackageIdentifier) – Marketplace package identifier.

Returns:

  • list[PackageVersionIdentifier] – List of package versions available, newest first.

Raises:

  • MarketplaceReadError – If the versions could not be retrieved from the marketplace server.

http¤

http: httpx.Client

Get the HTTP client instance for making API requests.

Returns the configured HTTP client, creating it lazily on first access. The client is pre-configured with the timeout value. Authentication headers are added per-request by the individual methods that require them.

Returns:

  • Client – The httpx.Client instance configured for the marketplace component.

license_issuer_url¤

license_issuer_url: HttpUrl

Get the local marketplace URL used as the license-token issuer.

logger¤

logger = logging.getLogger(f'{self._client.logger.name}.{self.__class__.__name__}')

marketplace_url¤

marketplace_url: HttpUrl

Get the marketplace server URL.

set_license_token¤

set_license_token(token, marketplace_url=None)

Set the license token (x-eccenca-auth) to send to a marketplace target.

Callers that can produce the encrypted license themselves – a marketplace server holds its own license and the target’s public key – use this instead of letting the component fetch a token from the license issuer’s /api/session.

Parameters:

  • token (str | None) – The encrypted license to attach, or None to record that there is none (which keeps the header off without a lookup attempt).
  • marketplace_url (HttpUrl | str | None) – The target this token is for. Defaults to the currently configured marketplace URL.

timeout¤

timeout: int

Get the marketplace timeout.

upload_package¤

upload_package(package_id, path)

Upload a local package to the marketplace server.

Parameters:

  • package_id (PackageIdentifier) – Marketplace package identifier of the package to be uploaded.
  • path (Path) – Path of the package to be uploaded. Must be a valid .cpa file.

Raises:

  • MarketplaceAuthError – If the token could not be provided.
  • MarketplaceWriteError – If the upload was rejected by the marketplace server.
  • HTTPError – If the marketplace server request fails.

Comments