CogniteClient

class cognite.client.CogniteClient(config: ClientConfig | None = None)

Main entrypoint into Cognite Python SDK.

All services are made available through this object. See examples below.

Parameters:

config (ClientConfig | None) – The configuration for this client.

get(
url: str,
params: dict[str, Any] | None = None,
headers: dict[str, Any] | None = None,
) → Response

Perform a GET request to an arbitrary path in the API.

post(
url: str,
json: dict[str, Any],
params: dict[str, Any] | None = None,
headers: dict[str, Any] | None = None,
) → Response

Perform a POST request to an arbitrary path in the API.

put(
url: str,
json: dict[str, Any] | None = None,
headers: dict[str, Any] | None = None,
) → Response

Perform a PUT request to an arbitrary path in the API.

delete(
url: str,
params: dict[str, Any] | None = None,
headers: dict[str, Any] | None = None,
) → Response

Perform a DELETE request to an arbitrary path in the API.

property version: str

Returns the current SDK version.

Returns:

The current SDK version

Return type:

str

property config: ClientConfig

Returns a config object containing the configuration for the current client.

Returns:

The configuration object.

Return type:

ClientConfig

classmethod default(
project: str,
cdf_cluster: str,
credentials: CredentialProvider,
client_name: str | None = None,
) → CogniteClient

Create a CogniteClient with default configuration.

The default configuration creates the URLs based on the project and cluster:

  • Base URL: “https://{cdf_cluster}.cognitedata.com/

Parameters:

  • project (str) – The CDF project.

  • cdf_cluster (str) – The CDF cluster where the CDF project is located.

  • credentials (CredentialProvider) – Credentials. e.g. Token, ClientCredentials.

  • client_name (str | None) – A user-defined name for the client. Used to identify the number of unique applications/scripts running on top of CDF. If this is not set, the getpass.getuser() is used instead, meaning the username you are logged in with is used.

Returns:

A CogniteClient instance with default configurations.

Return type:

CogniteClient

classmethod default_oauth_client_credentials(
project: str,
cdf_cluster: str,
tenant_id: str,
client_id: str,
client_secret: str,
client_name: str | None = None,
) → CogniteClient

Create a CogniteClient with default configuration using a client credentials flow.

The default configuration creates the URLs based on the project and cluster:

Parameters:

  • project (str) – The CDF project.

  • cdf_cluster (str) – The CDF cluster where the CDF project is located.

  • tenant_id (str) – The Azure tenant ID.

  • client_id (str) – The Azure client ID.

  • client_secret (str) – The Azure client secret.

  • client_name (str | None) – A user-defined name for the client. Used to identify the number of unique applications/scripts running on top of CDF. If this is not set, the getpass.getuser() is used instead, meaning the username you are logged in with is used.

Returns:

A CogniteClient instance with default configurations.

Return type:

CogniteClient

classmethod default_oauth_interactive(
project: str,
cdf_cluster: str,
tenant_id: str,
client_id: str,
client_name: str | None = None,
) → CogniteClient

Create a CogniteClient with default configuration using the interactive flow.

The default configuration creates the URLs based on the tenant_id and cluster:

Parameters:

  • project (str) – The CDF project.

  • cdf_cluster (str) – The CDF cluster where the CDF project is located.

  • tenant_id (str) – The Azure tenant ID.

  • client_id (str) – The Azure client ID.

  • client_name (str | None) – A user-defined name for the client. Used to identify the number of unique applications/scripts running on top of CDF. If this is not set, the getpass.getuser() is used instead, meaning the username you are logged in with is used.

Returns:

A CogniteClient instance with default configurations.

Return type:

CogniteClient

classmethod load(
config: dict[str, Any] | str,
) → CogniteClient

Load a cognite client object from a YAML/JSON string or dict.

Parameters:

config (dict[str, Any] | str) – A dictionary or YAML/JSON string containing configuration values defined in the CogniteClient class.

Returns:

A cognite client object.

Return type:

CogniteClient

Examples

Create a cognite client object from a dictionary input:

>>> from cognite.client import CogniteClient
>>> import os
>>> config = {
...     "client_name": "abcd",
...     "project": "cdf-project",
...     "base_url": "https://api.cognitedata.com/",
...     "credentials": {
...         "client_credentials": {
...             "client_id": "abcd",
...             "client_secret": os.environ["OAUTH_CLIENT_SECRET"],
...             "token_url": "https://login.microsoftonline.com/xyz/oauth2/v2.0/token",
...             "scopes": ["https://api.cognitedata.com/.default"],
...         },
...     },
... }
>>> client = CogniteClient.load(config)
class cognite.client.config.ClientConfig(
client_name: str,
project: str,
credentials: CredentialProvider,
api_subversion: str | None = None,
base_url: str | None = None,
max_workers: int | None = None,
headers: dict[str, str] | None = None,
timeout: int | None = None,
file_transfer_timeout: int | None = None,
debug: bool = False,
)

