API reference

core module

Environment variable parser.

class yaenv.core.Env(envfile: Union[str, PathLike])

Bases: PathLike

Class used to parse dotenv files and access their variables.

Variables

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

• envfile (Union[str, os.PathLike]) – The dotenv file of the object.

Parameters

envfile (Union[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.

vars

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) → Optional[str]

Return an environment variable or a default value.

Parameters

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

• default (Optional[str]) – The default value.

Returns

Optional[str] – 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) → Optional[bool]

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

Parameters

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

• default (Optional[bool]) – The default value.

Returns

Optional[bool] – 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) → Optional[int]

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

Parameters

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

• default (Optional[int]) – The default value.

Returns

Optional[int] – 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) → Optional[float]

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

Parameters

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

• default (Optional[float]) – The default value.

Returns

Optional[float] – 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 = ',') → Optional[List]

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

Parameters

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

• default (Optional[List]) – The default value.

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

Returns

Optional[List] – 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) → Optional[DBConfig]

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

Parameters

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

• default (Optional[str]) – The default (unparsed) value.

Returns

Optional[db.DBConfig] – 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) → Optional[EmailConfig]

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

Parameters

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

• default (Optional[str]) – The default (unparsed) value.

Returns

Optional[email.EmailConfig] – 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) → Optional[EnvVar]

Parse a line and return a new instance or None.

Parameters

line (str) – The line to be parsed.

Returns

Optional[EnvVar] – Returns 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.

__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

Useful 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