dataclass_wizard.environ package

Submodules

dataclass_wizard.environ.dumpers module

dataclass_wizard.environ.dumpers.asdict(o, *, cls=None, dict_factory=<class 'dict'>, exclude=None, **kwargs)

Return the fields of an instance of a EnvWizard subclass as a new dictionary mapping field names to field values.

Example usage:

class MyEnv(EnvWizard):
    x: int
    y: str

env = MyEnv()
serialized = asdict(env)

When directly invoking this function, an optional Meta configuration for the EnvWizard subclass can be specified via EnvMeta; by default, this will apply recursively to any nested subclasses. Here’s a sample usage of this below:

>>> EnvMeta(key_transform_with_dump='CAMEL').bind_to(MyClass)
>>> asdict(MyClass(my_str="value"))

If given, ‘dict_factory’ will be used instead of built-in dict. The function applies recursively to field values that are EnvWizard subclasses. This will also look into built-in containers: tuples, lists, and dicts.

Return type:

dict[str, Any]

Parameters:

• o (T)

• exclude (Collection[str] | None)

dataclass_wizard.environ.dumpers.dump_func_for_dataclass(cls, config=None, nested_cls_to_dump_func=None)

Return type:

Callable[[E, Any, Any, Any], dict[str, Any]]

Parameters:

• cls (Type[E])

• config (type[META_] | None)

• nested_cls_to_dump_func (Dict[Type, Any] | None)

dataclass_wizard.environ.loaders module

class dataclass_wizard.environ.loaders.EnvLoader

Bases: LoadMixin

This Mixin class derives its name from the eponymous json.loads function. Essentially it contains helper methods to convert JSON strings (or a Python dictionary object) to a dataclass which can often contain complex types such as lists, dicts, or even other dataclasses nested within it.

Refer to the AbstractLoader class for documentation on any of the implemented methods.

static load_func_for_dataclass(cls, config, is_main_class=False)

Return type:

Callable[[Union[str, dict[str, Any], TypeVar(T)], Type[TypeVar(T)]], TypeVar(T)]

Parameters:

• cls (Type[T])

• config (type[META_] | None)

• is_main_class (bool)

static load_to_byte_array(o, base_type, encoding='utf-8')

Return type:

bytearray

Parameters:

• o (AnyStr)

• base_type (Type[bytearray])

static load_to_bytes(o, base_type, encoding='utf-8')

Return type:

bytes

Parameters:

• o (AnyStr)

• base_type (Type[bytes])

static load_to_date(o, base_type)

Attempt to convert an object o to a date object using the below logic.

• str: convert date strings (in ISO format) via the built-in fromisoformat method.

• Number (int or float): Convert a numeric timestamp via the

  built-in fromtimestamp method.

• date: Return object o if it’s already of this type or

  sub-type.

Otherwise, if we’re unable to convert the value of o to a date as expected, raise an error if the raise_ parameter is true; if not, return default instead.

Return type:

date

Parameters:

• o (str | int | float)

• base_type (Type[date])

static load_to_datetime(o, base_type)

Attempt to convert an object o to a datetime object using the below logic.

• str: convert datetime strings (in ISO format) via the built-in fromisoformat method.

• Number (int or float): Convert a numeric timestamp via the

  built-in fromtimestamp method, and return a UTC datetime.

• datetime: Return object o if it’s already of this type or

  sub-type.

Otherwise, if we’re unable to convert the value of o to a datetime as expected, raise an error if the raise_ parameter is true; if not, return default instead.

Return type:

datetime

Parameters:

• o (str | int | float)

• base_type (Type[datetime])

static load_to_defaultdict(o, base_type, default_factory, key_parser, val_parser)

Return type:

TypeVar(DD, bound= defaultdict)

Parameters:

• o (Dict)

• base_type (Type[DD])

• default_factory (Callable[[], T])

• key_parser (AbstractParser)

• val_parser (AbstractParser)

static load_to_dict(o, base_type, key_parser, val_parser)

Return type:

TypeVar(M, bound= Mapping)

Parameters:

• o (Dict)

• base_type (Type[M])

• key_parser (AbstractParser)

• val_parser (AbstractParser)

static load_to_iterable(o, base_type, elem_parser)

