philiprehberger-env-validator

Schema-based environment variable validation with type coercion and helpful error messages.

Installation

pip install philiprehberger-env-validator

Usage

Basic Validation

from philiprehberger_env_validator import Schema, validate

schema = (
    Schema()
    .string("DATABASE_URL", description="PostgreSQL connection string")
    .integer("PORT", default=3000)
    .boolean("DEBUG", default=False)
    .string("NODE_ENV", choices=["development", "staging", "production"])
)

config = validate(schema)
print(config["PORT"])  # 3000 (int, not string)

Field Types

schema = (
    Schema()
    .string("API_KEY")
    .integer("MAX_CONNECTIONS")
    .float_field("RATE_LIMIT")
    .boolean("VERBOSE")
    .url("WEBHOOK_URL")
    .email("ADMIN_EMAIL")
)

Custom Validation

schema = Schema().string(
    "API_KEY",
    pattern=r"^sk-[a-zA-Z0-9]{32}$",
    validator=lambda v: len(v) > 10,
)

Optional Fields

schema = (
    Schema()
    .string("REQUIRED_VAR")
    .string("OPTIONAL_VAR", required=False, default="fallback")
)

Custom Source

config = validate(schema, source={"PORT": "8080", "DEBUG": "true"})

Error Handling

from philiprehberger_env_validator import ValidationError

try:
    config = validate(schema)
except ValidationError as e:
    for error in e.errors:
        print(error)

Schema Documentation

Generate formatted help text documenting all fields, grouped by required and optional.

schema = (
    Schema()
    .url("DATABASE_URL", description="PostgreSQL connection string")
    .string("API_KEY")
    .boolean("DEBUG", default=False, required=False, description="Enable debug mode")
    .integer("PORT", default=8000, required=False)
)

print(schema.generate_help())
# REQUIRED:
#   DATABASE_URL (url): PostgreSQL connection string
#   API_KEY (str): No description
#
# OPTIONAL:
#   DEBUG (bool) [default: false]: Enable debug mode
#   PORT (int) [default: 8000]: No description

Load from .env File

Read and validate a .env file directly against a schema.

schema = (
    Schema()
    .string("DATABASE_URL")
    .integer("PORT", default=3000)
    .boolean("DEBUG", default=False)
)

config = schema.load_from_env_file(".env")
print(config["DATABASE_URL"])
print(config["PORT"])  # coerced to int

The .env file uses standard KEY=VALUE format. Comments (#) and blank lines are skipped. Quoted values are unquoted automatically.

List Fields

list_field() parses comma-separated values into a list, with optional per-item type coercion.

schema = (
    Schema()
    .list_field("ALLOWED_HOSTS")               # default: split on "," as strings
    .list_field("PORTS", item_type=int)        # coerce each element to int
    .list_field("PATHS", sep=":")              # custom separator
)

config = validate(schema, source={
    "ALLOWED_HOSTS": "a.com, b.com, c.com",
    "PORTS": "80,443,8080",
    "PATHS": "/usr/bin:/usr/local/bin",
})
# {
#   "ALLOWED_HOSTS": ["a.com", "b.com", "c.com"],
#   "PORTS": [80, 443, 8080],
#   "PATHS": ["/usr/bin", "/usr/local/bin"],
# }

JSON values

json_field() parses an env var value as JSON, returning the decoded object.

schema = (
    Schema()
    .json_field("FEATURE_FLAGS")
    .json_field("LIMITS", required=False, default={"max": 100})
)

config = validate(schema, source={
    "FEATURE_FLAGS": '{"beta": true, "experimental": false}',
})
# {
#   "FEATURE_FLAGS": {"beta": True, "experimental": False},
#   "LIMITS": {"max": 100},
# }

Invalid JSON raises ValidationError with a "cannot be converted to json" message.

Declarative schemas

Schema.from_dict() builds a schema from a plain dict — useful when the schema is loaded from YAML/JSON config rather than written in code.

schema = Schema.from_dict({
    "PORT": {"type": "integer", "default": 8080},
    "DEBUG": {"type": "boolean", "default": False},
    "HOSTS": {"type": "list", "sep": ","},
    "FEATURES": {"type": "json", "required": False, "default": {}},
})

config = validate(schema, source={"PORT": "3000", "DEBUG": "true", "HOSTS": "a,b"})

Supported type values: "string", "integer", "float", "boolean", "url", "email", "list", "json". Remaining keys are forwarded to the corresponding fluent method.

API

Development

pip install -e .
python -m pytest tests/ -v

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT