rics.env.read#

Read environment variables as specific types.

To read typing.Literal values, use rics.types.LiteralHelper.read_env() instead.

Functions

read_bool()

Read bool variable.

read_enum()

Read enum variable.

read_env()

Read and convert an environment variable.

read_float()

Read float variable.

read_int()

Read int variable.

read_str()

Read str variable.
read_bool(var: str, default: bool = False, *, strict: bool = True, split: str | None = None) → bool | list[bool][source]#

Read bool variable.

Parameters:

  • var – Variable to read.

  • default – Default value to use when var is not set (or blank).

  • strict – If False, always fall back to default instead of raising.

  • split – Character to split on. Returns list[bool] when set.

Returns:

A bool value, or a list thereof (if split is set).

Notes

See str_as_bool() for value mapping.

Examples

Basic usage.

>>> import os
>>> os.environ["MY_BOOL"] = "true"
>>> read_bool("MY_BOOL")
True

>>> os.environ["MY_BOOL"] = "0"
>>> read_bool("MY_BOOL")
False

When using strict=False, unmapped values are converted to the default instead of raising.

>>> os.environ["MY_BOOL"] = "not-a-bool"
>>> read_bool("MY_BOOL", default=True, strict=False)
True

When using split, elements are cleaned individually and blank items are skipped.

>>> os.environ["MY_BOOL_LIST"] = "true, 0, no, yes, enable,, false"
>>> read_bool("MY_BOOL_LIST", split=",")
[True, False, False, True, True, False]

Conversion (see str_as_bool) must succeed for all elements, or the default will be returned.

read_enum(var: str, default_or_type: EnumT | type[EnumT], *, split: str | None = None) → EnumT | list[EnumT][source]#

Read enum variable.

This function wraps LiteralHelper.from_enum() and LiteralHelper.read_env().

Parameters:

  • var – Variable to read.

  • default_or_type – Enum type or default enum value. Must be a concrete value (e.g. Animal.dog instead of just Animal) to allow unset or blank var values.

  • split – Character to split on. Returns list[EnumT] when set.

Returns:

An EnumT value, or a list thereof (if split is set).

Raises:

TypeError – If conversion fails.

Examples

Basic usage.

>>> from enum import Enum
>>> class Animal(Enum):
...     cat = "meow"
...     dog = "woof"

Enums are matched by name, never by value.

>>> import os
>>> os.environ["MY_ANIMAL"] = "cat"
>>> read_enum("MY_ANIMAL", Animal)
<Animal.cat: 'meow'>

Input is always cleaned and normalized.

>>> os.environ["MY_ANIMAL"] = " DOG"
>>> read_enum("MY_ANIMAL", Animal)
<Animal.dog: 'woof'>

This also applies when reading multiple enums.

>>> os.environ["MY_ANIMAL_LIST"] = " DOG, cat  , CAT"
>>> read_enum("MY_ANIMAL_LIST", Animal, split=",")
[<Animal.dog: 'woof'>, <Animal.cat: 'meow'>, <Animal.cat: 'meow'>]

Unlike the other functions in this module, read_enum always runs in strict mode. Define a default for when the var is not set or blank by passing concrete value in the second position.

>>> read_enum("MISSING_VARIABLE", Animal.dog)
<Animal.dog: 'woof'>

Unknown values will always raise.

read_env(var: str, converter: Callable[[str], T], default: T, *, strict: bool = True, type_name: str | None = None, split: str | None = None, catch: tuple[type[Exception], ...] | None = None) → T | list[T][source]#

Read and convert an environment variable.

Parameters:

  • var – Variable to read.

  • converter – A callable (str) -> T, where the argument is the environment variable value.

  • default – Default value to use when var is not set (or blank).

  • strict – If False, always fall back to default instead of raising.

  • type_name – Used in error messages. Derive if None.

  • split – Character to split on. Returns list[T] when set.

  • catch – Types to suppress when calling converter. Default is (ValueError, TypeError).

Returns:

A T value, or a list thereof (if split is set).

Raises:

ValueError – If conversion fails.

Notes

If the variable key is unset or the value is empty, the default value is always returned.

read_float(var: str, default: float = 0.0, *, strict: bool = True, split: str | None = None) → float | list[float][source]#

Read float variable.

Parameters:

  • var – Variable to read.

  • default – Default value to use when var is not set (or blank).

  • strict – If False, always fall back to default instead of raising.

  • split – Character to split on. Returns list[float] when set.

Returns:

An float value, or a list thereof (if split is set).

Examples

Basic usage.

>>> import os
>>> os.environ["MY_FLOAT"] = "1.0"
>>> read_float("MY_FLOAT")
1.0

When using strict=False, unmapped values are converted to the default instead of raising.

>>> os.environ["MY_FLOAT"] = "not-a-float"
>>> read_float("MY_FLOAT", strict=False)
0.0

When using split, elements are cleaned individually and blank items are skipped.

>>> os.environ["MY_FLOAT_LIST"] = "0, 1.1, , 5"
>>> read_float("MY_FLOAT_LIST", split=",")
[0.0, 1.1, 5.0]

Conversion must succeed for all elements, or the default will be returned.

read_int(var: str, default: int = 0, *, strict: bool = True, split: str | None = None) → int | list[int][source]#

Read int variable.

Parameters:

  • var – Variable to read.

  • default – Default value to use when var is not set (or blank).

  • strict – If False, always fall back to default instead of raising.

  • split – Character to split on. Returns list[int] when set.

Returns:

An int value, or a list thereof (if split is set).

Examples

Basic usage.

>>> import os
>>> os.environ["MY_INT"] = "1"
>>> read_int("MY_INT")
1

When using strict=False, unmapped values are converted to the default instead of raising.

>>> os.environ["MY_INT"] = "not-an-int"
>>> read_int("MY_INT", strict=False)
0

Note that this includes passing float values, even if the decimal is zero.

>>> os.environ["MY_INT"] = "0.0"
>>> read_int("MY_INT", default=2019, strict=False)
2019

When using split, elements are cleaned individually and blank items are skipped.

>>> os.environ["MY_INT_LIST"] = "0, 1, , 5"
>>> read_int("MY_INT_LIST", split=",")
[0, 1, 5]

Conversion must succeed for all elements, or the default will be returned.

read_str(var: str, default: str = '', *, strict: bool = True, split: str | None = None) → str | list[str][source]#

Read str variable.

Parameters:

  • var – Variable to read.

  • default – Default value to use when var is not set (or blank).

  • strict – If False, always fall back to default instead of raising.

  • split – Character to split on. Returns list[str] when set.

Returns:

An str value, or a list thereof (if split is set).

Examples

Basic usage.

>>> import os
>>> os.environ["MY_STR"] = "  foo "
>>> read_str("MY_STR")
'foo'

Input is stripped and cleaned, returning bare strings. Empty items are discarded when using split.

>>> os.environ["MY_STR_LIST"] = "  foo, , bar "
>>> read_str("MY_STR_LIST", split=",")
['foo', 'bar']

This means that input such as ',  , , ' will return an empty list.