Skip to content

cmem_client.repositories.vocabularies¤

Repository for managing vocabularies in Corporate Memory.

Provides VocabulariesRepository class for listing, installing, and uninstalling vocabularies, and for reading the global vocabulary cache from DataIntegration.

Installed vocabularies (and their labels) are read from the DataPlatform /api/vocabs endpoint. Installable (not-yet-installed) vocabularies are resolved from the (optional, legacy) vocabulary catalog graph; on newer backends without a catalog graph there are none and only installed vocabularies are listed.

Installing and uninstalling are kept for backwards compatibility but are slated to be superseded by the marketplace package command group. They resolve download URLs from the (optional) vocabulary catalog graph; when it is absent, there is nothing to install and callers should use the marketplace package command group instead.

Graph-level operations (upload, delete, reload) are delegated to GraphsRepository to avoid duplication.

Examples:

List the installed vocabularies:

>>> from cmem_client.client import Client
>>> client = Client.from_env()
>>> for vocabulary in client.vocabularies.list_vocabularies(filter_="installed"):
...     print(vocabulary.iri)

Install a vocabulary from the (legacy) catalog and drop it again:

>>> urls = client.vocabularies.get_catalog_download_urls()
>>> client.vocabularies.install(
...     iri="http://xmlns.com/foaf/0.1/", download_url=urls["http://xmlns.com/foaf/0.1/"]
... )
>>> client.vocabularies.uninstall("http://xmlns.com/foaf/0.1/")

Read the global vocabulary cache of DataIntegration:

>>> client.vocabularies.get_global_cache()

Classes:

Attributes:

CATALOG_ENTRIES_QUERY¤

CATALOG_ENTRIES_QUERY = '\nPREFIX dcat: <http://www.w3.org/ns/dcat#>\nPREFIX voaf: <http://purl.org/vocommons/voaf#>\nPREFIX skos: <http://www.w3.org/2004/02/skos/core#>\nPREFIX vann: <http://purl.org/vocab/vann/>\nSELECT DISTINCT ?iri ?downloadUrl ?label ?prefix\nFROM <{graph}>\nWHERE {{\n    ?iri a voaf:Vocabulary ;\n        dcat:distribution ?distribution .\n    OPTIONAL {{ ?distribution dcat:downloadURL ?url . }}\n    BIND(COALESCE(?url, ?distribution) AS ?downloadUrl)\n    OPTIONAL {{ ?iri skos:prefLabel ?label . }}\n    OPTIONAL {{ ?iri vann:preferredNamespacePrefix ?prefix . }}\n}}\n'

DEFAULT_CATALOG_GRAPH¤

DEFAULT_CATALOG_GRAPH = 'https://ns.eccenca.com/example/data/vocabs/'

REMOVE_CATALOG_ENTRY_IF_NOT_INSTALLABLE¤

REMOVE_CATALOG_ENTRY_IF_NOT_INSTALLABLE = '\nPREFIX dcat: <http://www.w3.org/ns/dcat#>\nWITH <{graph}>\nDELETE {{ ?s ?p ?o }}\nWHERE {{\n    ?s ?p ?o .\n    FILTER NOT EXISTS {{ ?s dcat:distribution ?downloadUrl . }}\n    FILTER (STR(?s) = "{vocab}")\n}}\n'

VocabulariesRepository¤

Bases: Repository[Vocabulary]

Repository for Corporate Memory vocabularies.

Lists vocabularies as the named graphs that declare an owl:Ontology resource and provides install, uninstall, and cache operations. Graph-level operations are delegated to the GraphsRepository via client.graphs.

Functions:

  • fetch_data – Fetch the installed vocabularies from the /api/vocabs endpoint.
  • get_catalog_download_urls – Return all available vocabulary IRIs and their download URLs from the catalog graph.
  • get_catalog_entries – Return installable vocabulary catalog entries keyed by IRI.
  • get_global_cache – Get the global vocabulary cache from DataIntegration.
  • install – Install a vocabulary by downloading it and adding it as an owl:Ontology graph.
  • items – Get the items of the repository
  • keys – Get the keys of the repository
  • list_vocabularies – Return vocabularies filtered by installation status.
  • reload – Reload prefixes and vocabulary cache for the given IRI.
  • uninstall – Uninstall (delete) an installed vocabulary.
  • values – Get the values of the repository

