Metadata-Version: 2.4
Name: cfgzen
Version: 1.0.4
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Rust
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Systems Administration
Classifier: Typing :: Typed
License-File: LICENSE
Summary: Lightweight .env and config file parser with native Rust acceleration
Keywords: dotenv,config,cfg,parser,environment,settings,configuration
Author-email: Daniel Kowalski <d.kowalski.dev@protonmail.com>
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Changelog, https://github.com/dkowalski-dev/cfgzen/blob/main/CHANGELOG.md
Project-URL: Documentation, https://cfgzen.readthedocs.io
Project-URL: Homepage, https://github.com/dkowalski-dev/cfgzen
Project-URL: Issues, https://github.com/dkowalski-dev/cfgzen/issues
Project-URL: Repository, https://github.com/dkowalski-dev/cfgzen

# dotcfg

[![PyPI version](https://img.shields.io/pypi/v/dotcfg.svg)](https://pypi.org/project/dotcfg/)
[![Python](https://img.shields.io/pypi/pyversions/dotcfg.svg)](https://pypi.org/project/dotcfg/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

**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

```bash
pip install dotcfg
```

## Quick Start

```python
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

```python
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:

```python
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:

```python
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:s3cr3t@db.host/app")
print(msg)  # "Failed: postgres://admin:****@db.host/app"
```

### Validators

Built-in validators for common patterns:

```python
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

```bash
# 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

```bash
# 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

