cfgzen

dotcfg

Lightweight .env and config file parser with native Rust acceleration.

A batteries-included environment configuration library for Python. Parse .env files 10x faster than pure-Python alternatives with built-in validation, schema definitions, and secret masking.

Features

• Native Rust parser — 10x faster than python-dotenv for large files
• Variable interpolation — ${VAR}, $VAR, ${VAR:-default}
• Type casting — get("PORT", cast=int) with bool/int/float/custom
• Schema validation — Declarative variable definitions with constraints
• Secret masking — Safely log env vars without leaking credentials
• CLI tools — dotcfg check, dotcfg diff, dotcfg keys
• Full type annotations — py.typed, mypy-strict compatible

Installation

pip install dotcfg

Quick Start

from dotcfg import load, get

# Load .env into os.environ
env = load()

# Type-safe access
port = get("PORT", cast=int, default=8080)
debug = get("DEBUG", cast=bool, default=False)
db_url = get("DATABASE_URL")

Advanced Usage

EnvCore Class

from dotcfg import EnvCore

core = EnvCore(".env.production", override=True, interpolate=True)
env = core.load()

# Typed access with defaults
port = core.get("PORT", cast=int, default=8080)
host = core.get("HOST", default="0.0.0.0")

Schema Validation

Define expected variables with types, constraints, and documentation:

from dotcfg.schema import EnvSchema, Var
from dotcfg.validators import Url, Port, OneOf, MinLength

schema = EnvSchema(
    Var("DATABASE_URL", validators=[Url()], required=True,
        description="PostgreSQL connection string"),
    Var("PORT", cast=int, default="8080", validators=[Port()]),
    Var("LOG_LEVEL", default="info",
        validators=[OneOf(["debug", "info", "warning", "error"])]),
    Var("SECRET_KEY", required=True, sensitive=True,
        validators=[MinLength(32)]),
    Var("DEBUG", cast=bool, default="false"),
)

# Validate all at once
config = schema.validate()

# Access typed values
config.PORT        # int: 8080
config.DEBUG       # bool: False
config.LOG_LEVEL   # str: "info"

# Safe representation (sensitive values masked)
print(config)  # Config(PORT=8080, SECRET_KEY=********, ...)

# Generate .env.example template
print(schema.generate_template())

Secret Masking

Prevent accidental credential leaks in logs:

from dotcfg.vault import SecretVault

vault = SecretVault()

# Mask sensitive keys automatically
safe_env = vault.mask_dict(os.environ)
print(safe_env["AWS_SECRET_ACCESS_KEY"])  # "aws****key"

# Scrub URLs in log messages
msg = vault.scrub("Failed: postgres://admin:[e-mail]/app")
print(msg)  # "Failed: postgres://admin:****@db.host/app"

Validators

Built-in validators for common patterns:

from dotcfg.validators import (
    Required, Url, Port, Email, OneOf,
    Range, Regex, Boolean, IPv4, MinLength, Json,
)

# Use standalone
Port().validate("PORT", "8080")       # OK
Email().validate("ADMIN", "bad")      # raises ValidationError

# Or with schema
Var("REDIS_URL", validators=[Url(schemes=["redis", "rediss"])])
Var("WORKERS", cast=int, validators=[Range(min_val=1, max_val=32)])
Var("CONFIG", validators=[Json()])

CLI Tools

# Validate a .env file
$ dotcfg check .env
OK: .env (12 variables)

# Compare environments
$ dotcfg diff .env .env.production --mask
Only in .env:
  - DEV_MODE=true

Changed:
  ~ PORT: '3000' -> '80'
  ~ DATABASE_URL: 'pos****cal' -> 'pos****ion'

# List all keys
$ dotcfg keys .env --sort

.env File Format

# Comments
DATABASE_URL=postgres://localhost/mydb
PORT=8080

# Quoted values (single, double, backtick)
MESSAGE="Hello, World!"
SINGLE='no interpolation here'

# Variable interpolation
BASE_URL=https://api.example.com
ENDPOINT=${BASE_URL}/v2/users

# Default values
CACHE_TTL=${REDIS_TTL:-3600}

# Export prefix (compatible with shell source)
export API_KEY=sk_live_abc123

# Multiline (double-quoted)
RSA_KEY="-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEA...
-----END RSA PRIVATE KEY-----"

Benchmarks

Parsing a 500-line .env file (averaged over 1000 runs):

Library	Time	Relative
dotcfg (native)	0.12ms	1x
python-dotenv	1.24ms	10.3x slower
environs	1.89ms	15.8x slower
pydantic-settings	2.41ms	20.1x slower

Comparison with Alternatives

Feature	dotcfg	python-dotenv	environs	pydantic-settings
Native parser	Rust	Python	Python	Python
Interpolation	Yes	Yes	No	No
Schema validation	Built-in	No	Marshmallow	Pydantic
Secret masking	Built-in	No	No	No
CLI tools	Yes	CLI	No	No
Type casting	Yes	No	Yes	Yes
Typed (py.typed)	Yes	No	No	Yes

License

MIT