typed_envs package

Submodules

typed_envs.ENVIRONMENT_VARIABLES module

typed_envs.factory module

class typed_envs.factory.EnvVarFactory[source]

Bases: object

Factory for creating EnvironmentVariable instances with optional prefix.

__init__(env_var_prefix=None)[source]

Initializes the EnvVarFactory with an optional prefix for environment variables.

Parameters:

env_var_prefix (str | None) – An optional string prefix to be added to environment variable names.

Return type:

None

create_env(env_var_name, env_var_type, default, *init_args, string_converter=None, verbose=True, **init_kwargs)[source]

Creates a new EnvironmentVariable object with the specified parameters.

Typing note:

Mypy cannot natively model the dynamic subclass created by typed_envs. If you want mypy to treat EnvironmentVariable[T] as having the methods and attributes of both EnvironmentVariable and the underlying T, enable the typed_envs mypy plugin in your config:

[mypy] plugins = typed_envs.mypy_plugin

Parameters:

  • env_var_name (str) – The name of the environment variable.

  • env_var_type (type[T]) – The type of the environment variable.

  • default (Any) – The default value for the environment variable.

  • *init_args (Any) – Additional positional arguments for initialization.

  • string_converter (Callable[[str], Any] | None) – An optional callable to convert the string value from the environment.

  • verbose (bool) – If True, logs the environment variable details.

  • **init_kwargs (Any) – Additional keyword arguments for initialization.

Returns:

An instance of EnvironmentVariable with the specified type and value.

Return type:

EnvironmentVariable[T]

Example

Create an environment variable with an integer type using an EnvVarFactory instance:

```python from typed_envs.factory import EnvVarFactory factory = EnvVarFactory() some_var = factory.create_env(“SET_WITH_THIS_ENV”, int, 10)

>>> isinstance(some_var, int)
True
>>> isinstance(some_var, EnvironmentVariable)
True
```

Differences between some_var and int(10): - some_var will type check as both int and EnvironmentVariable. - some_var.__repr__() includes contextual information about the EnvironmentVariable.

`python >>> some_var <EnvironmentVariable[name=`SET_WITH_THIS_ENV`, type=int, default_value=10, current_value=10, using_default=True]> >>> str(some_var) "10" >>> some_var + 5 15 >>> 20 / some_var 2 `

See also

register_string_converter(register_for, converter)[source]
Parameters:
Return type:

None

__dict__ = mappingproxy({'__module__': 'typed_envs.factory', '__firstlineno__': 14, '__doc__': 'Factory for creating :class:`EnvironmentVariable` instances with optional prefix.', '__init__': <function EnvVarFactory.__init__>, 'default_string_converters': <property object>, 'use_prefix': <property object>, 'create_env': <function EnvVarFactory.create_env>, 'register_string_converter': <function EnvVarFactory.register_string_converter>, '__static_attributes__': ('__default_string_converters', '__use_prefix', 'prefix'), '__dict__': <attribute '__dict__' of 'EnvVarFactory' objects>, '__weakref__': <attribute '__weakref__' of 'EnvVarFactory' objects>, '__annotations_cache__': {'prefix': 'Final', '__use_prefix': 'Final', '__default_string_converters': 'Final[dict[type, StringConverter]]'}})
__firstlineno__ = 14
__module__ = 'typed_envs.factory'
__static_attributes__ = ('__default_string_converters', '__use_prefix', 'prefix')
__weakref__

list of weak references to the object

property default_string_converters: dict[type, Callable[[str], Any]]
property use_prefix: bool
typed_envs.factory.__annotate__(format, /)

typed_envs.mypy_plugin module

typed_envs.registry module

typed_envs.typing module

Module contents

class typed_envs.EnvVarFactory[source]

Bases: object

Factory for creating EnvironmentVariable instances with optional prefix.

__init__(env_var_prefix=None)[source]

Initializes the EnvVarFactory with an optional prefix for environment variables.

Parameters:

env_var_prefix (str | None) – An optional string prefix to be added to environment variable names.

Return type:

None

create_env(env_var_name, env_var_type, default, *init_args, string_converter=None, verbose=True, **init_kwargs)[source]

