Skip to main content

Typed environment variable parsing for Python

Project description

Build Status codecov.io PyPI version Code style: black

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

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


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

typenv-0.1.5.tar.gz (8.5 kB view details)

Uploaded Source

Built Distribution

typenv-0.1.5-py3-none-any.whl (7.1 kB view details)

Uploaded Python 3

File details

Details for the file typenv-0.1.5.tar.gz.

File metadata

  • Download URL: typenv-0.1.5.tar.gz
  • Upload date:
  • Size: 8.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.1.2 CPython/3.8.0 Linux/5.4.0-48-generic

File hashes

Hashes for typenv-0.1.5.tar.gz
Algorithm Hash digest
SHA256 ff132afa441b366f020f9174855df8a2422e4b4b1f9f6335969a582c8a50f404
MD5 c38ce5e08f8e7441572dbecc2dcc10f4
BLAKE2b-256 f65b493da2ed4da535762d2223f3d7e4ba3aa174806e8c89b2d34e502ba56ef9

See more details on using hashes here.

Provenance

File details

Details for the file typenv-0.1.5-py3-none-any.whl.

File metadata

  • Download URL: typenv-0.1.5-py3-none-any.whl
  • Upload date:
  • Size: 7.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.1.2 CPython/3.8.0 Linux/5.4.0-48-generic

File hashes

Hashes for typenv-0.1.5-py3-none-any.whl
Algorithm Hash digest
SHA256 eb002e7a93a7ab919073e4320c5e1ba14b1d853271d43d9e713dc140a0edaa1f
MD5 daee8c23725c4728c3f4368310cd1880
BLAKE2b-256 76ae49d81f6638e2bb5f5e6ada2029812bce47d454db549681ef8ed53f26ff1e

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page