API reference¶
core module¶
Environment variable parser.
- class yaenv.core.Env(envfile: str | PathLike)[source]¶
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 [source]¶
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 [source]¶
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 [source]¶
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]] [source]¶
Iterate through the entries in the dotenv file.
- Returns:
Iterator[tuple[str, str]] – An iterator of key-value pairs.
- __contains__(item: str) bool [source]¶
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 [source]¶
Return the number of environment variables.
- Returns:
int – The number of variables defined in the dotenv file.
- __fspath__() str [source]¶
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 [source]¶
Return a string representing the environment variables.
- Returns:
str – The key-value pairs defined in the dotenv file as lines.
- __repr__() str [source]¶
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 [source]¶
Add the variables defined in the dotenv file to os.environ.
- get(key: str, default: str) str [source]¶
- 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 [source]¶
- 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 thedefault
value.- Raises:
EnvError – If the variable cannot be cast to
bool
.
Examples
>>> env.bool('BOOL_VAR', False) False
- int(key: str, default: int) int [source]¶
- 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 thedefault
value.- Raises:
EnvError – If the variable cannot be cast to
int
.
Examples
>>> env.int('INT_VAR', 10) 10
- float(key: str, default: float) float [source]¶
- 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 thedefault
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 [source]¶
- 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 thedefault
value.
Examples
>>> env.list('LIST_VAR', separator=':') ['item1', 'item2']
- db(key: str, default: str) DBConfig [source]¶
- 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 [source]¶
- 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.
- exception yaenv.core.EnvError[source]¶
Bases:
Exception
Exception class representing a dotenv error.
- class yaenv.core.EnvVar(line: str)[source]¶
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 [source]¶
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, orNone
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 [source]¶
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] [source]¶
Iterate through the tokens of the variable.
- Returns:
Iterator[str] – An iterator containing the key and value.
db module¶
Database URL parser.
- yaenv.db.add_scheme(scheme: str, backend: str) None [source]¶
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 [source]¶
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 [source]¶
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.