Config

MISSING

Config

Configuration settings for working with environment variables.

__call__(name, cast=_default_cast, default=MISSING)

Get the value of the specified environment variable, optionally casting it using the callable syntax.

Parameters:

Name	Type	Description	Default
name	str	The name of the environment variable.	required
cast	Union[Callable[[Any], T], type[T]]	The casting function or type. Defaults to _default_cast.	_default_cast
default	Union[T, type[MISSING]]	The default value to return if the variable is not found. Defaults to MISSING.	MISSING

Returns:

Name	Type	Description
T	T	The value of the environment variable, casted if necessary.

Raises:

Type	Description
MissingName	If the environment variable is not found and no default value is provided.
InvalidCast	If casting the value is unsuccessful.

__post_init__()

Initialize the Config instance after construction.

Reads values from the environment file and updates the internal mapping if necessary.

file_values()

Lazy field for storing values read from the environment file.

Returns:

Name	Type	Description
dict		Dictionary containing values read from the environment file.

get(name, cast=_default_cast, default=MISSING)

Get the value of the specified environment variable, optionally casting it.

Parameters:

Name	Type	Description	Default
name	str	The name of the environment variable.	required
cast	Callable	The casting function. Defaults to _default_cast.	_default_cast
default	Union[Any, type[MISSING]]	The default value to return if the variable is not found. Defaults to MISSING.	MISSING

Returns:

Name	Type	Description
Any	Any	The value of the environment variable, casted if necessary.

Raises:

Type	Description
MissingName	If the environment variable is not found and no default value is provided.
InvalidCast	If casting the value is unsuccessful.

EnvMapping

Bases: MutableMapping[str, str]

A mutable mapping representing the environment variables.

__delitem__(name)

Delete the specified environment variable.

Parameters:

Name	Type	Description	Default
name	str	The name of the environment variable.	required

Raises:

Type	Description
KeyError	If the environment variable has already been read.

__getitem__(name)

Get the value of the specified environment variable.

Parameters:

Name	Type	Description	Default
name	str	The name of the environment variable.	required

Returns:

Name	Type	Description
str		The value of the environment variable.

Raises:

Type	Description
KeyError	If the environment variable is not found.

__iter__()

Iterate through the environment variable names.

Yields:

Name	Type	Description
str	str	The names of environment variables.

__len__()

Get the number of environment variables.

Returns:

Name	Type	Description
int	int	The number of environment variables.

__setitem__(name, value)

Set the value of the specified environment variable.

Parameters:

Name	Type	Description	Default
name	str	The name of the environment variable.	required
value	str	The new value for the environment variable.	required

Raises:

Type	Description
KeyError	If the environment variable has already been read.

Env

Bases: EnvTuple, Enum

An enumeration representing different environment values with associated weights.

Attributes:

Name	Type	Description
LOCAL	Env	The local environment.
TEST	Env	The test environment.
DEV	Env	The development environment.
QA	Env	The quality assurance environment.
PRD	Env	The production environment.

val property

Get the environment value.

Returns:

Name	Type	Description
str		The environment value.

value: EnvTuple property

Get the value associated with the environment.

Returns:

Name	Type	Description
EnvTuple	EnvTuple	The value associated with the environment.

weight property

Get the weight associated with the environment.

Returns:

Name	Type	Description
int		The weight associated with the environment.

new(val) classmethod

Create a new instance of the Env enum based on the given environment value.

Parameters:

Name	Type	Description	Default
val	str	The environment value to create an instance for.	required

Returns:

Name	Type	Description
Env	Self	An instance of the Env enum based on the given value.

Raises:

Type	Description
ValueError	If the provided value is not a valid environment value.

DotFile

Represents a configuration dotfile associated with a specific environment.

Attributes:

Name	Type	Description
filename	Union[str, Path]	The filename or path of the dotfile.
env	Env	The environment associated with the dotfile.
apply_to_lower	bool	Indicates whether the dotfile should be applied to lower-priority environments.

is_higher(env)

Check if the dotfile's environment is higher or equal to the given environment.

Parameters:

Name	Type	Description	Default
env	Env	The environment to compare against.	required

Returns:

Name	Type	Description
bool	bool	True if the dotfile's environment is higher or equal to the given environment, False otherwise.

EnvConfig

Bases: Config

Extended configuration class that supports environment-specific configurations.

__init__(*dotfiles, env_var='CONFIG_ENV', mapping=default_mapping, ignore_default_rule=default_rule, env_cast=Env.new)

Initialize the EnvConfig instance.

Parameters:

Name	Type	Description	Default
*dotfiles	DotFile	One or more DotFile instances representing configuration dotfiles.	()
env_var	str	The name of the environment variable to determine the current environment.	'CONFIG_ENV'
mapping	EnvMapping	An environment mapping to use for configuration values.	default_mapping
ignore_default_rule	Callable[[Env], bool]	A callable to determine whether to ignore default values.	default_rule
env_cast	Callable[[str], Env]	A callable to cast the environment name to an Env enum value.	Env.new

