chipenv (0.0.1)

2026-01-04T17:14:45Z

To install the package using pip, run the following command:

pip install --index-url  chipenv

For more information on the PyPI registry, see the documentation.

a lightweight environment variable management library for Python

`chipenv`

A simple but flexible environment loader.

Supports .env file parsing with optional mode suffixes (e.g. .env.production, .env.testing, etc.), lazy loading, and dynamic access.

Features

Mode-based config support (.env.production, .env.testing, etc.)
Access via:
- env["KEY"]
- env.get("KEY", ...)
- env.KEY
Optional type casting (str, bool, list, dict, etc.)
Sane default handling
Does not mutate os.environ

Use cases

Loading .env files in mode-aware Python projects
Separating secrets and configs by deployment context
Dynamically reading values like env.DB_URL, env.get("DEBUG", default=False, cast=cast_bool)
Avoiding os.environ pollution

When to use which class

Environment: default choice for most apps; new instance per config.
EnvShared: use when you want a single shared instance across the process (legacy singleton behavior).
TestEnv: use for tests/fixtures when you want to inject a dict and skip file I/O.

Basic Example

from chipenv import Environment, Modes

env = Environment(env_file_name=".env", mode=Modes.DEVELOPMENT)

print(env.get("DEBUG", default=False))
print(env["API_KEY"])
print(env.DB_URL)

Given a .env.development file:

DEBUG=true
API_KEY=secret
DB_URL=https://example.com

Smart Casts Example

from chipenv import Environment, cast

env = Environment()

print("INT:", env.get("PORT", cast=cast.cast_int))                      # -> int
print("FLOAT:", env.get("PI", cast=cast.cast_float))                    # -> float
print("BOOL:", env.get("ENABLED", cast=cast.cast_bool))                 # -> bool
print("LIST:", env.get("NUMBERS", cast=cast.cast_list))                 # -> list[str]
print("TUPLE:", env.get("WORDS", cast=cast.cast_tuple))                 # -> tuple[str]
print("DICT:", env.get("CONFIG", cast=cast.cast_dict))                  # -> dict
print("NONE_OR_STR:", env.get("OPTIONAL", cast=cast.cast_none_or_str))  # -> None or str

Singleton Example

from chipenv import EnvShared, Modes

env_a = EnvShared(env_file_name=".env", mode=Modes.LOCAL)
env_b = EnvShared(env_file_name=".env", mode=Modes.LOCAL)

print(env_a is env_b)  # -> True

Test/Fixture Example

from chipenv import TestEnv

env = TestEnv({"DEBUG": "true", "PORT": "8080"})

print(env.get("DEBUG"))  # -> "true"
print(env["PORT"])       # -> "8080"

Example .env:

PORT=8080
PI=3.1415
ENABLED=yes
NUMBERS=1,2,3
WORDS=hello,world,test
CONFIG={"timeout": 30, "debug": true}
OPTIONAL=null

Common errors and handling

Missing key with no default:

from chipenv import Environment, EnviromentKeyMissing

env = Environment(suppress_file_not_found=True)

try:
    env.get("MISSING_KEY")
except EnviromentKeyMissing as exc:
    print(exc)

Missing .env file:

from chipenv import Environment

try:
    env = Environment(env_file_name=".env", mode="missing")
except FileNotFoundError as exc:
    print(exc)

Included Cast Helpers

Import them via from chipenv import cast and use cast.cast_int(...), etc.

All built-in cast functions handle common edge cases:

Cast Function	Description
`cast_str`	Ensures string
`cast_int`	Converts to integer
`cast_float`	Converts to float
`cast_bool`	Accepts `1`, `true`, `yes`, `on`, etc.
`cast_list`	Comma-split list
`cast_tuple`	Comma-split, converted to tuple
`cast_dict`	Parses JSON string into dictionary
`cast_none_or_str`	Returns `None` if value is `null` or `None`

EnviromentKeyMissing

if a key is get from env.get and it has no default given it will raise EnviromentKeyMissing(f"Environment variable '{key}' not found.")

Requires Python: >=3.6

Details

PyPI

2026-01-04 17:14:45 +00:00

5

Chipperfluff

Project Site

10 KiB

Assets (2)

chipenv-0.0.1-py3-none-any.whl 5.3 KiB

chipenv-0.0.1.tar.gz 4.9 KiB

Versions (1) View all

0.0.1

2026-01-04