Metadata-Version: 2.4
Name: envward
Version: 0.1.0
Summary: Validate your .env against a typed schema (required, int, url, enum, …) before the app boots — catch bad config up front. Zero dependencies.
Author: yyfjj
License: MIT
Project-URL: Homepage, https://github.com/jjdoor/envward-py
Project-URL: Repository, https://github.com/jjdoor/envward-py
Project-URL: Issues, https://github.com/jjdoor/envward-py/issues
Keywords: dotenv,env,environment,validation,schema,config,validate,cli,ci,twelve-factor
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# envward

**Validate your `.env` against a typed schema before the app boots.** A missing
`DATABASE_URL`, a `PORT=abc`, a `NODE_ENV=prodd` typo — these don't fail loudly,
they fail *deep in startup* with a cryptic stack trace, or worse, silently in
production. `envward` checks the whole environment against a small schema up
front and tells you exactly what's wrong, in one place. **Zero dependencies, no
network.**

```bash
pip install envward

$ envward

.env — checked against env.schema.json

  ✗ API_KEY   missing — required string
  ✗ NODE_ENV  "prodd" is not one of: development, production, test
  ✗ PORT      70000 is above max 65535

3 problem(s), 3 key(s) valid
```

Exits non-zero when anything is invalid, so it drops straight into a boot script
or CI step. Unlike a drift checker (which finds *missing keys*), `envward`
validates the *values*: types, ranges, formats, and allowed sets.

> This is the Python build. A behavior-equivalent Node build is on npm:
> `npx envward` (<https://github.com/jjdoor/envward>).

## Get started in one command

```bash
# Infer a starter schema from your existing .env, then edit it:
envward --init > env.schema.json
```

`--init` guesses a type for each key from its current value (`8080` → `int`,
`https://…` → `url`, `true` → `bool`, …) and marks them all required. Tighten it
from there.

## The schema

A plain JSON file (`env.schema.json` by default), one rule per key:

```json
{
  "PORT":         { "type": "int", "required": true, "min": 1, "max": 65535 },
  "DATABASE_URL": { "type": "url", "required": true },
  "NODE_ENV":     { "type": "enum", "values": ["development", "production", "test"] },
  "DEBUG":        { "type": "bool" },
  "API_KEY":      { "type": "string", "required": true, "minLength": 16 },
  "ADMIN_EMAIL":  { "type": "email" }
}
```

| Type | Accepts |
|------|---------|
| `string` | anything; constraints: `minLength`, `maxLength`, `pattern` (regex) |
| `int` | integer; constraints: `min`, `max` |
| `number` | integer or float; constraints: `min`, `max` |
| `bool` | `true` / `false` / `1` / `0` (case-insensitive) |
| `url` | `scheme://…` |
| `email` | `name@host.tld` |
| `enum` | one of `values` (required array) |

`required` defaults to `false`. An empty value (`KEY=`) counts as missing.

## Usage

```bash
envward                              # validate .env against env.schema.json
envward --env .env.prod --schema prod.schema.json
envward --strict                     # also flag keys in .env not declared in the schema
envward --json                       # machine-readable
envward --init > env.schema.json     # scaffold a schema from the current .env
```

## Options

| Flag | Effect |
|------|--------|
| `--env <file>` | `.env` file to check (default `.env`) |
| `--schema <file>` | JSON schema file (default `env.schema.json`) |
| `--strict` | Keys present in `.env` but absent from the schema are problems |
| `--init` | Print a schema scaffold inferred from the `.env` |
| `--json` | Emit `{ valid, problems, summary }` as JSON |
| `--quiet` | Print only the one-line summary |
| `-v`, `--version` · `-h`, `--help` | |

## Use it as a gate

```bash
# refuse to boot with a broken .env, or fail CI:
envward && python -m myapp
envward --env .env.ci --strict
```

## Exit codes

| Code | Meaning |
|------|---------|
| `0` | every key valid |
| `1` | one or more validation problems |
| `2` | error (missing/invalid schema, unreadable file) |

A validator should fail when validation fails, so `envward` exits `1` on problems
by default — no flag needed.

## Notes

- **Same tool, two builds.** A behavior-equivalent Node build is on npm
  (`npx envward`); use whichever your stack already has.
- **.env parsing** strips a single pair of surrounding quotes and an optional
  `export ` prefix. Inline comments after a value are *not* stripped — quote
  values that contain `#`.
- **`pattern` is a regex** matched in ASCII mode (`\d` = `[0-9]`) and as an
  *unanchored* search — wrap it in `^…$` to match the whole value. For identical
  results across both builds keep to a portable subset (avoid inline `(?i)` flags,
  lookbehind, and named groups, which differ between the JS and Python engines; a
  malformed pattern is reported as a schema error, exit 2).
- **Numeric `min`/`max`** are compared at 64-bit float precision — ample for
  config; keep bounds within ±2^53.

## License

MIT