Return type:

TypeVar(LSQ, list, set, frozenset, deque)

Parameters:

• o (Iterable)

• base_type (Type[LSQ])

• elem_parser (AbstractParser)

static load_to_named_tuple(o, base_type, field_to_parser, field_parsers)

Return type:

TypeVar(NT, bound= NamedTuple)

Parameters:

• o (Dict | List | Tuple)

• base_type (Type[NT])

• field_to_parser (FieldToParser)

• field_parsers (List[AbstractParser])

static load_to_named_tuple_untyped(o, base_type, dict_parser, list_parser)

Return type:

TypeVar(NT, bound= NamedTuple)

Parameters:

• o (Dict | List | Tuple)

• base_type (Type[NT])

• dict_parser (AbstractParser)

• list_parser (AbstractParser)

static load_to_tuple(o, base_type, elem_parsers)

Return type:

Tuple

Parameters:

• o (List | Tuple)

• base_type (Type[Tuple])

• elem_parsers (Sequence[AbstractParser])

static load_to_typed_dict(o, base_type, key_to_parser, required_keys, optional_keys)

Return type:

TypeVar(M, bound= Mapping)

Parameters:

• o (Dict)

• base_type (Type[M])

• key_to_parser (FieldToParser)

• required_keys (frozenset[str])

• optional_keys (frozenset[str])

static load_to_uuid(o, base_type)

Return type:

TypeVar(U, bound= UUID)

Parameters:

• o (AnyStr | U)

• base_type (Type[U])

dataclass_wizard.environ.lookups module

class dataclass_wizard.environ.lookups.Env

Bases: object

cleaned_to_env = {}

classmethod dotenv_values(files)

Retrieve the values (environment variables) from a dotenv file, or a list/tuple of dotenv files.

classmethod load_environ(force_reload=False)

Load environ from os.environ.

If force_reload is true, start fresh and re-copy os.environ.

classmethod reload(env=None)

Refresh cached environment variable names.

classmethod secret_values(dirs)

Retrieve the values (environment variables) from secret file(s) in a secret directory, or a list/tuple of secret directories.

classmethod update_with_dotenv(files='.env', dotenv_values=None)

classmethod update_with_secret_values(dirs)

var_names = {}

dataclass_wizard.environ.lookups.clean(s)

TODO:

see https://stackoverflow.com/questions/1276764/stripping-everything-but-alphanumeric-chars-from-a-string-in-python also, see if we can refactor to use something like Rust and pyo3 for a slight performance improvement.

dataclass_wizard.environ.lookups.lookup_exact(var)

Lookup by variable name(s) with exact letter casing, and return None if not found in the environment.

dataclass_wizard.environ.lookups.try_cleaned(key)

Return the value of the env variable as a string if present in the Environment, or MISSING otherwise.

dataclass_wizard.environ.lookups.with_pascal_or_camel_case(field_name)

Lookup with PascalCase or camelCase letter casing first.

This function assumes the dataclass field name is either pascal- or camel- cased.

For a field named ‘myEnvVar’, this tries the following lookups in order:

• myEnvVar, MyEnvVar (camel-case, or pascal-case)

• MY_ENV_VAR (screaming snake-case)

• my_env_var (snake-case)

• Any other variations - i.e. my-env-var, myenvvar

Parameters:

field_name – The dataclass field name to lookup in the environment.

Returns:

The value of the matched environment variable, if one is found in the environment.

dataclass_wizard.environ.lookups.with_screaming_snake_case(field_name)

Lookup with SCREAMING_SNAKE_CASE letter casing first - this is the default lookup.

This function assumes the dataclass field name is lower-cased.

For a field named ‘my_env_var’, this tries the following lookups in order:

• MY_ENV_VAR (screaming snake-case)

• my_env_var (snake-case)

• Any other variations - i.e. MyEnvVar, myEnvVar, myenvvar, my-env-var

Parameters:

field_name – The dataclass field name to lookup in the environment.

Returns:

The value of the matched environment variable, if one is found in the environment.

dataclass_wizard.environ.lookups.with_snake_case(field_name)

Lookup with snake_case letter casing first.

This function assumes the dataclass field name is lower-cased.

