https://github.com/pinnlabs/venvalid
Venvalid is a inspiring Envalid (Node.JS) lib for validating and accessing environment variables in python programs
https://github.com/pinnlabs/venvalid
python venv venv-manager venv-python
Last synced: 2 months ago
JSON representation
Venvalid is a inspiring Envalid (Node.JS) lib for validating and accessing environment variables in python programs
- Host: GitHub
- URL: https://github.com/pinnlabs/venvalid
- Owner: PinnLabs
- License: mit
- Created: 2025-08-03T01:31:32.000Z (8 months ago)
- Default Branch: master
- Last Pushed: 2025-08-20T00:38:11.000Z (7 months ago)
- Last Synced: 2025-11-28T12:39:08.056Z (4 months ago)
- Topics: python, venv, venv-manager, venv-python
- Language: Python
- Homepage: https://pinnlabs.github.io/Venvalid/
- Size: 862 KB
- Stars: 4
- Watchers: 2
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Minimalist environment variable validation for Python, inspired by envalid
---
## About
**Venvalid** is a minimalist and developer-friendly environment variable validator for Python — inspired by the simplicity and clarity of [`envalid`](https://github.com/af/envalid) from the Node.js world.
It lets you define a schema for your environment variables and ensures they are present, well-formed, and ready to use — before your app even starts.
---
## Why Venvalid?
Venvalid was designed with Python developers in mind, offering a modern, clean, and extensible API to handle `.env` configurations. It stands out from other libraries by:
- ✅ Using **Python native types** (`str`, `bool`, `int`, `list`, `Path`, `Decimal`, `datetime`, etc.)
- ✅ Supporting **default values**, **enum constraints**, and **custom validation**
- ✅ Allowing **custom dotenv loading** with override support
- ✅ Raising clear and styled error messages that prevent app boot on misconfig
- ✅ Having zero external dependencies — just Python
---
## Installation
```bash
pip install venvalid
```
or
```bash
uv add venvalid
```
---
## Quick Example
```python
from venvalid import str_, int_, bool_, venvalid
from venvalid.dotenv import load_env_file
# Define schema
config = venvalid({
"DEBUG": bool_(default=False),
"PORT": int_(default=8000),
"SECRET_KEY": str_(),
"ENVIRONMENT": str_(allowed=["dev", "prod", "test"], default="dev"),
})
print(config["DEBUG"]) # -> False
print(config["PORT"]) # -> 8000
print(config["ENVIRONMENT"]) # -> "dev"
```
---
## Usage
You can use `venvalid` to validate configuration before mounting the app:
```python
from fastapi import FastAPI
from venvalid import str_, int_, bool_, venvalid
from venvalid.dotenv import load_env_file
config = venvalid({
"DEBUG": bool_(default=False),
"PORT": int_(default=8000),
"ENVIRONMENT": str_(allowed=["dev", "prod", "test"], default="dev"),
})
app = FastAPI()
@app.get("/")
def read_root():
return {
"env": config["ENVIRONMENT"],
"debug": config["DEBUG"],
"port": config["PORT"],
}
```
---
## Supported Types
You can use both built-in types and helper functions:
- `str`, `int`, `bool`, `list`
- `path_()` → for `pathlib.Path`
- `decimal_()` → for `Decimal`
- `datetime_()` → for `datetime`
- `json_()` → for JSON/dict strings
All helpers accept:
- `default=...`
- `allowed=[...]`
- `validate=callable`
---
## Advanced Options
```python
"ENVIRONMENT": str_(allowed=["dev", "prod"], default="dev"),
"FEATURE_FLAG": bool_(default=False),
"API_KEY": str_(validate=lambda v: v.startswith("sk-")),
```
If any variable is missing or invalid, `venvalid` will stop execution and print a meaningful error message.
---
## .env Loading
If you want to load variables from a `.env` file (without relying on `python-dotenv`), use:
```python
from venvalid.dotenv import load_env_file
load_env_file(".env") # default
load_env_file(".env.prod", override=True) # optional override
```