typenv

Version 0.1.6

Typed environment variable parsing for Python

Table of Contents generated with mdformat-toc

• Background
• Installing
• Usage
  • Basics
  • Supported types
  • Default values
  • Name prefixes
  • Name character set
  • Name uppercasing
  • Validation
  • Reading from a .env file
  • Dumping parsed values
• Acknowledgments

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 or decimal.Decimal
• env.bytes

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

export SOME_STR=blaablaa
export SOME_INT=99

from typenv import Env, ParsedValue

env = Env()

SOME_STR = env.str("SOME_STR")
SOME_INT = env.int("SOME_INT")

assert env.dump() == {
    "SOME_INT": ParsedValue(value=99, type="int", optional=False),
    "SOME_STR": ParsedValue(value="blaablaa", type="str", optional=False),
}

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.