For a field named ‘my_env_var’, this tries the following lookups in order:

• my_env_var (snake-case)

• MY_ENV_VAR (screaming snake-case)

• Any other variations - i.e. MyEnvVar, myEnvVar, myenvvar, my-env-var

Parameters:

field_name – The dataclass field name to lookup in the environment.

Returns:

The value of the matched environment variable, if one is found in the environment.

dataclass_wizard.environ.wizard module

class dataclass_wizard.environ.wizard.EnvWizard

Bases: AbstractEnvWizard

Environment Wizard

A mixin class for parsing and managing environment variables in Python.

EnvWizard makes it easy to map environment variables to Python attributes, handle defaults, and optionally load values from .env files.

Quick Example:

import os
from pathlib import Path

class MyConfig(EnvWizard):
    my_var: str
    my_optional_var: int = 42

# Set environment variables
os.environ["MY_VAR"] = "hello"

# Load configuration from the environment
config = MyConfig()
print(config.my_var)  # Output: "hello"
print(config.my_optional_var)  # Output: 42

# Specify configuration explicitly
config = MyConfig(my_var='world')
print(config.my_var)  # Output: "world"
print(config.my_optional_var)  # Output: 42

Example with .env file:

class MyConfigWithEnvFile(EnvWizard):
    class _(EnvWizard.Meta):
        env_file = True  # Defaults to loading from `.env`

    my_var: str
    my_optional_var: int = 42

# Create an `.env` file in the current directory:
# MY_VAR=world
config = MyConfigWithEnvFile()
print(config.my_var)  # Output: "world"
print(config.my_optional_var)  # Output: 42

Key Features:

• Automatically maps environment variables to dataclass fields.

• Supports default values for fields if environment variables are not set.

• Optionally loads environment variables from .env files.

• Supports prefixes for environment variables using _env_prefix or Meta.env_prefix.

• Supports loading secrets from directories using _secrets_dir or Meta.secrets_dir.

• Dynamic reloading with _reload to handle updated environment values.

Initialization Options:

The __init__ method accepts additional parameters for flexibility:

• _env_file (optional):

  Overrides the Meta.env_file value dynamically. Can be a file path, a sequence of file paths, or True to use the default .env file.

• _reload (optional):

  Forces a reload of environment variables to bypass caching. Defaults to False.

• _env_prefix (optional):

  Dynamically overrides Meta.env_prefix, applying a prefix to all environment variables. Defaults to None.

• _secrets_dir (optional):

  Overrides the Meta.secrets_dir value dynamically. Can be a directory path or a sequence of paths pointing to directories containing secret files.

Meta Settings:

These class-level attributes can be configured in a nested Meta class:

• env_file:

  The path(s) to .env files to load. If set to True, defaults to .env.

• env_prefix:

  A prefix applied to all environment variables. Defaults to None.

• secrets_dir:

  A path or sequence of paths to directories containing secret files. Defaults to None.

Attributes:

Defined dynamically based on the dataclass fields in the derived class.

class Meta

Bases: BaseEnvWizardMeta

Inner meta class that can be extended by sub-classes for additional customization with the environment load process.

to_dict(*, cls=None, dict_factory=<class 'dict'>, exclude=None, **kwargs)

Return the fields of an instance of a EnvWizard subclass as a new dictionary mapping field names to field values.

Example usage:

class MyEnv(EnvWizard):
    x: int
    y: str

env = MyEnv()
serialized = asdict(env)

When directly invoking this function, an optional Meta configuration for the EnvWizard subclass can be specified via EnvMeta; by default, this will apply recursively to any nested subclasses. Here’s a sample usage of this below:

>>> EnvMeta(key_transform_with_dump='CAMEL').bind_to(MyClass)
>>> asdict(MyClass(my_str="value"))

If given, ‘dict_factory’ will be used instead of built-in dict. The function applies recursively to field values that are EnvWizard subclasses. This will also look into built-in containers: tuples, lists, and dicts.

Return type:

dict[str, Any]

Parameters:

• o (T)

• exclude (Collection[str] | None)

to_json(*, encoder=<function dumps>, **encoder_kwargs)

Converts the EnvWizard subclass to a JSON string representation.

Module contents