DirectoryIO

class upsilonconf.io.DirectoryIO(config_io: ConfigIO, main_file: str | None = None)[source]

IO for reading/writing configs from a directory.

A config directory can hold any combination of the following three elements:

  1. The base configuration file with the name config (e.g. config.json)

  2. Config files/directories with sub-configs to be added to the base config. These sub-configs are directly added to the base config. The filename of this sub-config will be a new(!) key in the base config.

  3. Config files/directories with config options for the base config. These sub-configs provide one or more sub-config options for an existing(!) key in the base config. Therefore, the filename must match one of the keys in the base config.

Added in version 0.5.0.

Parameters:
config_ioConfigIO

The io to use to read/write files in each directory.

main_filestr, optional

The filename that specifies the main config file when reading or the filename for the file that is created when writing.

Examples

Consider a directory with structure:

examples/hparam/
  config.yaml
  bar.yaml
  baz.yaml

with file-contents:

# config.yaml
foo: 1
bar: option1

# bar.yaml
option1: hparam
option2: not hparam

# baz.yaml
a: 0.1
b: 0.2

When reading this directory, we end up with the following configuration:

>>> upsilonconf.load_config("examples/hparam")  
PlainConfiguration(foo=1, baz=PlainConfiguration(a=0.1, b=0.2), bar='hparam')
property extensions

Collection of extensions that are supported by this IO.

read_from(stream)[source]

Read configuration from a file-like object.

Parameters:
streamTextIO

Readable character stream (file-like object).

Returns:
configdict

A dictionary representing the configuration in the stream.

Raises:
TypeError

If the implementation does not support reading from a stream.

parse_value(val)[source]

Parse string representing a value for a configuration without key.

Added in version 0.8.0.

Parameters:
valstr

The string representing the value.

Returns:
objany basic type

The value object represented by val.

read(path, encoding='utf-8')[source]

Read configuration from a file.

Parameters:
pathPath

Path to a readable text file.

encodingstr, optional

The character encoding to use for the given file.

Returns:
configdict

A dictionary representing the configuration in the file.

write(conf, path, encoding='utf-8')[source]

Write configuration to a file.

Parameters:
confMapping

A dictionary representing the configuration to be written.

pathPath or str

Path to a writeable text file.

encodingstr, optional

The character encoding to use for the given file.

write_to(stream, config)[source]

Write configuration to a file-like object.

Parameters:
streamTextIO

Writeable character stream (file-like object).

confMapping

A dictionary representing the configuration to be written.

Raises:
TypeError

If the implementation does not support writing to a stream.