core.env

core.env.find_dotenvs(filename: str = '.env', start_path: Path | None = None) → list[Path]

Find all dotenv files named filename in the start directory and every parent directory up to the filesystem root.

Unlike dotenv.find_dotenv(), which stops at the first match, this function collects all matches along the directory tree, using dotenv.find_dotenv() to resolve the starting directory.

Parameters:

• filename – dotenv filename to look for (default: '.env').

• usecwd – if True (default), start from the current working directory. Ignored when start_path is provided. Note: unlike dotenv.find_dotenv(), usecwd=False here is equivalent to usecwd=True because find_dotenv would otherwise use this module’s frame, not the caller’s.

• start_path – explicit starting directory, takes priority over usecwd.

Returns:

List of Path objects for every dotenv file found, ordered from closest (start directory) to farthest (root).

core.env.getdir(envvar: str, default: Path | None = None, create: bool | None = None) → Path

Returns the value of environment variable envvar, assumed to represent a directory path. If this variable is not defined, returns default.

The environment variable can be defined in the users .bashrc, or in a file .env in the current working directory.

Parameters:

• envvar – the input environment variable

• default –

  the default path, if the environment variable is not defined default values are predefined for the following variables:

  • DIR_DATA : “data” (in current working directory)

  • DIR_STATIC : DIR_DATA/”static”

  • DIR_SAMPLES : DIR_DATA/”sample_products”

  • DIR_ANCILLARY : DIR_DATA/”ancillary”

• create – whether to silently create the directory if it does not exist. If not provided this parameter defaults to False except for DIR_STATIC, DIR_SAMPLES and DIR_ANCILLARY.

Returns:

the path to the directory.

core.env.getvar(envvar: str, default: str | None = None) → str

Returns the value of environment variable envvar. If this variable is not defined, returns default.

The environment variable can be defined in the users .bashrc, or in a file .env in the current working directory.

Parameters:

• envvar – the input environment variable

• default – the default return, if the environment variable is not defined

Returns:

the requested environment variable or the default if the var is not defined and a default has been provided.

core.env.load_dotenvs(filename: str = '.env', start_path: Path | None = None, override: bool = True) → list[Path]

Load all dotenv files found by find_dotenvs(), from the farthest ancestor to the closest directory so that inner .env files take precedence over outer ones.

load_dotenv is called once per file found; variables already present in the environment are only overwritten when override=True (the default here, unlike the dotenv library default, to honour the closest-wins precedence).

Parameters:

• filename – dotenv filename to look for (default: '.env').

• usecwd – if True, start from the current working directory.

• start_path – explicit starting directory.

• override – whether a closer file’s value overrides a value already loaded from a farther file (default: True).

Returns:

The list of dotenv files that were loaded, closest first.