Typed environment variable parsing for Python
Project description
typenv
Version 0.1.4
Typed environment variable parsing for Python
Background
Typenv does environment variable parsing with an API almost identical to the excellent environs. There are a few reasons why typenv might be preferred:
- Type annotated typecast functions: type checkers are able to understand types of parsed environment variables.
- More flexible prefix manipulation of environment variable names.
- Validation of environment variable names.
- Optional automatic uppercasing of environment variable names.
- Ability to generate a .env.example that shows expected types of environment variables.
- Less dependencies. No marshmallow required.
Installing
Installing from PyPI repository (https://pypi-hypernode.com/project/typenv):
pip install typenv
Usage
Basics
Set environment variables:
export NAME='Harry Potter'
export AGE=14
export IS_WIZARD=true
export PATRONUM_SUCCESS_RATE=0.92
export BANK_BALANCE=134599.01
export LUCKY_NUMBERS=7,3,11
export EXTRA_DETAILS='{"friends": ["Hermione", "Ron"]}'
Parse the values in Python:
from typenv import Env
env = Env()
NAME = env.str("NAME") # => "Harry Potter"
AGE = env.int("AGE") # => 14
IS_WIZARD = env.bool("IS_WIZARD") # => True
PATRONUM_SUCCESS_RATE = env.float("PATRONUM_SUCCESS_RATE") # => 0.92
BANK_BALANCE = env.decimal("BANK_BALANCE") # => decimal.Decimal("134599.01")
LUCKY_NUMBERS = env.list("LUCKY_NUMBERS", subcast=int) # => [7, 3, 11]
EXTRA_DETAILS = env.json("EXTRA_DETAILS") # => {"friends": ["Hermione", "Ron"]}
# Optional settings must have a default value
IS_DEATH_EATER = env.bool("IS_DEATH_EATER", default=False) # => False
Supported types
The types supported by typenv are:
env.str
env.int
env.bool
env.float
env.decimal
env.json
env.list
- Takes a subcast argument for casting list items to one of
str
,int
,bool
,float
ordecimal.Decimal
- Takes a subcast argument for casting list items to one of
Default values
Normally, if an environment variable is not found, typenv raises an exception. If a default value is provided, however, that will be returned instead of raising.
from typenv import Env
env = Env()
BOOL = env.bool("NON_EXISTING_NAME", default=False) # => False
LIST = env.list("NON_EXISTING_NAME", default=["a", "b"]) # => ["a", "b"]
OPTIONAL_INT = env.int("NON_EXISTING_NAME", default=None) # => None
Name prefixes
TODO: document here
Name character set
Typenv validates environment variable names. By default, the set of allowed characters includes upper case ASCII letters, digits and the underscore (_
).
The set of allowed characters can be configured:
from typenv import Env
env = Env(allowed_chars="ABCDEFGHIJKLMNOPQRSTUVWXYZ")
Name uppercasing
export UPPER_CASE_NAME=true
from typenv import Env
# Environment variable names in type cast methods will automatically be upper
# cased when `upper=True` is set here.
env = Env(upper=True)
NAME = env.bool("upper_casE_Name")
Validation
export NAME='Harry Potter'
export AGE=14
from typenv import Env
env = Env()
# A single validator function
NAME = env.str("NAME", validate=lambda n: n.startswith("Harry"))
# A validator function can signal error by raising an exception
def is_positive(num):
if num <= 0:
raise Exception("Number is not positive")
# A validator function can alternatively return `False` to signal an error
def is_less_than_thousand(num):
if num >= 1000:
return False
return True
# Multiple validator functions can be passed as an iterable of callables
AGE = env.int("AGE", validate=(is_positive, is_less_than_thousand))
Reading from a .env
file
TODO: document here
Dumping parsed values
TODO: document here
Acknowledgments
The public API of this library is almost an exact copy of environs, which is based on envparse and django-environ. Credit for the interface goes to the authors of those libraries.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.