dotfile()

Get the applicable dotfile for the current environment.

Returns:

Name	Type	Description
DotFile		The applicable dotfile, or None if no matching dotfile is found.

env()

Get the current environment from the configuration.

Returns:

Name	Type	Description
Env		The current environment.

get(name, cast=..., default=...)

Get a configuration value, with the option to cast and provide a default value.

Parameters:

Name	Type	Description	Default
name	str	The name of the configuration value.	required
cast	Callable[..., Any]	A callable to cast the value.	...
default	Union[Any, type[MISSING]]	The default value if the configuration is not found.	...

Returns:

Name	Type	Description
Any	Any	The configuration value.

ignore_default()

Determine whether to ignore default values based on the current environment.

Returns:

Name	Type	Description
bool		True if default values should be ignored, False otherwise.

ConfigLike

Bases: Protocol

AdapterConfigFactory

Factory for creating configuration instances based on model classes.

get_strategy_class(config_class) staticmethod

Get the appropriate strategy class for resolving fields in the configuration class.

Parameters:

Name	Type	Description	Default
config_class	type	The configuration class to resolve.	required

Returns:

Type	Description
type[FieldResolverStrategy]	type[FieldResolverStrategy]: The strategy class for resolving fields.

load(model_cls, __prefix__='', __sep__='__', *, presets=None, **defaults)

Load a configuration instance based on a model class.

Parameters:

Name	Type	Description	Default
model_cls	type[T]	The model class representing the configuration.	required
__prefix__	str	Optional prefix for configuration fields.	''
__set__(str)		Optional prefix to separate fields of nested models. Default is "__"	required
presets	Optional[Mapping[str, Any]]	Optional preset values for fields.	None
**defaults	Any	Default values for fields.	{}

Returns:

Name	Type	Description
T	T	The loaded configuration instance.

maker(model_cls, __prefix__='', __sep__='__', *, presets=None, **defaults)

Create a factory function for loading configuration instances.

Parameters:

Name	Type	Description	Default
model_cls	type[T]	The model class representing the configuration.	required
__prefix__	str	Optional prefix for configuration fields.	''
presets	Optional[Mapping[str, Any]]	Optional preset values for fields.	None
**defaults	Any	Default values for fields.	{}

Returns:

Type	Description
Callable[[], T]	Callable[[], T]: The factory function for loading configuration instances.

resolve_confignames(root) classmethod

Resolve the environment variable names required by marked config classes.

Parameters:

Name	Type	Description	Default
root	Path	The root directory of the project.	required

Returns:

Type	Description
dict[type, tuple[Sequence[str], ...]]	dict[type, tuple[Sequence[str], ...]]: A dictionary of config classes and their associated environment variable names.

boolean_cast(string)

Converts a string to its boolean equivalent.

1 and true (case-insensitive) are considered True, everything else is False.

Parameters:

Name	Type	Description	Default
string	str	The string to check if it represents a boolean value.	required

Returns:

Type	Description
	MaybeResult[P, bool]: A maybe result helper. If called normally, it returns an Optional[bool].
	If called with .strict(string), it raises an error if boolean_cast returns None.
	If called with .optional(string), it returns Optional[bool], suppressing exceptions caused by None values.

joined_cast(cast)

Creates a joined casting function for chaining casting operations.

Parameters:

Name	Type	Description	Default
cast	Callable[[str], T]	The casting function to apply.	required

Returns:

Type	Description
_JoinedCast[str, T]	_JoinedCast[str, T]: A _JoinedCast object that allows chaining casting operations.

valid_path(val)

Converts a string to a Path object and checks if the path exists.

Parameters:

Name	Type	Description	Default
val	str	The string representing a file path.	required

Raises:

Type	Description
FileNotFoundError	If the path does not exist.

Returns:

Name	Type	Description
Path	Path	A Path object representing the file path.

with_rule(rule)

Applies a rule check on a value, raising an InvalidEnv exception if the rule is not satisfied.

Parameters:

Name	Type	Description	Default
rule	Callable[[Any], bool]	The rule function to apply.	required

Raises:

Type	Description
InvalidEnv	If the rule condition is not met.

Returns:

Type	Description
	Callable[[T], T]: A caster function that applies the rule check.

as_config(cls)

Transform a class into a config class.

This function applies the @define decorator from gyver.attrs and also marks the class as a config_class

Parameters:

Name	Type	Description	Default
cls	type[T]	The class to be transformed into a config class.	required

Returns:

Type	Description
type[T]	type[T]: The transformed class, marked as a config class.

mark(cls)

Mark a given class as a config class. If the attribute config_class already exists, but is not the SENTINEL, it raises a TypeError indicating that the attribute has an unexpected value. It is used by the resolve_confignames to differentiate config classes

Parameters:

Name	Type	Description	Default
cls	type[T]	The class to be marked as a config class.	required

Returns:

Type	Description
type[T]	type[T]: The class, marked as a config class.