Configuration object for the client

Parameters:

  • client_name (str) – A user-defined name for the client. Used to identify number of unique applications/scripts running on top of CDF.

  • project (str) – CDF Project name.

  • credentials (CredentialProvider) – Credentials. e.g. Token, ClientCredentials.

  • api_subversion (str | None) – API subversion

  • base_url (str | None) – Base url to send requests to. Defaults to “https://api.cognitedata.com”

  • max_workers (int | None) – DEPRECATED. Use global_config.max_workers instead. Max number of workers to spawn when parallelizing data fetching. Defaults to 5.

  • headers (dict[str, str] | None) – Additional headers to add to all requests.

  • timeout (int | None) – Timeout on requests sent to the api. Defaults to 30 seconds.

  • file_transfer_timeout (int | None) – Timeout on file upload/download requests. Defaults to 600 seconds.

  • debug (bool) – Configures logger to log extra request details to stderr.

classmethod default(
project: str,
cdf_cluster: str,
credentials: CredentialProvider,
client_name: str | None = None,
) → ClientConfig

Create a default client config object.

Parameters:

  • project (str) – CDF Project name.

  • cdf_cluster (str) – The CDF cluster where the CDF project is located.

  • credentials (CredentialProvider) – Credentials. e.g. Token, ClientCredentials.

  • client_name (str | None) – A user-defined name for the client. Used to identify the number of unique applications/scripts running on top of CDF. If this is not set, the getpass.getuser() is used instead, meaning the username you are logged in with is used.

Returns:

A default client config object.

Return type:

ClientConfig

classmethod load(
config: dict[str, Any] | str,
) → ClientConfig

Load a client config object from a YAML/JSON string or dict.

Parameters:

config (dict[str, Any] | str) – A dictionary or YAML/JSON string containing configuration values defined in the ClientConfig class.

Returns:

A client config object.

Return type:

ClientConfig

Examples

Create a client config object from a dictionary input:

>>> from cognite.client.config import ClientConfig
>>> import os
>>> config = {
...     "client_name": "abcd",
...     "project": "cdf-project",
...     "base_url": "https://api.cognitedata.com",
...     "credentials": {
...         "client_credentials": {
...             "client_id": "abcd",
...             "client_secret": os.environ["OAUTH_CLIENT_SECRET"],
...             "token_url": "https://login.microsoftonline.com/xyz/oauth2/v2.0/token",
...             "scopes": ["https://api.cognitedata.com/.default"],
...         },
...     },
... }
>>> client_config = ClientConfig.load(config)
class cognite.client.config.GlobalConfig

Global configuration object

default_client_config

A default instance of a client configuration. This will be used by the CogniteClient constructor if no config is passed directly. Defaults to None.

Type:

Optional[ClientConfig]

disable_gzip

Whether or not to disable gzipping of json bodies. Defaults to False.

Type:

bool

disable_pypi_version_check

Whether or not to check for newer SDK versions when instantiating a new client. Defaults to False.

Type:

bool

status_forcelist

HTTP status codes to retry. Defaults to {429, 502, 503, 504}

Type:

Set[int]

max_retries

Max number of retries on a given http request. Defaults to 10.

Type:

int

max_retries_connect

Max number of retries on connection errors. Defaults to 3.

Type:

int

max_retry_backoff

Retry strategy employs exponential backoff. This parameter sets a max on the amount of backoff after any request failure. Defaults to 30.

Type:

int

max_connection_pool_size

The maximum number of connections which will be kept in the SDKs connection pool. Defaults to 50.

Type:

int

disable_ssl

Whether or not to disable SSL. Defaults to False

Type:

bool

proxies

Dictionary mapping from protocol to url. e.g. {“https”: “http://10.10.1.10:1080”}

Type:

Dict[str, str]

max_workers

Max number of workers to spawn when parallelizing API calls. Defaults to 5.

Type:

int | None

silence_feature_preview_warnings

Whether or not to silence warnings triggered by using alpha or beta features. Defaults to False.

Type:

bool

apply_settings(settings: dict[str, Any] | str) → None

Apply settings to the global configuration object from a YAML/JSON string or dict.

Note

All settings in the dictionary will be applied unless an invalid key is provided, a ValueError will instead be raised and no settings will be applied.

Warning

This must be done before instantiating a CogniteClient for the configuration to take effect.

Parameters:

settings (dict[str, Any] | str) – A dictionary or YAML/JSON string containing configuration values defined in the GlobalConfig class.

Examples

Apply settings to the global_config from a dictionary input:

>>> from cognite.client import global_config
>>> settings = {
...     "max_retries": 5,
...     "disable_ssl": True,
... }
>>> global_config.apply_settings(settings)