Metadata-Version: 2.4
Name: envguard-py
Version: 0.1.0
Summary: Validate your environment variables before they break your app — CLI + library.
License: MIT
Project-URL: Homepage, https://github.com/yourusername/envguard
Project-URL: Issues, https://github.com/yourusername/envguard/issues
Keywords: env,dotenv,environment,validation,cli,devtools
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# 🛡️ envguard

> Validate your environment variables before they break your app — CLI scanner + runtime guard.

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---

## 🤔 Why envguard?

`python-dotenv` loads your `.env` file. But what if a required variable is missing? Your app crashes at runtime — sometimes deep inside a function, hours after startup.

`envguard` catches missing variables **before** your app runs.

---

## 📦 Installation

```bash
pip install envguard
```

---

## 🚀 Two Ways to Use It

### 1. CLI — scan a project for missing vars

```bash
envguard scan ./myproject
```

```
🛡️  envguard scan

  📁 Scanning : /home/user/myproject
  📄 .env file: /home/user/myproject/.env

  ✅ DB_HOST          → localhost  (main.py:5)
  ✅ DB_NAME          → mydb       (main.py:6)
  ❌ API_KEY          → MISSING    (api.py:12)
  ⚠️  OLD_VAR         → in .env but not used in code

  Results: 2 ok  |  1 missing  |  1 unused

  💡 Add the missing variables to your .env file.
```

### 2. Library — block app startup if vars are missing

```python
from envguard import guard

guard.require("DB_HOST", "DB_NAME", "API_KEY")
guard.typed("PORT", int)
guard.typed("DEBUG", bool)
guard.start()   # raises EnvGuardError if anything is wrong
```

---

## 📖 CLI Reference

```bash
envguard scan [path] [options]

Arguments:
  path              Directory to scan (default: current directory)

Options:
  --env FILE        Path to .env file (default: auto-detect)
  --no-unused       Don't report .env vars unused in code
  --strict          Exit with code 1 if any vars are missing

Examples:
  envguard scan .
  envguard scan ./myproject --env .env.production
  envguard scan . --strict
```

---

## 📖 Library Reference

### `guard.require(*names)`
Mark variables as required — fails if missing or empty.

```python
guard.require("DB_HOST", "API_KEY", "SECRET_TOKEN")
```

### `guard.typed(name, type)`
Require a variable to be castable to a Python type.

```python
guard.typed("PORT", int)       # "5432" → 5432
guard.typed("RATE", float)     # "3.14" → 3.14
guard.typed("DEBUG", bool)     # "true" / "1" / "yes" → True
```

### `guard.start()`
Run all validations. Raises `EnvGuardError` with all failures listed.

```python
from envguard import guard, EnvGuardError

try:
    guard.require("DB_HOST").typed("PORT", int).start()
except EnvGuardError as e:
    print(e)
    # envguard: environment validation failed:
    #   ❌ 'DB_HOST' is missing from environment
    #   ❌ 'PORT' is missing (expected int)
```

### `guard.check()`
Like `start()` but returns `True`/`False` instead of raising.

```python
if not guard.require("API_KEY").check():
    print("Some env vars are missing!")
```

---

## 🔍 What envguard scans for

```python
os.getenv("VAR")              # ✅ detected
os.getenv("VAR", "default")   # ✅ detected
os.environ["VAR"]             # ✅ detected
os.environ.get("VAR")         # ✅ detected
```

---

## 🆚 envguard vs python-dotenv

| Feature | python-dotenv | envguard |
|---|---|---|
| Load .env file | ✅ | ❌ (use together) |
| Validate required vars | ❌ | ✅ |
| Type checking | ❌ | ✅ |
| Scan codebase for usage | ❌ | ✅ CLI |
| Report unused .env vars | ❌ | ✅ |

They work great **together**:
```python
from dotenv import load_dotenv
from envguard import guard

load_dotenv()                        # load .env into os.environ
guard.require("DB_HOST", "API_KEY")  # then validate
guard.typed("PORT", int)
guard.start()
```

---

## 🧪 Running Tests

```bash
pip install pytest
pytest tests/ -v
```

---

## 📄 License

MIT — free to use in personal and commercial projects.
