`ssb_timeseries.config`¶

Configurations for the SSB timeseries library.

An environment variable ENV_VAR_NAME is expected to point to a JSON file with configurations. If these exist, they will be loaded and put into a Config object when the configuration module is loaded.

In most cases, this would happen behind the scene when ssb_timeseries.dataset or ssb_timeseries.catalog are imported.

Directly accessing the configuration module should only be required when manipulating configurations from Python code.

Example

>>> from ssb_timeseries.config import Config
>>>
>>> cfg = Config.active()

… modify, eg. disable library logging (leave the responsibility to the application using it): >>> cfg.logging = {}

>>>
>>> cfg.save()
>>>
>>> cfg.activate()

For switching between preset configurations, apply the preset, then save and activate it:

cfg = Config(preset="defaults")
cfg.save()
cfg.activate()

main() performs those three steps for a named preset. From a terminal, ssb_timeseries.cli.config inspects configurations without changing them:

ts config list
ts config show defaults
ts config path

class Config(**kwargs)¶

Bases: object

Configuration for reading, modifying, saving, and activating timeseries configurations.

A configuration can be loaded from a specified file, from the file identified by ENV_VAR_NAME, or from the default configuration preset. Configuration values can also be provided or overridden as keyword arguments.

A newly created configuration exists only in memory. Use save() to persist it to a file and activate() to make it the active configuration. The active configuration can be retrieved with active() or reloaded from its file with refresh().

__eq__(other)¶

Equality test.

Return type:: bool
Parameters:: other (Self | dict)

__getitem__(item)¶

Get the value of a configuration.

Return type:: Optional[typing.Any]
Parameters:: item (str)

__init__(**kwargs)¶

Initialize Config object from keyword arguments.

Keyword Arguments:

preset (str) – Optional. Name of a preset configuration. If provided, the preset configuration is loaded, and no other parameters are considered.
configuration_file (str) – Path to the configuration file. If the parameter is not provided, the environment variable ENV_VAR_NAME is used. If the environment variable is not set, the default configuration file location is used.
repositories (dict[str, Repository]) – New in version 0.5.0. Replaces bucket, timeseries_root and catalog.
ignore_file (bool) – Read a missing configuration_file as an empty file, merged over the defaults, instead of raising.
log_file (str) – Deprecated and discarded. Configure a file handler under logging instead.
bucket (str) – Name of the GCS bucket. Stored on the instance for callers to read; this module does not use it.

Raises:

FileNotFoundError – If a configuration_file is specified and does not exist. # noqa: DAR402
ValidationError – If the resulting configuration is not valid. # noqa: DAR402

Return type:

None

Examples

To load an existing preset configuration:

>>> from ssb_timeseries.config import Config
>>> config = Config(preset='defaults')

… or (specific to Statistics Norway and Dapla):

>>> from ssb_timeseries.config import Config
>>> config = Config(preset='daplalab')

__str__()¶

Return timeseries configurations as JSON string.

Return type:: str

activate()¶

Update the process wide active in-memory configuration, and if its configuration file exists, update the environment variable ENV_VAR_NAME to point to that file.

Note that this does not save the file. See .save().

Return type:: Self

classmethod active()¶

Return the (in-memory) active configuration.

This does not read from file, use .refresh() to reload it.

Return type:: Config

apply(configuration)¶

Set configuration values from a dictionary.

The dictionary is validated first. A deprecated log_file key is dropped with a warning, and a snapshots section is reported as renamed to archives.

Raises:: ValidationError – If the configuration is not valid.
Return type:: None
Parameters:: configuration (dict)

archives: dict[str, ArchiveConfig]¶: Defines the storage locations for archiving data in stable states.

configuration_file: PathStr¶: The path to the configuration file.

io_handlers: dict[str, Any]¶: IO handlers for repositories, archives and sharing.

property is_valid: bool¶: Check if the configuration has all required fields.

property log_file: str¶: Get file name from logging configuration, if a file based log handler is defined.

logging: dict[str, Any]¶: Logging configuration as a valid logging.dictConfig.

classmethod refresh()¶

Reload the configuration from the file identified by ENV_VAR_NAME, activate it and return it.

Return type:: Self

repositories: dict[str, Repository]¶: Defines storage locations for time series data and metadata.

save(path='')¶

Saves configurations to the JSON file defined by path or configuration_file.

If path is provided, it takes presence and configuration_file will be updated accordingly.

Note that .save() does not activate the configuration instance. Use .activate() to make it the active configuration, or .refresh() to reload the active configuration from its file.

Parameters:: path (str | PathLike[str]) – Full path of the JSON file to save to. If not specified, configuration_file is used. That attribute is set when the configuration is created: from the configuration_file parameter, from the file identified by the environment variable ENV_VAR_NAME, from a preset, or from the default location $HOME/.config/ssb_timeseries/timeseries_config.json. A configuration file contributes its own configuration_file value, which need not be the path it was found at. Note that a preset carries its own configuration_file, so the environment variable does not redirect where a preset configuration is saved.
Raises:: ValueError – If path is not provided and configuration_file is not set.
Return type:: None

sharing: dict[str, Repository]¶: Defines the storage locations for shared data.

ssb_timeseries.config¶

`ssb_timeseries.config`¶