envguard-py 0.1.0

Validate your environment variables before they break your app — CLI + library.

🛡️ envguard

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

---

🤔 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

pip install envguard

---

🚀 Two Ways to Use It

1. CLI — scan a project for missing vars

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

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

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.

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

guard.typed(name, type)

Require a variable to be castable to a Python type.

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.

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.

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

---

🔍 What envguard scans for

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:

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

pip install pytest
pytest tests/ -v

---

📄 License

MIT — free to use in personal and commercial projects.