philiprehberger-env-validator
v0.3.0358 downloadsMIT
Schema-based environment variable validation with type coercion and helpful error messages
$
pip install philiprehberger-env-validatorREADME
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: