tlcconfig.option_loader

This module contains the OptionLoader class, which is used to load and store the 3LC options.

Module Contents

Classes

Class	Description
Readable
OptionValue	Holds the value of a 3LC option
OptionLoader	Load the 3LC options.

Functions

Function	Description
format_type	Format the type for human-readable output.
check_type	Check if the type of the given instance matches the hinted type. Returns True if it matches, otherwise returns a tuple of False and a descriptive error message.
get_default_config_file	Return the default config file.
get_default_config_file_locations	Return the default config file location.

API

class Readable

Bases: typing.Protocol

read(

mode: str = 'b',

) → bytes | str

Method to read content from the object.

format_type(

tp: type,

) → str

Format the type for human-readable output.

check_type(

instance: Any,

hinted: type,

) → tuple[bool, str]

Check if the type of the given instance matches the hinted type. Returns True if it matches, otherwise returns a tuple of False and a descriptive error message.

get_default_config_file() → str

Return the default config file.

get_default_config_file_locations() → list[str]

Return the default config file location.

class OptionValue(

cls: type[OPTION],

)

Holds the value of a 3LC option

format() → object

Return a formatted version of the value.

validate() → None

Validate the value of the option.

Raises an informative ValueError if the value is invalid.

class OptionLoader(

config_file: str | None = None,

initialize: bool = True,

set_additional_arguments: Callable[[OptionLoader], tuple[Any, list[str]]] | None = None,

)

Load the 3LC options.

Note

Even if config_file is passed in, values from environment variables will override values from the config file.

Parameters:

• config_file – The config file to use. If None, the default config files will be searched for and used if they exist.

• initialize – If True, the options will be read from the config file and environment variables. This is the default.

Raises:

FileNotFoundError – If config_file is set and does not exists.

property config_file: str | None

property config_files: list[str]

property additional_argument_result: tuple[Any, list[str]] | None

get_config() → dict[type[OPTION], object]

Return the current configuration as a dictionary.

get_value(

option: type[OPTION],

) → object

Return the value of an option without the config source decoration.

get_config_source(

option: type[OPTION],

) → ConfigSource | list[ConfigSource] | dict[str, ConfigSource]

Return the value of an option.

get_config_source_info(

option: type[OPTION],

) → str | list[str | None] | dict[str, str | None] | None

Return the value of an option.

set_value(

option: type[OPTION],

value: object,

config_source: ConfigSource = ConfigSource.API,

) → None

Set the value of an option.

validate() → None

Validate the configuration.

Raises a ValueError if the configuration is invalid.

to_yaml(

doc_strings: bool = True,

detail: bool = False,

) → str

Return the current configuration as a YAML string.

to_default_yaml(

doc_strings: bool = True,

) → str

Return the default configuration as a YAML string.

write_to_yaml_file(

filename: str,

overwrite: bool = False,

doc_strings: bool = True,

detail: bool = False,

) → bool

Write the current configuration to a YAML file.

Parameters:

• filename – The name of the file to write to, if not set the default config file will be used as returned by get_default_config_file.

• overwrite – If True, the file will be overwritten if it exists. If False, the file will not be written.

• doc_strings – If True, doc strings will be included as comments in the output YAML file.

update_from_yaml_file(

config_file: str | Readable,

config_file_type: Literal[tlcurl.config_source.ConfigSource.CONFIG_FILE, tlcurl.config_source.ConfigSource.SECONDARY_CONFIG_FILE] = ConfigSource.CONFIG_FILE,

filter_keys: list[str] | None = None,

) → None

Update the configuration from a YAML file.

update_from_environment() → None

Update the configuration from the environment.

update_from_project_root_config_file() → None

Update the configuration from the project root config file.

static set_instance(

option_loader: OptionLoader,

) → None

Set the instance of the OptionLoader to be used by the rest of the package.

Parameters:

option_loader – The OptionLoader instance to be used by the rest of the application.

static instance() → OptionLoader

Return the instance of the OptionLoader to be used by the rest of the application.

If the instance has not been set, a new instance will be created using the defaults.

Returns:

The OptionLoader instance to be used by the rest of the application.

Raises:

ValueError – If no valid OptionLoader can be created.

static resolve_effective_config_file(

path: str | None = None,

env: dict[str, str] | None = None,

) → str | None

Return the effective config file path.

This method is deprecated and will be removed in a future release.

This method will search for a valid config file in the following order:

• Path specified by the path argument

• Path specified by the TLC_CONFIG_FILE environment variable

• Default config file locations

Parameters:

• path – The path to the config file to use. If None, the default config files will be searched for.

• env – Dict for environment variables. If None, os.environ will be used.

Returns:

A string with a path to a config file. Returns None if no config file can be found.

Raises:

FileNotFoundError – If the path argument or TLC_CONFIG_FILE environment variable is specified but the file does not exist.