API reference

core module

Environment variable parser.

class yaenv.core.Env(envfile: str | PathLike)

Bases: PathLike

Class used to parse dotenv files and access their variables.

Variables:

• ENV (os._Environ) – A reference to os.environ.

• envfile (str | os.PathLike) – The dotenv file of the object.

Parameters:

envfile (str | os.PathLike) – The path to a dotenv file.

Examples

>>> print(open('.env').read())
STR_VAR=value
LIST_VAR=item1:item2
SECRET_KEY=notsosecret
>>> env = Env('.env')

__getitem__(key: str) → str

Return an environment variable that cannot be missing.

Parameters:

key (str) – The name of the variable.

Returns:

str – The value of the variable as str.

Raises:

EnvError – If the environment variable is missing.

__setitem__(key: str, value: str) → None

Set an environment variable.

Parameters:

• key (str) – The name of the variable.

• value (str) – The value of the variable as str.

__delitem__(key: str) → None

Unset an environment variable.

Parameters:

key (str) – The name of the variable.

Raises:

EnvError – If the variable is not set.

__iter__() → Iterator[tuple[str, str]]

Iterate through the entries in the dotenv file.

Returns:

Iterator[tuple[str, str]] – An iterator of key-value pairs.

__contains__(item: str) → bool

Check whether a variable is defined in the dotenv file.

Parameters:

item (str) – The name of the variable.

Returns:

bool – True if the variable is defined.

__len__() → int

Return the number of environment variables.

Returns:

int – The number of variables defined in the dotenv file.

__fspath__() → str

Return the file system representation of the object.

This method is used by os.fspath.

Returns:

str – The path of the dotenv file.

__str__() → str

Return a string representing the environment variables.

Returns:

str – The key-value pairs defined in the dotenv file as lines.

__repr__() → str

Return a string representing the object.

Returns:

str – A string that shows the path of the dotenv file.

property vars: dict[str, str]

Get the environment variables as a dict.

Type:

dict[str, str]

setenv() → None

Add the variables defined in the dotenv file to os.environ.

get(key: str, default: str) → str

get(key: str, default: None = None) → str | None

Return an environment variable or a default value.

Parameters:

• key (str) – The name of the variable.

• default (str | None) – The default value.

Returns:

str | None – The value of the variable or the default value.

Examples

>>> env.get('STR_VAR', 'default')
'value'

bool(key: str, default: bool) → bool

bool(key: str, default: None = None) → bool | None

Return an environment variable as a bool, or a default value.

Parameters:

• key (str) – The name of the variable.

• default (bool | None) – The default value.

Returns:

bool | None – The bool value of the variable or the default value.

Raises:

EnvError – If the variable cannot be cast to bool.

Examples

>>> env.bool('BOOL_VAR', False)
False

int(key: str, default: int) → int

int(key: str, default: None = None) → int | None

Return an environment variable as an int, or a default value.

Parameters:

• key (str) – The name of the variable.

• default (int | None) – The default value.

Returns:

int | None – The int value of the variable or the default value.

Raises:

EnvError – If the variable cannot be cast to int.

Examples

>>> env.int('INT_VAR', 10)
10

float(key: str, default: float) → float

float(key: str, default: None = None) → float | None

Return an environment variable as a float, or a default value.

Parameters:

• key (str) – The name of the variable.

• default (float | None) – The default value.

Returns:

float | None – The float value of the variable or the default value.

Raises:

EnvError – If the variable cannot be cast to float.

Examples

>>> env.float('FLOAT_VAR', 0.3)
0.3

list(key: str, default: list, separator: str = ',') → list

list(key: str, default: None = None, separator: str = ',') → list | None

Return an environment variable as a list, or a default value.

Parameters:

• key (str) – The name of the variable.

• default (list | None) – The default value.

• separator (str) – The separator to use when splitting the list.

Returns:

list | None – The list value of the variable or the default value.

Examples

>>> env.list('LIST_VAR', separator=':')
['item1', 'item2']

db(key: str, default: str) → DBConfig

db(key: str, default: None = None) → DBConfig | None

Return a dictionary that can be used for Django’s database settings.

Parameters:

• key (str) – The name of the variable.

• default (str | None) – The default (unparsed) value.

Returns:

db.DBConfig | None – A database config object for Django.

Raises:

EnvError – If the variable cannot be parsed.

See also

yaenv.db.parse()