Creates a new EnvironmentVariable object with the specified parameters.

Typing note:

Mypy cannot natively model the dynamic subclass created by typed_envs. If you want mypy to treat EnvironmentVariable[T] as having the methods and attributes of both EnvironmentVariable and the underlying T, enable the typed_envs mypy plugin in your config:

[mypy] plugins = typed_envs.mypy_plugin

Parameters:

  • env_var_name (str) – The name of the environment variable.

  • env_var_type (type[T]) – The type of the environment variable.

  • default (Any) – The default value for the environment variable.

  • *init_args (Any) – Additional positional arguments for initialization.

  • string_converter (Callable[[str], Any] | None) – An optional callable to convert the string value from the environment.

  • verbose (bool) – If True, logs the environment variable details.

  • **init_kwargs (Any) – Additional keyword arguments for initialization.

Returns:

An instance of EnvironmentVariable with the specified type and value.

Return type:

EnvironmentVariable[T]

Example

Create an environment variable with an integer type using an EnvVarFactory instance:

```python from typed_envs.factory import EnvVarFactory factory = EnvVarFactory() some_var = factory.create_env(“SET_WITH_THIS_ENV”, int, 10)

>>> isinstance(some_var, int)
True
>>> isinstance(some_var, EnvironmentVariable)
True
```

Differences between some_var and int(10): - some_var will type check as both int and EnvironmentVariable. - some_var.__repr__() includes contextual information about the EnvironmentVariable.

`python >>> some_var <EnvironmentVariable[name=`SET_WITH_THIS_ENV`, type=int, default_value=10, current_value=10, using_default=True]> >>> str(some_var) "10" >>> some_var + 5 15 >>> 20 / some_var 2 `

See also

register_string_converter(register_for, converter)[source]
Parameters:
Return type:

None

__annotations_cache__ = {'__default_string_converters': 'Final[dict[type, StringConverter]]', '__use_prefix': 'Final', 'prefix': 'Final'}
__dict__ = mappingproxy({'__module__': 'typed_envs.factory', '__firstlineno__': 14, '__doc__': 'Factory for creating :class:`EnvironmentVariable` instances with optional prefix.', '__init__': <function EnvVarFactory.__init__>, 'default_string_converters': <property object>, 'use_prefix': <property object>, 'create_env': <function EnvVarFactory.create_env>, 'register_string_converter': <function EnvVarFactory.register_string_converter>, '__static_attributes__': ('__default_string_converters', '__use_prefix', 'prefix'), '__dict__': <attribute '__dict__' of 'EnvVarFactory' objects>, '__weakref__': <attribute '__weakref__' of 'EnvVarFactory' objects>, '__annotations_cache__': {'prefix': 'Final', '__use_prefix': 'Final', '__default_string_converters': 'Final[dict[type, StringConverter]]'}})
__firstlineno__ = 14
__module__ = 'typed_envs.factory'
__static_attributes__ = ('__default_string_converters', '__use_prefix', 'prefix')
__weakref__

list of weak references to the object

property default_string_converters: dict[type, Callable[[str], Any]]
prefix: Final
property use_prefix: bool
final class typed_envs.EnvironmentVariable[source]

Bases: Generic[T]

Base class for creating custom wrapper subclasses on the fly.

Note

This is just a base class used to create custom wrapper subclasses on the fly. You must never initialize these directly. You must use the create_env() function either on the main module or on an EnvVarFactory to initialize your env vars.

Example

Useful for enhancing type hints and __repr__ of variables that hold values you set with env vars. Note: This is just a helper class to create custom wrapper classes on the fly. You should never initialize these directly.

Functionally, EnvironmentVariable objects will work exactly the same as any instance of specified typ.

In the example below, some_var can be used just like any other int object.

import typed_envs
some_var = typed_envs.create_env("SET_WITH_THIS_ENV", int, 10)

>>> isinstance(some_var, int)
True
>>> isinstance(some_var, EnvironmentVariable)
True

There are only 2 differences between some_var and int(10): - some_var will properly type check as an instance of both int and EnvironmentVariable - some_var.__repr__() will include contextual information about the EnvironmentVariable.

