philiprehberger-env-validator 0.2.0

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

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.

API

Function / Class	Description
validate(schema, source)	Validate environment variables against a schema, returning typed dict
Schema	Fluent schema builder with string(), integer(), float_field(), boolean(), url(), email() methods
Schema.generate_help()	Return formatted help text documenting all fields grouped by required/optional
Schema.load_from_env_file(path)	Load and validate a .env file against the schema
FieldSpec	Field specification with type, default, choices, pattern, validator, and description options
ValidationError	Raised when validation fails, contains list of error messages in errors

Development

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

Support

If you find this package useful, consider giving it a star on GitHub — it helps motivate continued maintenance and development.

License

MIT