Database URL parser.

email(key: str, default: str) → EmailConfig

email(key: str, default: None = None) → EmailConfig | None

Return a dictionary that can be used for Django’s e-mail settings.

Parameters:

• key (str) – The name of the variable.

• default (str | None) – The default (unparsed) value.

Returns:

email.EmailConfig | None – An e-mail config object for Django.

Raises:

EnvError – If the variable cannot be parsed.

See also

yaenv.email.parse()

E-mail URL parser.

secret(key: str = 'SECRET_KEY') → str

Return a cryptographically secure secret key.

If the key is empty, it is generated and saved.

Parameters:

key (str) – The name of the key.

Returns:

str – The value of the key or a random string.

exception yaenv.core.EnvError

Bases: Exception

Exception class representing a dotenv error.

class yaenv.core.EnvVar(line: str)

Bases: object

Class that represents an environment variable.

Variables:

• key (str) – The key of the variable.

• value (str) – The value of the variable.

static __new__(cls, line: str) → EnvVar | None

Parse a line and return a new instance or None.

Parameters:

line (str) – The line to be parsed.

Returns:

EnvVar | None – A new EnvVar if all went well, or None if the line doesn’t contain a variable declaration.

Raises:

EnvError – If the line cannot be parsed.

Examples

>>> print(repr(EnvVar('example=???')))
EnvVar('example', '???')
>>> print(repr(EnvVar('# comment')))
None

__bool__() → bool

Return whether the variable can be interpolated or not.

Returns:

bool – True unless the value is blank or enclosed in single quotes.

__iter__() → Iterator[str]

Iterate through the tokens of the variable.

Returns:

Iterator[str] – An iterator containing the key and value.

__len__() → Literal[0, 1, 2]

Return a number which represents the state of the EnvVar.

Returns:

Literal[0, 1, 2] – 0 if the EnvVar is None, 1 if the value is blank, or 2 otherwise.

__str__() → str

Return the variable as a string.

Returns:

str – The value of the variable.

__repr__() → str

Return a string representing the object.

Returns:

str – A string that shows the key and value of the variable.

db module

Database URL parser.

yaenv.db.add_scheme(scheme: str, backend: str) → None

Extend the dictionary of supported schemes.

Parameters:

• scheme (int) – The scheme of the database.

• backend (str) – The backend of the database.

Examples

>>> add_scheme('mysql-connector', 'mysql.connector.django')

yaenv.db.parse(url: str) → DBConfig

Parse a database URL.

Parameters:

url (str) – The database URL to be parsed.

Returns:

DBConfig – A dictionary that can be used in django.settings.DATABASES.

Examples

>>> parse('mysql://user:pass@127.0.0.1:3306/django')
{
    'ENGINE': 'django.db.backends.mysql',
    'NAME': 'django',
    'USER': 'user',
    'PASSWORD': 'pass',
    'HOST': '127.0.0.1',
    'PORT': '3306',
    'OPTIONS': {}
}

class yaenv.db.DBConfig

Type representing a database config object.

email module

E-mail URL parser.

yaenv.email.parse(url: str) → EmailConfig

Parse an e-mail URL.

Parameters:

url (str) – The e-mail URL to be parsed.

Returns:

EmailConfig – A dictionary that can be used in django.settings.EMAIL_*.

Examples

>>> parse('smtp+tls://user:pass@example.com')
{
    'EMAIL_BACKEND': 'django.core.mail.backends.smtp.EmailBackend',
    'EMAIL_HOST_USER': 'user',
    'EMAIL_HOST_PASSWORD': 'pass',
    'EMAIL_HOST': 'example.com',
    'EMAIL_USE_TLS': True,
    'EMAIL_PORT': 587
}

class yaenv.email.EmailConfig

Type representing an e-mail config object.

utils module

Miscellaneous utilities.

yaenv.utils.is_truthy(arg: Any) → bool

Check if the given argument is truthy.

Parameters:

arg (Any) – The argument to check.

Returns:

bool – True if arg is truthy.

Examples

>>> is_truthy('ON')
True
>>> is_truthy(10)
False

yaenv.utils.is_falsy(arg: Any) → bool

Check if the given argument is falsy.

Parameters:

arg (Any) – The argument to check.

Returns:

bool – True if arg is falsy.

Examples

>>> is_falsy('NO')
True
>>> is_falsy(-1)
False