philiprehberger-env-validator 0.3.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.

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"],
# }

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(), list_field() methods
Schema.list_field(name, *, sep=",", item_type=str)	Parse a comma-separated list with optional int/float coercion
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 project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT