hdx.api.configuration

module hdx.api.configuration

Configuration for HDX

Classes

• ConfigurationError

• Configuration — Configuration for HDX

class ConfigurationError()

Bases : Exception

class Configuration(**kwargs: Any)

Bases : UserDict

Configuration for HDX

Parameters

• **kwargs : Any — See below

• user_agent : str — User agent string. HDXPythonLibrary/X.X.X- is prefixed. Must be supplied if remoteckan is not.

• user_agent_config_yaml : str — Path to YAML user agent configuration. Ignored if user_agent supplied. Defaults to ~/.useragent.yaml.

• user_agent_lookup : str — Lookup key for YAML. Ignored if user_agent supplied.

• hdx_url : str — HDX url to use. Overrides hdx_site.

• hdx_site : str — HDX site to use eg. prod, test. Defaults to stage.

• hdx_read_only : bool — Whether to access HDX in read only mode. Defaults to False.

• hdx_key : str — Your HDX key. Ignored if hdx_read_only = True.

• hdx_config_dict : dict — HDX configuration dictionary to use instead of above 3 parameters OR

• hdx_config_json : Path | str — Path to JSON HDX configuration OR

• hdx_config_yaml : Path | str — Path to YAML HDX configuration

• project_config_dict : dict — Project configuration dictionary OR

• project_config_json : Path | str — Path to JSON Project configuration OR

• project_config_yaml : Path | str — Path to YAML Project configuration

• hdx_base_config_dict : dict — HDX base configuration dictionary OR

• hdx_base_config_json : Path | str — Path to JSON HDX base configuration OR

• hdx_base_config_yaml : Path | str — Path to YAML HDX base configuration. Defaults to library's internal hdx_base_configuration.yaml.

Methods

• set_read_only — Set HDX read only flag

• set_api_key — Set HDX api key

• get_api_key — Return HDX api key or None if read only

• get_user_agent — Return user agent

• get_hdx_site_url — Return HDX web site url

• get_dataset_url — Return HDX dataset url given dataset name

• get_session — Return the session object

• remoteckan — Return the remote CKAN object (see ckanapi library)

• call_remoteckan — Calls the remote CKAN

• create_session_user_agent — Create session and user agent from configuration

• setup_session_remoteckan — Set up remote CKAN from provided CKAN or by creating from configuration

• emailer — Return the Email object (see :any:Email)

• setup_emailer

• read — Read the HDX configuration

• setup — Construct the HDX configuration

• create — Create HDX configuration. Can only be called once (will raise an error if called more than once).

• delete — Delete global HDX configuration.

method Configuration.set_read_only(read_only: bool = True) → None

Set HDX read only flag

Parameters

• read_only : bool — Value to set HDX read only flag. Defaults to True.

• Returns — None

method Configuration.set_api_key(apikey: str) → None

Set HDX api key

Parameters

• apikey : str — Value to set api key.

• Returns — None

method Configuration.get_api_key() → str | None

Return HDX api key or None if read only

Returns

• str | None — HDX api key or None if read only

method Configuration.get_user_agent() → str

Return user agent

Returns

• str — User agent

method Configuration.get_hdx_site_url() → str

Return HDX web site url

Returns

• str — HDX web site url

method Configuration.get_dataset_url(name: str) → str

Return HDX dataset url given dataset name

Parameters

• name : str — Dataset name

Returns

• str — HDX dataset url

method Configuration.get_session() → requests.Session

Return the session object

Returns

• requests.Session — The session object

Raises

• ConfigurationError

method Configuration.remoteckan() → ckanapi.RemoteCKAN

Return the remote CKAN object (see ckanapi library)

Returns

• ckanapi.RemoteCKAN — The remote CKAN object

Raises

• ConfigurationError

method Configuration.call_remoteckan(*args: Any, **kwargs: Any) → dict

Calls the remote CKAN

Parameters

• *args : Any — Arguments to pass to remote CKAN call_action method

• **kwargs : Any — Keyword arguments to pass to remote CKAN call_action method

Returns

• dict — The response from the remote CKAN call_action method

classmethod Configuration.create_session_user_agent(session: requests.Session = None, user_agent: str | None = None, user_agent_config_yaml: Path | str | None = None, user_agent_lookup: str | None = None, use_env: bool = False, **kwargs: Any) → tuple[requests.Session, str]

Create session and user agent from configuration

Parameters

• session : requests.Session — requests Session object to use. Defaults to calling hdx.utilities.session.get_session()

• user_agent : str | None — User agent string. HDXPythonLibrary/X.X.X- is prefixed.

• user_agent_config_yaml : Path | str | None — Path to YAML user agent configuration. Ignored if user_agent supplied. Defaults to ~/.useragent.yaml.

• user_agent_lookup : str | None — Lookup key for YAML. Ignored if user_agent supplied.

• use_env : bool — Whether to read environment variables. Defaults to False.

Returns

• tuple[requests.Session, str] — Tuple of (session, user agent)

method Configuration.setup_session_remoteckan(remoteckan: ckanapi.RemoteCKAN | None = None, **kwargs: Any) → None

Set up remote CKAN from provided CKAN or by creating from configuration

Parameters

• remoteckan : ckanapi.RemoteCKAN | None — CKAN instance. Defaults to setting one up from configuration.

Returns

• None — None

method Configuration.emailer() → Email

Return the Email object (see :any:Email)

Returns

• Email — The email object

Raises

• ConfigurationError

method Configuration.setup_emailer(**kwargs: Any) → None

Set up emailer. Parameters in dictionary or file (eg. yaml below)

| connection_type: "ssl" ("ssl" for smtp ssl or "lmtp", otherwise basic smtp is assumed) | host: "localhost" | port: 123 | local_hostname: "mycomputer.fqdn.com" | timeout: 3 | username: "user" | password: "pass"

Parameters

• **kwargs : Any — See below

• email_config_dict : dict — HDX configuration dictionary OR

• email_config_json : str — Path to JSON HDX configuration OR

• email_config_yaml : str — Path to YAML HDX configuration. Defaults to ~/hdx_email_configuration.yaml.

Returns

• None — None

classmethod Configuration.read() → Configuration

Read the HDX configuration

Returns

• Configuration — The HDX configuration

Raises

• ConfigurationError

classmethod Configuration.setup(configuration: Optional['Configuration'] = None, **kwargs: Any) → None

Construct the HDX configuration

Parameters

• configuration : Optional['Configuration'] — Configuration instance. Defaults to setting one up from passed arguments.

• **kwargs : Any — See below

• user_agent : str — User agent string. HDXPythonLibrary/X.X.X- is prefixed. Must be supplied if remoteckan is not.

• user_agent_config_yaml : str — Path to YAML user agent configuration. Ignored if user_agent supplied. Defaults to ~/.useragent.yaml.

• user_agent_lookup : str — Lookup key for YAML. Ignored if user_agent supplied.

• hdx_url : str — HDX url to use. Overrides hdx_site.

• hdx_site : str — HDX site to use eg. prod, test. Defaults to stage.

• hdx_read_only : bool — Whether to access HDX in read only mode. Defaults to False.

• hdx_key : str — Your HDX key. Ignored if hdx_read_only = True.

• hdx_config_dict : dict — HDX configuration dictionary to use instead of above 3 parameters OR

• hdx_config_json : Path | str — Path to JSON HDX configuration OR

• hdx_config_yaml : Path | str — Path to YAML HDX configuration

• project_config_dict : dict — Project configuration dictionary OR

• project_config_json : Path | str — Path to JSON Project configuration OR

• project_config_yaml : Path | str — Path to YAML Project configuration

• hdx_base_config_dict : dict — HDX base configuration dictionary OR

• hdx_base_config_json : Path | str — Path to JSON HDX base configuration OR

• hdx_base_config_yaml : Path | str — Path to YAML HDX base configuration. Defaults to library's internal hdx_base_configuration.yaml.

Returns

• None — None

classmethod Configuration.create(configuration: Optional['Configuration'] = None, remoteckan: ckanapi.RemoteCKAN | None = None, **kwargs: Any) → str

Create HDX configuration. Can only be called once (will raise an error if called more than once).

Parameters

• configuration : Optional['Configuration'] — Configuration instance. Defaults to setting one up from passed arguments.

• remoteckan : ckanapi.RemoteCKAN | None — CKAN instance. Defaults to setting one up from configuration.

• **kwargs : Any — See below

• user_agent : str — User agent string. HDXPythonLibrary/X.X.X- is prefixed. Must be supplied if remoteckan is not.

• user_agent_config_yaml : str — Path to YAML user agent configuration. Ignored if user_agent supplied. Defaults to ~/.useragent.yaml.

• user_agent_lookup : str — Lookup key for YAML. Ignored if user_agent supplied.

• hdx_url : str — HDX url to use. Overrides hdx_site.

• hdx_site : str — HDX site to use eg. prod, test. Defaults to stage.

• hdx_read_only : bool — Whether to access HDX in read only mode. Defaults to False.

• hdx_key : str — Your HDX key. Ignored if hdx_read_only = True.

• hdx_config_dict : dict — HDX configuration dictionary to use instead of above 3 parameters OR

• hdx_config_json : Path | str — Path to JSON HDX configuration OR

• hdx_config_yaml : Path | str — Path to YAML HDX configuration

• project_config_dict : dict — Project configuration dictionary OR

• project_config_json : Path | str — Path to JSON Project configuration OR

• project_config_yaml : Path | str — Path to YAML Project configuration

• hdx_base_config_dict : dict — HDX base configuration dictionary OR

• hdx_base_config_json : Path | str — Path to JSON HDX base configuration OR

• hdx_base_config_yaml : Path | str — Path to YAML HDX base configuration. Defaults to library's internal hdx_base_configuration.yaml.

Returns

• str — HDX site url

Raises

• ConfigurationError

classmethod Configuration.delete() → None

Delete global HDX configuration.

Returns

• None — None