cmem_client.client¤
Main API client for eccenca Corporate Memory.
This module provides the primary Client class that serves as the central interface for interacting with eccenca Corporate Memory instances. The Client orchestrates authentication, HTTP communication, and provides access to various service components like workspaces and graph stores.
The Client uses lazy loading for its components and can be configured either manually or automatically from environment variables, making it flexible for different deployment scenarios.
Examples:
>>> from os import environ
>>> from cmem_client.models.url import HttpUrl
>>> from cmem_client.auth_provider.client_credentials import ClientCredentialsFlow
>>> config = Config(url_base=HttpUrl(environ.get("TESTING_BASE_URL")))
>>> client = Client(config=config)
>>> client_id = environ.get("TESTING_CCF_CLIENT_ID")
>>> client_secret = environ.get("TESTING_CCF_CLIENT_SECRET")
>>> client.auth = ClientCredentialsFlow(config=config, client_id=client_id, client_secret=client_secret)
>>> # Client is now configured with oauth provider from environment
Logging
The client logs through the standard library. Its logger is cmem_client.client
unless another one is passed to the constructor, and every component creates a child
of it, named after its class (cmem_client.client.GraphsRepository). Configuring
the client logger therefore configures the whole library.
The quickest way is configure_client_logger(), which sets the level and installs
a handler:
client = Client.from_env() client.configure_client_logger(level=”DEBUG”) client.configure_client_logger(level=”INFO”, filename=”cmem.log”)
Deployments which already describe their logging in a file use
configure_logging_from_dict() or configure_logging_from_json() instead. Both
validate the configuration against
LoggingConfig before handing it to
logging.config.dictConfig():
client.configure_logging_from_json(Path(“logging.json”))
In addition to the standard levels, the client installs a TRACE level (5), which
is more verbose than DEBUG. Methods carrying the
log_method decorator log their arguments on
entry and their result on exit at that level, which makes it useful when a request
does not do what you expect:
client.configure_client_logger(level=”TRACE”) client.configure_client_logger(level=”INFO”)
Because TRACE logs arguments and results verbatim, it can write credentials and
payloads into your logs. Keep it out of production.
Classes:
- Client – API Client for eccenca Corporate Memory.
Client¤
API Client for eccenca Corporate Memory.
The Client class provides the main interface for interacting with eccenca Corporate Memory instances. It manages authentication, HTTP communication, and provides access to various service components through lazy-loaded properties.
The client follows a lazy initialization pattern where components are only created when first accessed, improving performance and reducing unnecessary resource allocation.
Attributes:
- config (
Config) – Configuration object containing URLs and connection settings. - _headers (
dict) – Class-level dictionary of HTTP headers shared across instances. - _auth (
AuthProvider) – Authentication provider for obtaining access tokens. - _http (
Client) – HTTP client instance for making API requests. - _workspace (
BuildWorkspace) – DataIntegration workspace component for build operations. - _store (
GraphStore) – DataPlatform graph store component for explore operations.
Functions:
- configure_client_logger – Configure logging for the client’s loggger and its decendants.
- configure_logging_from_dict – Configure logging for the client.
- configure_logging_from_json – Configure logging for the client via a json file.
- from_cmempy – Create a client instance configured from a cmempy environment.
- from_context – Create a client instance configured from a cmem-plugin-base context object.
- from_dict – Create a client instance from a plain dictionary of configuration values.
- from_env – Create a client instance configured from environment variables.
- get_new_httpx_client – Create a new HTTP client instance with current configuration.
Parameters:
- config (
Config) – Configuration object containing base URLs, SSL settings, and other connection parameters. - auth (
AuthProvider | None) – Optional authentication provider. If given, it is applied through theauthsetter (which fetches an access token and prepares the HTTP client). IfNone, an authentication provider must be set before making authenticated requests. - logger (
Logger | None) – Optional Logger object for configuring logging.
access_conditions¤
Get the access conditions repository for managing DataPlatform authorization.
Returns: The access conditions repository instance, created lazy on first access.
auth¤
Get the current authentication provider.
Returns the authentication provider responsible for obtaining and refreshing access tokens for API requests.
Returns:
AuthProvider– The currently configured AuthProvider instance.
Raises:
ClientNoAuthProviderError– If no authentication provider has been set on this client instance.
Note
An authentication provider must be set before the client can make authenticated API requests. Use Client.from_env() for automatic configuration or set the auth property manually.
client_accounts¤
Get the Keycloak OpenID Connect client accounts repository.
Returns the ClientAccountRepository for managing OpenID Connect client accounts in the Corporate Memory Keycloak realm.
Returns:
ClientAccountRepository– The ClientAccountRepository instance, created lazily on first access.
Examples:
>>> client = Client.from_env()
>>> for client_account in client.client_accounts.values():
... print(client_account.client_id)
config¤
Configuration object containing URLs, timeouts, and SSL settings.
configure_client_logger¤
Configure logging for the client’s loggger and its decendants.
Parameters:
- level (
str | int) – Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL) or int - format_string (
str | None) – Custom log format string - handlers (
list[Handler] | None) – List of custom handlers (if provided, overrides filename) - filename (
str | Path | None) – Path to log file (creates FileHandler if provided)
Examples:
>>> client = Client.from_env()
>>> client.configure_client_logger(level="DEBUG")
>>> client.configure_client_logger(level="INFO", filename="cmem.log")
configure_logging_from_dict¤
Configure logging for the client.
Parameters:
- config (
dict[str, Any]) – Dictionary of logging configuration
configure_logging_from_json¤
Configure logging for the client via a json file.
Parameters:
- json_config (
Path) – Path to json configuration file
datasets¤
Get the DataIntegration (build) datasets repository.
Returns the DatasetsRepository for managing Corporate Memory datasets within projects. Provides access to dataset listing, creation, update, deletion, and file resource upload/download operations.
Returns:
DatasetsRepository– The DatasetsRepository instance, created lazily on first access.
Examples:
>>> client = Client.from_env()
>>> client.datasets.fetch_data()
>>> for dataset in client.datasets.values():
... print(dataset.get_id())
deployment¤
Get the deployment status component.
Returns the Deployment component for aggregating version and health information across all Corporate Memory services.
Returns:
Deployment– The Deployment component instance, created lazily on first access.
Examples:
>>> client = Client.from_env()
>>> status = client.deployment.get_status()
>>> print(status.explore.version, status.health)
files¤
Get the files repository for managing files
Returns: The files repository instance, created lazy on first access.
from_cmempy¤
Create a client instance configured from a cmempy environment.
from_context¤
Create a client instance configured from a cmem-plugin-base context object.
This method is intended for use inside corporate memory python plugins.
It extracts connection URLs from the SystemContext and uses the token
provided by the UserContext for authentication, so no environment variables
or credentials need to be supplied manually.
Parameters:
- context (
object) – AnExecutionContextorPluginContextinstance fromcmem-plugin-base. Must expose asystemattribute (SystemContext) for URL discovery and auserattribute (UserContext) for token retrieval. - logger (
Logger | None) – Optional Logger object for configuring logging.
Returns:
Client– A fully configured Client instance authenticated via the tokenClient– provided by the context’sUserContext.
Raises:
ClientEnvConfigError– If the base URL cannot be retrieved from the context’sSystemContext.
Examples:
>>> def execute(self, inputs, context):
... client = Client.from_context(context)
... packages = client.marketplace.get_available_packages()
from_dict¤
Create a client instance from a plain dictionary of configuration values.
This factory method is intended for callers that manage their own configuration (e.g. a config file with named environments) and want to pass parsed values directly without relying on environment variables or the cmempy library.
Parameters:
- data (
dict[str, str]) – A flat dictionary whose keys mirror the environment variable names used byfrom_env()(e.g."CMEM_BASE_URI","OAUTH_GRANT_TYPE","OAUTH_CLIENT_SECRET"). - logger (
Logger | None) – Optional Logger object for configuring logging.
Returns:
Client– A fully configured Client instance with authentication providerClient– set from the supplied dictionary.
Raises:
ClientEnvConfigError– If required keys are missing fromdata.
Examples:
>>> client = Client.from_dict({
... "CMEM_BASE_URI": "http://docker.localhost",
... "OAUTH_GRANT_TYPE": "password",
... "OAUTH_CLIENT_ID": "cmemc",
... "OAUTH_USER": "admin",
... "OAUTH_PASSWORD": "admin",
... })
from_env¤
Create a client instance configured from environment variables.
This factory method creates a fully configured client by reading configuration and authentication settings from environment variables. It’s the recommended way to create clients in most applications.
Parameters:
- logger (
Logger | None) – Optional Logger object for configuring logging.
Returns:
Client– A fully configured Client instance with authentication providerClient– automatically set based on environment variables.
Raises:
ClientEnvConfigError– If required environment variables are missing.
Examples:
>>> my_client = Client.from_env() # Uses CMEM_BASE_URI, OAUTH_* vars
>>> store_info = my_client.store.self_information
get_new_httpx_client¤
Create a new HTTP client instance with current configuration.
Creates a fresh httpx.Client instance configured with the current headers, SSL verification settings, and timeout values from the client configuration.
Returns:
Client– A new httpx.Client instance ready for making HTTP requests.
Note
This method is called internally when the auth provider changes or when the HTTP client needs to be refreshed with new headers.
graph_imports¤
Get the graph imports repository for managing graph imports
Returns: The graph imports repository instance, created lazily on first access.
graph_insights¤
Get the Graph Insights repository for managing semspect snapshots.
Returns: The GraphInsightsRepository instance, created lazily on first access.
graphs¤
Get the DataPlatform (explore) graph repository component.
Returns the GraphsRepository component for managing Corporate Memory’s DataPlatform graph repository for importing and exporting graph files and manages their integration with the graph store.
Returns:
GraphsRepository– The GraphRepository component instance, created lazily on first access.
Examples:
>>> from pathlib import Path
>>> client = Client.from_env()
>>> graphs = client.graphs
>>> graphs.import_item(Path("backup.ttl"))
http¤
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 authentication headers, SSL settings, and timeout values.
Returns:
Client– The httpx.Client instance configured for this client.
Note
The HTTP client is automatically recreated when the authentication provider is changed to ensure headers are updated.
logger¤
Return the configured logger.
marketplace¤
Get the DataPlatform (explore) marketplace component.
Returns the Marketplace component.
Returns:
Marketplace– The Marketplace component instance, created lazily on first access.
marketplace_packages¤
Get the package repository for managing Corporate Memory’s marketplace packages
Returns the package repository for managing Corporate Memory’s marketplace packages. This component handles marketplace packages in a .zip format.
Returns: The marketplace package repository instance, created lazily on first access.
Examples:
>>> from pathlib import Path
>>> client = Client.from_env()
>>> packages = client.marketplace_packages
>>> packages.import_item(key="w3c-geo-vocab")
projects¤
Get the DataIntegration (build) project repository component.
Returns the ProjectsRepository component to manage DataIntegration projects, such as importing and exporting project files.
Returns:
ProjectsRepository– The ProjectsRepository component instance, created lazily on first access.
Examples:
>>> from pathlib import Path
>>> client = Client.from_env()
>>> projects = client.projects
>>> projects.import_item(Path("project.zip"))
python_packages¤
Get the package repository for managing python packages
Returns: The python package repository instance, created lazily on first access.
queries¤
Get the DataPlatform (explore) queries repository.
Returns the QueriesRepository for accessing queries stored in the Corporate Memory query catalog. Queries are fetched from RDF catalog graphs and described using SHACL UI vocabulary.
Returns:
QueriesRepository– The QueriesRepository instance, created lazily on first access.
Examples:
>>> client = Client.from_env()
>>> queries = client.queries
>>> queries.fetch_data()
>>> my_query = queries.get(":myQueryId")
schedulers¤
Get the workflow schedulers repository.
Returns the SchedulersRepository for accessing workflow schedulers across all Corporate Memory projects. Schedulers execute workflows at specified intervals and are identified by a ‘project_id:scheduler_id’ composite key.
Returns:
SchedulersRepository– The SchedulersRepository instance, created lazily on first access.
Examples:
>>> client = Client.from_env()
>>> for scheduler in client.schedulers.values():
... print(scheduler.get_id())
store¤
Get the DataPlatform (explore) graph store component.
Returns the GraphStore component for managing Corporate Memory’s DataPlatform graph store, including RDF graph operations, bootstrap data management, and store-level backup/restore functionality.
Returns:
GraphStore– The GraphStore component instance, created lazily on first access.
Examples:
>>> client = Client.from_env()
>>> store_info = client.store.self_information
>>> print(f"Store type: {store_info.type}, version: {store_info.version}")
user_accounts¤
Get the Keycloak user accounts repository.
Returns the UserAccountRepository for managing user accounts in the Corporate Memory Keycloak realm. Provides CRUD operations on user accounts as well as group assignment and password management.
Returns:
UserAccountRepository– The UserAccountRepository instance, created lazily on first access.
Examples:
>>> client = Client.from_env()
>>> for user in client.user_accounts.values():
... print(user.username)
validations¤
Get the repository for managing SHACL batch validation processes.
Returns: The ValidationsRepository instance, created lazily on first access.
variables¤
Get the DataIntegration (build) variables repository.
Returns the VariablesRepository for managing project variables across all Corporate Memory projects. Variables can hold static values or Jinja2 template strings referencing other variables.
Returns:
VariablesRepository– The VariablesRepository instance, created lazily on first access.
Examples:
>>> client = Client.from_env()
>>> for variable in client.variables.values():
... print(variable.get_id())
vocabularies¤
Get the vocabulary catalog repository.
Returns the VocabulariesRepository for listing, installing, uninstalling, and reading cache data for Corporate Memory vocabularies.
Returns:
VocabulariesRepository– The VocabulariesRepository instance, created lazily on first access.
Examples:
>>> client = Client.from_env()
>>> installed = client.vocabularies.list_vocabularies(filter_="installed")
workflows¤
Get the workflows repository for managing workflows
Returns: The workflows repository instance, created lazily on first access.
workspace¤
Get the DataIntegration (build) workspace component.
Returns the BuildWorkspace component for managing Corporate Memory’s DataIntegration workspace, including projects, datasets, transformations, and workspace-level import/export operations.
Returns:
BuildWorkspace– The BuildWorkspace component instance, created lazily on first access.
Examples:
>>> from pathlib import Path
>>> client = Client.from_env()
>>> client.workspace.import_from_zip(Path("backup.zip"))
>>> client.workspace.export_to_zip(Path("new_backup.zip"))
workspace_configs¤
Get the workspace configs repository for managing explore workspace configurations.
Returns: The workspace configs repository instance, created lazy on first access.