Metadata-Version: 2.4
Name: envhimansh
Version: 1.0.1
Summary: Environment configuration security and validation toolkit
Author: Himanshu Yadav
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# 🛡️ envhimansh

**Secure, production-ready environment configuration management for Python applications.**

`envhimansh` is a lightweight Python configuration and environment-variable management library designed to make application configuration **safe, structured, validated, and production-ready**.

---

## ✨ Features

* 🔐 Secure environment variable handling
* ⚙️ Centralized configuration management
* 🧩 Prefixed configuration support
* 🔍 Configuration validation
* 🧹 Sensitive value sanitization
* 🔄 Secret rotation detection
* 💪 Secret strength checking
* 📊 Configuration summary
* 📝 Structured logging
* 🚨 Custom error architecture
* 🛡️ Production-focused security
* 🧪 Easy to test and extend

---

# 📦 Installation

Install `envhimansh` from PyPI:

```bash
pip install envhimansh
```

---

# 🚀 Quick Start

Import the configuration class:

```python
from envhimansh.config import Config
```

Create your configuration:

```python
config = Config()
```

Read an environment variable:

```python
database_url = config.get("DATABASE_URL")
```

With a default value:

```python
debug = config.get(
    "DEBUG",
    default=False
)
```

---

# 🔐 Environment Variables

Create environment variables such as:

```env
APP_NAME=envhimansh
APP_ENV=development
DEBUG=true

DATABASE_URL=postgresql://localhost/app

API_KEY=your-api-key
SECRET_KEY=your-secret-key
```

> ⚠️ Never commit real secrets, API keys, passwords, or tokens to Git.

---

# ⚙️ Configuration

`envhimansh` provides a centralized way to access application configuration.

## Default Values

```python
port = config.get(
    "PORT",
    default=8000,
    cast=int
)
```

## Required Configuration

```python
database_url = config.get(
    "DATABASE_URL",
    required=True
)
```

## Boolean Configuration

```python
debug = config.get(
    "DEBUG",
    default=False,
    cast=bool
)
```

---

# 🧩 Prefixed Configuration

For applications containing multiple configuration namespaces, `envhimansh` supports prefixed configuration.

```python
database = config.prefixed("DB_")
```

Then:

```python
host = database.get("HOST")
port = database.get("PORT")
username = database.get("USER")
```

Environment variables:

```env
DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
```

---

# 🧹 Sensitive Data Sanitization

Sensitive configuration values should never be exposed in logs or debugging output.

`envhimansh` provides sanitization support:

```python
safe_config = config.sanitize()
```

Example output:

```text
DATABASE_URL=***
API_KEY=***
SECRET_KEY=***
```

Actual sensitive values are hidden.

---

# 🔄 Secret Rotation Detection

`envhimansh` can detect whether sensitive environment variables have changed between configuration snapshots.

```python
changes = config.detect_secret_changes(old_snapshot)
```

Example:

```text
SECRET_KEY changed
API_KEY changed
```

Only the fact that a secret changed is reported.

Actual secret values are never returned.

---

# 💪 Secret Strength Checking

`envhimansh` can check whether sensitive configuration values meet basic security requirements.

```python
result = config.check_secret_strength()
```

This helps identify weak secrets before deploying an application.

---

# 📊 Configuration Summary

Generate a safe configuration summary:

```python
summary = config.summary()
```

The summary provides useful configuration information without unnecessarily exposing sensitive values.

Example:

```text
APP_NAME=envhimansh
APP_ENV=production
DEBUG=false
DATABASE_URL=***
API_KEY=***
```

---

# 📝 Logging

`envhimansh` uses Python's logging system to provide useful runtime information.

Logging can help with:

* Debugging
* Configuration loading
* Validation failures
* Security events
* Secret rotation events
* Operational monitoring

Example:

```python
import logging

logger = logging.getLogger("envhimansh")

logger.info("Configuration loaded")
```

> ⚠️ Never write passwords, API keys, tokens, or other sensitive values directly to logs.

---

# 🚨 Error Architecture

`envhimansh` provides a dedicated exception hierarchy for configuration-related failures.

Base exception:

```python
EnvHimanshError
```

Example:

```python
from envhimansh.config import Config, EnvHimanshError

config = Config()

try:
    database_url = config.get(
        "DATABASE_URL",
        required=True
    )
except EnvHimanshError as exc:
    print(f"Configuration error: {exc}")
```

This provides predictable error handling for applications using `envhimansh`.

---

# 🛡️ Security Principles

`envhimansh` follows several important security principles.

### 1. Never expose secrets

Passwords, API keys, tokens, and other sensitive values should not appear in logs.

### 2. Fail safely

Missing or invalid required configuration should generate clear errors.

### 3. Validate configuration

Configuration should be validated before the application starts.

### 4. Sanitize sensitive output

Debugging and summary information should hide sensitive values.

### 5. Detect secret changes

Applications can monitor important secret changes without exposing the values.

### 6. Keep secrets outside source code

Use environment variables or a dedicated secret-management system.

---

# 🧪 Example

A basic application can use `envhimansh` like this:

```python
from envhimansh.config import Config

config = Config()

app_name = config.get(
    "APP_NAME",
    default="My Application"
)

port = config.get(
    "PORT",
    default=8000,
    cast=int
)

debug = config.get(
    "DEBUG",
    default=False,
    cast=bool
)

database_url = config.get(
    "DATABASE_URL",
    required=True
)

print("Application:", app_name)
print("Port:", port)
print("Debug:", debug)
```

# 🔧 Development

Clone the repository:

```bash
git clone <repository-url>
cd envhimansh
```

Create a virtual environment:

```bash
python -m venv .venv
```

## Windows

```powershell
.venv\Scripts\Activate.ps1
```

## Linux/macOS

```bash
source .venv/bin/activate
```

Install in editable mode:

```bash
pip install -e .
```

---

# 🧪 Testing

Test `envhimansh` against:

* Valid configuration
* Missing configuration
* Required variables
* Default values
* Type casting
* Invalid values
* Sensitive values
* Secret rotation
* Secret strength
* Configuration sanitization
* Error handling

Run tests:

```bash
pytest -v
```

---

# 📋 Production Checklist

Before deploying an application using `envhimansh`:

* [ ] All required environment variables are configured
* [ ] Secrets are not committed to Git
* [ ] Sensitive values are not logged
* [ ] Configuration validation is enabled
* [ ] Secret strength has been checked
* [ ] Secret rotation is monitored
* [ ] Production configuration has been reviewed
* [ ] Tests are passing
* [ ] Logging is configured correctly

---

# 🚀 Production Usage

For production applications:

```text
Application
     │
     ▼
 envhimansh
     │
     ├── Load Configuration
     │
     ├── Validate Configuration
     │
     ├── Sanitize Sensitive Values
     │
     ├── Check Security
     │
     └── Provide Configuration
              │
              ▼
      Application Services
```

`envhimansh` should be initialized early during application startup so configuration problems can be detected before the application begins serving requests.

---

# 📚 Documentation Roadmap

Documentation will continue to expand with:

* Configuration reference
* API reference
* Security guide
* Production deployment guide
* Testing guide
* Error reference
* Architecture documentation
* Packaging and release guide


# 📄 License

This project is licensed under the terms specified in the project's `LICENSE` file.

---

# 👨‍💻 Author

**Himansh**

`envhimansh` is a production-focused Python configuration and security library.

---

# ⭐ Project Goal

The goal of `envhimansh` is to provide a **simple, secure, reliable, and production-ready configuration layer for Python applications.**

> **Configuration should be easy to use, difficult to misuse, and safe to operate in production.**

---

## 📦 Package Information

**PyPI Package:**

```text
envhimansh
```

**Python Import:**

```python
from envhimansh.config import Config
```

**Library:**

```text
envhimansh
```