Attributes:

  • logger (Logger) – Gets the client logger

fetch_data¤

fetch_data()

Fetch the installed vocabularies from the /api/vocabs endpoint.

The endpoint reports the installed vocabularies together with their installation status (installed) and label. Installable vocabularies are resolved separately from the vocabulary catalog graph in :meth:list_vocabularies.

get_catalog_download_urls¤

get_catalog_download_urls(catalog_graph=DEFAULT_CATALOG_GRAPH)

Return all available vocabulary IRIs and their download URLs from the catalog graph.

Queries the vocabulary catalog graph for entries that provide a download URL. If the catalog graph does not exist, an empty mapping is returned.

Parameters:

  • catalog_graph (str) – URI of the vocabulary catalog graph to query.

Returns:

  • dict[str, str] – Mapping of vocabulary IRI to download URL.

get_catalog_entries¤

get_catalog_entries(catalog_graph=DEFAULT_CATALOG_GRAPH)

Return installable vocabulary catalog entries keyed by IRI.

Queries the vocabulary catalog graph for entries that provide an HTTP download URL and builds Vocabulary objects carrying the download URL and a human-readable label ("<prefix>: <prefLabel>" when both are available). If the catalog graph does not exist, an empty mapping is returned.

Parameters:

  • catalog_graph (str) – URI of the vocabulary catalog graph to query.

Returns:

  • dict[str, Vocabulary] – Mapping of vocabulary IRI to Vocabulary catalog entry.

get_global_cache¤

get_global_cache()

Get the global vocabulary cache from DataIntegration.

Returns:

  • VocabularyCache – The global vocabulary cache as a VocabularyCache model.

install¤

install(iri, download_url, on_conflict=ImportConflictPolicy.REPLACE)

Install a vocabulary by downloading it and adding it as an owl:Ontology graph.

The vocabulary content is downloaded from the given download_url (the URL is supplied by the caller; it is not resolved from any catalog). The graph upload and vocabulary registration are delegated to GraphsRepository.

Parameters:

  • iri (str) – IRI of the vocabulary to install (used as the graph IRI).
  • download_url (str) – URL to download the vocabulary RDF file from.
  • on_conflict (ImportConflictPolicy) – How to handle a graph that already exists. Defaults to REPLACE.

Raises:

  • HTTPError – If the download request fails.

items¤

items()

Get the items of the repository

keys¤

keys()

Get the keys of the repository

list_vocabularies¤

list_vocabularies(filter_='all', catalog_graph=DEFAULT_CATALOG_GRAPH)

Return vocabularies filtered by installation status.

Installed vocabularies (and their labels) come from the /api/vocabs endpoint. Installable vocabularies are the catalog-graph entries that provide a download URL and are not yet installed; when the catalog graph does not exist there are none.

Parameters:

  • filter_ (VocabularyFilter) – One of “all”, “installed”, or “installable”.
  • catalog_graph (str) – URI of the vocabulary catalog graph used to resolve installable vocabularies (ignored for the “installed” filter).

Returns:

  • list[Vocabulary] – Filtered list of Vocabulary objects.

logger¤

logger: logging.Logger

Gets the client logger

reload¤

reload(iri)

Reload prefixes and vocabulary cache for the given IRI.

Delegates to GraphsRepository._reload_vocabularies which handles both the DI prefix reload and the global vocabulary cache update.

Parameters:

  • iri (str) – IRI of the vocabulary to reload.

uninstall¤

uninstall(iri, catalog_graph=DEFAULT_CATALOG_GRAPH)

Uninstall (delete) an installed vocabulary.

Delegates the graph deletion (and prefix/cache reload) to GraphsRepository, then removes the catalog entry if it has no download URL.

Parameters:

  • iri (str) – IRI of the vocabulary to uninstall.
  • catalog_graph (str) – URI of the vocabulary catalog graph.

Raises:

values¤

values()

Get the values of the repository

VocabularyFilter¤

VocabularyFilter = Literal['all', 'installed', 'installable']

Comments