>>> some_var
EnvironmentVariable[int](name=`SET_WITH_THIS_ENV`, default_value=10, using_default=True)
>>> str(some_var)
"10"
>>> some_var + 5
15
>>> 20 / some_var
2

See also

create_env(), EnvVarFactory

classmethod __class_getitem__(type_arg)[source]
Returns a mixed subclass of type_arg and EnvironmentVariable that does 2 things:

  • modifies the __repr__ method so its clear an object’s value was set with an env var while when inspecting variables

  • ensures the instance will type check as an EnvironmentVariable object without losing information about its actual type

Aside from these two things, subclass instances will function exactly the same as any other instance of typ.

Parameters:

type_arg (type[T])

Return type:

type[EnvironmentVariable[T]]

classmethod __init_subclass__()

Function to initialize subclasses.

__annotate_func__()

The type of the None singleton.

__init__(*args, **kwargs)[source]
Parameters:
Return type:

None

__int__()[source]
Return type:

int

__repr__()[source]

Return repr(self).

Return type:

str

__str__()[source]

Return str(self).

Return type:

str

__args__: ClassVar[type[object]]
__dict__ = mappingproxy({'__module__': 'typed_envs._env_var', '__firstlineno__': 11, '__doc__': '\nBase class for creating custom wrapper subclasses on the fly.\n\nNote:\n    This is just a base class used to create custom wrapper subclasses on the fly.\n    You must never initialize these directly.\n    You must use the :func:`create_env` function either on the main module or on an :class:`EnvVarFactory` to initialize your env vars.\n\nExample:\n    Useful for enhancing type hints and __repr__ of variables that hold values you set with env vars.\n    Note: This is just a helper class to create custom wrapper classes on the fly.\n    You should never initialize these directly.\n\n    Functionally, :class:`EnvironmentVariable` objects will work exactly the same as any instance of specified `typ`.\n\n    In the example below, `some_var` can be used just like any other `int` object.\n\n    .. code-block:: python\n\n        import typed_envs\n        some_var = typed_envs.create_env("SET_WITH_THIS_ENV", int, 10)\n\n        >>> isinstance(some_var, int)\n        True\n        >>> isinstance(some_var, EnvironmentVariable)\n        True\n\n    There are only 2 differences between `some_var` and `int(10)`:\n    - `some_var` will properly type check as an instance of both `int` and :class:`EnvironmentVariable`\n    - `some_var.__repr__()` will include contextual information about the :class:`EnvironmentVariable`.\n\n    .. code-block:: python\n\n        >>> some_var\n        EnvironmentVariable[int](name=`SET_WITH_THIS_ENV`, default_value=10, using_default=True)\n        >>> str(some_var)\n        "10"\n        >>> some_var + 5\n        15\n        >>> 20 / some_var\n        2\n\nSee Also:\n    :func:`create_env`, :class:`EnvVarFactory`\n', '__init__': <function EnvironmentVariable.__init__>, '__str__': <function EnvironmentVariable.__str__>, '__repr__': <function EnvironmentVariable.__repr__>, '__class_getitem__': <classmethod(<function EnvironmentVariable.__class_getitem__>)>, '__int__': <function EnvironmentVariable.__int__>, '__static_attributes__': (), '__orig_bases__': (typing.Generic[~T],), '__dict__': <attribute '__dict__' of 'EnvironmentVariable' objects>, '__weakref__': <attribute '__weakref__' of 'EnvironmentVariable' objects>, '__parameters__': (~T,), '__final__': True, '__annotations_cache__': {'_default_value': typing.Any, '_using_default': <class 'bool'>, '_env_name': <class 'str'>, '_init_arg0': typing.Any, '__args__': typing.ClassVar[type[object]], '__origin__': typing.ClassVar[type['EnvironmentVariable[Any]']]}})
__final__ = True
__firstlineno__ = 11
__module__ = 'typed_envs._env_var'
__orig_bases__ = (typing.Generic[~T],)
__origin__: ClassVar[type[EnvironmentVariable[Any]]]
__parameters__ = (~T,)
__static_attributes__ = ()
__weakref__

list of weak references to the object

typed_envs.create_env(name, typ, default, *init_args, string_converter=None, verbose=True, **init_kwargs)