Typed environment variable parsing for Python
Project description
typenv
Version 0.1.5
Typed environment variable parsing for Python
Table of Contents generated with mdformat-toc
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.