CogniteClient

class cognite.client.CogniteClient(config: Optional[ClientConfig] = 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: Optional[dict[str, Any]] = None, headers: Optional[dict[str, Any]] = None) → Response

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

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

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

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

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

delete(url: str, params: Optional[dict[str, Any]] = None, headers: Optional[dict[str, Any]] = 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: Optional[str] = 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: Optional[str] = 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: Optional[str] = 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: Optional[str] = None, base_url: Optional[str] = None, max_workers: Optional[int] = None, headers: Optional[dict[str, str]] = None, timeout: Optional[int] = None, file_transfer_timeout: Optional[int] = 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: Optional[str] = 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)