Source code for yaenv.core

"""Environment variable parser."""

from __future__ import annotations

from functools import cached_property
from os import PathLike, environ, fspath, path
from re import Match, compile as regex
from secrets import token_urlsafe
from shlex import shlex
from shutil import move
from tempfile import mkstemp
from typing import Iterator, Literal, overload

from . import db, email, utils


[docs] class EnvError(Exception): """Exception class representing a dotenv error."""
[docs] class EnvVar: """ Class that represents an environment variable. Attributes ---------- key : str The key of the variable. value : str The value of the variable. """ _interpolate: bool key: str value: str
[docs] def __new__(cls, line: str) -> EnvVar | None: # type: ignore """ 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 """ lex = shlex(line) key = lex.read_token() if not key: return None # invalid key if ( not all(c in lex.wordchars for c in key) or lex.get_token() != '=' or key == '_' or key[0] in '0123456789' ): raise EnvError(f'Invalid key in line: {line}') lex.whitespace_split = True try: value = lex.read_token() except ValueError as e: raise EnvError(f'Mismatched quotes in line: {line}') from e # surplus token after value if lex.read_token(): raise EnvError(f'Surplus token in line: {line}') instance = super(EnvVar, cls).__new__(cls) instance.key = key # blank value if not value: instance.value = '' instance._interpolate = False return instance # double-quoted value if value[0] == '"' or value[-1] == '"': if not value[0] == value[-1]: raise EnvError(f'Mismatched quotes in line: {line}') instance.value = value[1:-1] instance._interpolate = True return instance # single-quoted value if value[0] == "'" or value[-1] == "'": if not value[0] == value[-1]: raise EnvError(f'Mismatched quotes in line: {line}') instance.value = value[1:-1] instance._interpolate = False return instance instance.value = value instance._interpolate = True return instance
[docs] def __bool__(self) -> bool: """ Return whether the variable can be interpolated or not. Returns ------- bool ``True`` unless the value is blank or enclosed in single quotes. """ return self._interpolate
[docs] def __iter__(self) -> Iterator[str]: """ Iterate through the tokens of the variable. Returns ------- Iterator[str] An iterator containing the key and value. """ yield self.key yield self.value
[docs] def __len__(self) -> 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. """ if self is None: return 0 if not self.value: return 1 return 2
[docs] def __str__(self) -> str: # pragma: no cover """ Return the variable as a string. Returns ------- str The value of the variable. """ return self.value
[docs] def __repr__(self) -> str: # pragma: no cover """ Return a string representing the object. Returns ------- str A string that shows the key and value of the variable. """ return f"EnvVar('{self.key}', '{self.value}')"
[docs] class Env(PathLike): """ Class used to parse dotenv files and access their variables. Attributes ---------- 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') """ def __init__(self, envfile: str | PathLike) -> None: if not path.isfile(envfile): raise EnvError(f"File '{envfile}' does not exist") self.envfile = envfile self.ENV = environ
[docs] def __getitem__(self, 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. """ value = self.ENV.get(key, self.vars.get(key)) if value is None: raise EnvError(f"Missing environment variable: '{key}'") return value
[docs] def __setitem__(self, 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``. """ self.vars[key] = value self._replace(key, value)
[docs] def __delitem__(self, key: str) -> None: """ Unset an environment variable. Parameters ---------- key : str The name of the variable. Raises ------ EnvError If the variable is not set. """ try: del self.vars[key] except KeyError: raise EnvError(f"Missing environment variable: '{key}'") else: self._replace(key, None)
[docs] def __iter__(self) -> Iterator[tuple[str, str]]: """ Iterate through the entries in the dotenv file. Returns ------- Iterator[tuple[str, str]] An iterator of key-value pairs. """ yield from self.vars.items()
[docs] def __contains__(self, 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. """ return item in self.vars
[docs] def __len__(self) -> int: """ Return the number of environment variables. Returns ------- int The number of variables defined in the dotenv file. """ return len(self.vars)
[docs] def __fspath__(self) -> str: """ Return the file system representation of the object. This method is used by :os:`fspath`. Returns ------- str The path of the dotenv file. """ return fspath(self.envfile)
[docs] def __str__(self) -> str: # pragma: no cover """ Return a string representing the environment variables. Returns ------- str The key-value pairs defined in the dotenv file as lines. """ return '\n'.join(f'{k}="{v}"' for k, v in self)
[docs] def __repr__(self) -> str: # pragma: no cover """ Return a string representing the object. Returns ------- str A string that shows the path of the dotenv file. """ return f"Env('{self.envfile}')"
@cached_property def vars(self) -> dict[str, str]: """`dict[str, str]` : Get the environment variables as a ``dict``.""" def _sub_callback(match: Match) -> str: return (self.ENV | result).get(match.group(1), '') with open(self.envfile, 'r') as f: envvars = list(filter(EnvVar.__len__, map(EnvVar, f.readlines()))) result = dict(envvars) # type: ignore # substitute variables that can be interpolated posix = regex(r'\$\{([^}].*)?\}') for var in filter(bool, envvars): result[var.key] = posix.sub(_sub_callback, var.value) return result
[docs] def setenv(self) -> None: """Add the variables defined in the dotenv file to :os:`environ`.""" self.ENV |= self.vars
@overload def get(self, key: str, default: str) -> str: ... @overload def get(self, key: str, default: None = None) -> str | None: ...
[docs] def get(self, key: str, default: str | 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' """ return self.ENV.get(key, self.vars.get(key) or default)
@overload def bool(self, key: str, default: bool) -> bool: ... @overload def bool(self, key: str, default: None = None) -> bool | None: ...
[docs] def bool(self, key: str, default: bool | 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 """ value = self.get(key) if value is None: return default if utils.is_truthy(value): return True if utils.is_falsy(value): return False raise EnvError(f"Invalid boolean value: '{value}'")
@overload def int(self, key: str, default: int) -> int: ... @overload def int(self, key: str, default: None = None) -> int | None: ...
[docs] def int(self, key: str, default: int | 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 """ value = self.get(key) if value is None: return default try: return int(value) except ValueError: raise EnvError(f"Invalid integer value: '{value}'")
@overload def float(self, key: str, default: float) -> float: ... @overload def float(self, key: str, default: None = None) -> float | None: ...
[docs] def float(self, key: str, default: float | 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 """ value = self.get(key) if value is None: return default try: return float(value) except ValueError: raise EnvError(f"Invalid numerical value: '{value}'")
@overload def list(self, key: str, default: list, separator: str = ...) -> list: ... @overload def list(self, key: str, default: None = None, separator: str = ...) -> list | None: ...
[docs] def list(self, key: str, default: list | 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'] """ value = self.get(key) if value is None: return default return value.split(separator)
@overload def db(self, key: str, default: str) -> db.DBConfig: ... @overload def db(self, key: str, default: None = None) -> db.DBConfig | None: ...
[docs] def db(self, key: str, default: str | None = None) -> db.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 -------- :meth:`yaenv.db.parse` : Database URL parser. """ value = self.get(key, default) if value is None: return None try: return db.parse(value) except Exception as e: raise EnvError(f"Invalid database URL: '{value}'") from e
@overload def email(self, key: str, default: str) -> email.EmailConfig: ... @overload def email(self, key: str, default: None = None ) -> email.EmailConfig | None: ...
[docs] def email(self, key: str, default: str | None = None) -> email.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 -------- :meth:`yaenv.email.parse` : E-mail URL parser. """ value = self.get(key, default) if value is None: return None try: return email.parse(value) except Exception as e: raise EnvError(f"Invalid e-mail URL: '{value}'") from e
[docs] def secret(self, 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. """ value = self.get(key) if value is None: value = token_urlsafe(37) self[key] = value return value
def _replace(self, key: str, value: str | None) -> None: target = mkstemp(prefix='yaenv')[-1] pattern = regex(fr'^\s*{key}\s*=') replaced = value is None # can't replace if there's no value if value is not None: value = value.replace('"', '\\"') \ .replace('\n', '\\n').replace('\t', '\\t') newline = f'{key}="{value}"\n' with open(target, 'w') as tf, open(self.envfile, 'r') as sf: for line in sf: if not pattern.match(line): tf.write(line) elif value is not None: tf.write(newline) replaced = True if not replaced: if not line[-1] == '\n': tf.write('\n') # ensure new line tf.write(newline) move(target, self.envfile)
__all__ = ['Env', 'EnvError', 'EnvVar']