dotenvmodel 0.1.1__tar.gz → 0.2.0__tar.gz

dotenvmodel-0.2.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.2.0"
+}

{dotenvmodel-0.1.1 → dotenvmodel-0.2.0}/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0](https://github.com/AZX-PBC/dotenvmodel/compare/v0.1.1...v0.2.0) (2025-12-05)
+
+
+### Features
+
+* add describe functionality for configuration classes and related tests ([#6](https://github.com/AZX-PBC/dotenvmodel/issues/6)) ([49767ea](https://github.com/AZX-PBC/dotenvmodel/commit/49767ea34e8216706a0071072cb92452890451f3))
+
 ## [0.1.1](https://github.com/AZX-PBC/dotenvmodel/compare/v0.1.0...v0.1.1) (2025-12-05)
 
 

dotenvmodel-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,381 @@
+# Contributing to dotenvmodel
+
+Thank you for your interest in contributing to dotenvmodel! We appreciate your time and effort in making this library better for everyone.
+
+## Development Setup
+
+### Prerequisites
+
+- Python 3.12 or higher
+- [uv](https://docs.astral.sh/uv/) - Fast Python package installer and resolver
+
+### Getting Started
+
+1. **Clone the repository:**
+   ```bash
+   git clone https://github.com/azxio/dotenvmodel.git
+   cd dotenvmodel
+   ```
+
+2. **Install dependencies:**
+
+   This project uses `uv` for dependency management. Install development dependencies with:
+   ```bash
+   uv sync --dev
+   ```
+
+   This will create a virtual environment and install all necessary dependencies including pytest, mypy, ruff, and other development tools.
+
+## Running Tests
+
+**IMPORTANT: Always use `uv run` to execute pytest and other development commands.**
+
+Using `uv run` ensures that:
+- Commands run in the correct virtual environment
+- All dependencies are properly resolved
+- You're using the exact versions specified in the project
+- No conflicts with globally installed packages
+
+### Test Commands
+
+```bash
+# Run all tests
+uv run pytest
+
+# Run specific test file
+uv run pytest tests/test_describe.py
+
+# Run specific test class
+uv run pytest tests/test_describe.py::TestLineEndings
+
+# Run specific test function
+uv run pytest tests/test_core.py::TestDotEnvConfig::test_load_from_dict
+
+# Run with verbose output
+uv run pytest -v
+
+# Run with coverage report
+uv run pytest --cov=dotenvmodel --cov-report=html
+
+# Run tests matching a pattern
+uv run pytest -k "test_validation"
+
+# Run tests with output from print statements
+uv run pytest -s
+```
+
+### Understanding Test Output
+
+The project is configured with the following pytest settings (in `pyproject.toml`):
+- Coverage is automatically collected for the `dotenvmodel` package
+- HTML coverage reports are generated in `htmlcov/`
+- Tests must maintain at least 95% code coverage
+- Coverage reports exclude test files and implementation details
+
+## Code Quality
+
+### Type Checking
+
+The project uses `ty` (a wrapper around pyright) for type checking:
+
+```bash
+# Run type checking
+uv run ty check
+
+# Type check specific file
+uv run ty check dotenvmodel/core.py
+```
+
+### Linting and Formatting
+
+The project uses `ruff` for both linting and formatting:
+
+```bash
+# Check for linting issues
+uv run ruff check dotenvmodel
+
+# Auto-fix linting issues
+uv run ruff check --fix dotenvmodel
+
+# Format code
+uv run ruff format dotenvmodel
+
+# Check formatting without making changes
+uv run ruff format --check dotenvmodel
+```
+
+### Running All Quality Checks
+
+Before submitting a PR, run all quality checks:
+
+```bash
+# Run tests with coverage
+uv run pytest
+
+# Run type checking
+uv run ty check
+
+# Run linting
+uv run ruff check dotenvmodel
+
+# Check formatting
+uv run ruff format --check dotenvmodel
+```
+
+## Making Changes
+
+### Workflow
+
+1. **Create a feature branch:**
+   ```bash
+   git checkout -b feat/your-feature-name
+   ```
+
+   Or for bug fixes:
+   ```bash
+   git checkout -b fix/bug-description
+   ```
+
+2. **Make your changes:**
+   - Write clear, readable code
+   - Follow existing code patterns and conventions
+   - Add type hints to all functions and methods
+   - Keep functions focused and modular
+
+3. **Write tests:**
+   - Add tests for all new functionality
+   - Update existing tests if modifying behavior
+   - Ensure tests are clear and well-documented
+   - Test edge cases and error conditions
+   - Run tests with `uv run pytest`
+
+4. **Update documentation:**
+   - Update README.md if adding new features
+   - Add docstrings to new functions and classes
+   - Update type hints and examples
+
+5. **Verify your changes:**
+   ```bash
+   # Run all tests
+   uv run pytest
+
+   # Check types
+   uv run ty check
+
+   # Check linting
+   uv run ruff check dotenvmodel
+
+   # Check formatting
+   uv run ruff format --check dotenvmodel
+   ```
+
+## Pull Request Process
+
+### Before Submitting
+
+1. **Ensure all tests pass:**
+   ```bash
+   uv run pytest
+   ```
+
+2. **Ensure type checking passes:**
+   ```bash
+   uv run ty check
+   ```
+
+3. **Ensure code is properly formatted:**
+   ```bash
+   uv run ruff format dotenvmodel
+   uv run ruff check --fix dotenvmodel
+   ```
+
+4. **Verify coverage hasn't decreased:**
+   ```bash
+   uv run pytest --cov=dotenvmodel --cov-report=term-missing
+   ```
+
+   Coverage should remain at or above 95%.
+
+### Submitting Your PR
+
+1. **Push your branch:**
+   ```bash
+   git push origin feat/your-feature-name
+   ```
+
+2. **Create a pull request on GitHub**
+
+3. **In your PR description:**
+   - Clearly describe what changes you made
+   - Explain why the changes are needed
+   - Reference any related issues
+   - Include examples of new functionality (if applicable)
+   - List any breaking changes
+
+### PR Description Template
+
+```markdown
+## Summary
+Brief description of what this PR does
+
+## Changes
+- Change 1
+- Change 2
+- Change 3
+
+## Testing
+Describe how you tested these changes
+
+## Related Issues
+Fixes #123
+```
+
+## Code Review
+
+### What to Expect
+
+- All changes must pass automated tests and type checking
+- Code reviewers will check for:
+  - Implementation correctness
+  - Code clarity and maintainability
+  - Adequate test coverage
+  - Documentation completeness
+  - Adherence to project conventions
+
+- You may be asked to make revisions
+- Reviews are constructive - they help improve code quality
+
+### Addressing Feedback
+
+When reviewers request changes:
+
+1. Make the requested changes in your branch
+2. Run tests again: `uv run pytest`
+3. Push the updates: `git push origin feat/your-feature-name`
+4. Respond to reviewer comments
+
+## Development Tips
+
+### Virtual Environment
+
+The `uv run` command automatically manages the virtual environment. You don't need to manually activate it.
+
+If you prefer to activate the environment manually:
+```bash
+# uv creates a .venv directory
+source .venv/bin/activate  # Linux/macOS
+# or
+.venv\Scripts\activate  # Windows
+```
+
+However, we recommend using `uv run` for consistency.
+
+### Interactive Testing
+
+You can use `uv run python` to start a Python interpreter with the correct environment:
+
+```bash
+uv run python
+```
+
+Then test your changes interactively:
+```python
+from dotenvmodel import DotEnvConfig, Field
+
+class TestConfig(DotEnvConfig):
+    value: str = Field()
+
+config = TestConfig.load_from_dict({"value": "test"})
+print(config.value)
+```
+
+### Debugging Tests
+
+To debug a specific test with pdb:
+
+```bash
+# Add breakpoint() in your test or code
+# Then run with -s to see output
+uv run pytest -s tests/test_describe.py::test_specific_function
+```
+
+### Coverage Reports
+
+After running tests with coverage, view the HTML report:
+
+```bash
+uv run pytest --cov=dotenvmodel --cov-report=html
+# Open htmlcov/index.html in your browser
+```
+
+## Code Style Guidelines
+
+### General Principles
+
+- Write clear, self-documenting code
+- Use meaningful variable and function names
+- Keep functions short and focused (ideally under 50 lines)
+- Avoid deep nesting (max 3-4 levels)
+- Comments should explain "why", not "what"
+
+### Type Hints
+
+Always use type hints:
+
+```python
+# Good
+def process_value(value: str, default: int = 0) -> int:
+    return int(value) if value else default
+
+# Bad
+def process_value(value, default=0):
+    return int(value) if value else default
+```
+
+### Docstrings
+
+Use clear docstrings for public APIs:
+
+```python
+def describe(cls, format: str = "table") -> str:
+    """Generate documentation for the configuration class.
+
+    Args:
+        format: Output format - "table", "markdown", "json", "html", or "dotenv"
+
+    Returns:
+        Formatted documentation string
+
+    Raises:
+        ValueError: If format is not supported
+    """
+```
+
+### Error Messages
+
+Write helpful error messages:
+
+```python
+# Good
+raise ValueError(
+    f"Invalid format '{format}'. "
+    f"Supported formats: table, markdown, json, html, dotenv"
+)
+
+# Bad
+raise ValueError("Invalid format")
+```
+
+## Getting Help
+
+- **Questions?** Open a [GitHub Discussion](https://github.com/azxio/dotenvmodel/discussions)
+- **Bug Reports?** Open an [Issue](https://github.com/azxio/dotenvmodel/issues)
+- **Feature Requests?** Open an [Issue](https://github.com/azxio/dotenvmodel/issues) with the `enhancement` label
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.
+
+## Thank You!
+
+Your contributions help make dotenvmodel better for everyone. We appreciate your time and effort!

{dotenvmodel-0.1.1 → dotenvmodel-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotenvmodel
-Version: 0.1.1
+Version: 0.2.0
 Summary: Type-safe environment configuration with automatic .env file loading
 Project-URL: Homepage, https://github.com/AZX-PBC/dotenvmodel
 Project-URL: Repository, https://github.com/AZX-PBC/dotenvmodel
@@ -42,6 +42,9 @@ Description-Content-Type: text/markdown
 - **Developer Experience**: Intuitive Pydantic-style API
 - **Smart .env Loading**: Automatic cascading of `.env`, `.env.{env}`, `.env.{env}.local` files
 - **Configuration Reload**: Reload configuration at runtime without creating new instances
+- **Configuration Documentation**: Generate docs in multiple formats (table, markdown, JSON, HTML, dotenv) with `describe()`
+- **.env.example Generation**: Automatically generate `.env.example` files with type hints, constraints, and examples
+- **File Export**: Save documentation directly to files for integration with build tools and wikis
 - **Environment Prefixes**: Class-level `env_prefix` to namespace environment variables
 - **Validation**: Numeric constraints (ge, le, gt, lt), string constraints (min_length, max_length, regex), choice validation, and collection size constraints (min_items, max_items)
 - **Clear Error Messages**: Helpful validation errors that guide you to fixes
@@ -85,6 +88,9 @@ config = AppConfig.load(env="dev")
 print(f"Connecting to {config.database_url}")  # config.database_url: str
 print(f"Running on port {config.port}")        # config.port: int
 print(f"Debug mode: {config.debug}")           # config.debug: bool
+
+# Generate documentation for your configuration
+print(AppConfig.describe())
 ```
 
 ## Type Safety and IntelliSense
@@ -650,6 +656,293 @@ The `reload()` method:
 - Validates all fields and raises errors if validation fails
 - Returns the same instance (useful for method chaining)
 
+## Configuration Documentation
+
+Generate human-readable documentation for your configuration classes using the `describe()` method. This is useful for:
+
+- **Creating documentation** for your team
+- **Generating `.env.example` files** automatically
+- **Validating configuration** in CI pipelines
+- **Onboarding new developers** quickly
+
+### Generate Documentation for a Single Config
+
+```python
+from dotenvmodel import DotEnvConfig, Field
+
+class AppConfig(DotEnvConfig):
+    database_url: str = Field(description="PostgreSQL connection string")
+    port: int = Field(default=8000, ge=1, le=65535, description="Server port")
+    debug: bool = Field(default=False, description="Enable debug mode")
+    workers: int = Field(default=4, ge=1, le=16, description="Number of worker processes")
+
+# Generate ASCII table (default)
+print(AppConfig.describe())
+```
+
+Output:
+
+```
+AppConfig
+=========
++--------------+------+----------+---------+---------------------------+----------------+
+| ENV Variable | Type | Required | Default | Description               | Constraints    |
++--------------+------+----------+---------+---------------------------+----------------+
+| DATABASE_URL | str  | Yes      | -       | PostgreSQL connection ... | -              |
+| PORT         | int  | No       | 8000    | Server port               | ge=1, le=65535 |
+| DEBUG        | bool | No       | False   | Enable debug mode         | -              |
+| WORKERS      | int  | No       | 4       | Number of worker proces...| ge=1, le=16    |
++--------------+------+----------+---------+---------------------------+----------------+
+```
+
+### Output Formats
+
+**ASCII Table (default)** - Best for terminal output and logging:
+
+```python
+print(AppConfig.describe(output_format="table"))
+```
+
+**Markdown** - Perfect for README files and documentation:
+
+```python
+# Generate markdown documentation
+docs = AppConfig.describe(output_format="markdown")
+
+# Save to file
+with open("CONFIG.md", "w") as f:
+    f.write(docs)
+```
+
+**JSON** - Ideal for CI validation and programmatic processing:
+
+```python
+import json
+
+# Get configuration schema as JSON
+config_spec = AppConfig.describe(output_format="json")
+data = json.loads(config_spec)
+
+# Use for validation, code generation, etc.
+print(data["class_name"])  # "AppConfig"
+print(data["fields"][0]["env_var"])  # "DATABASE_URL"
+```
+
+**HTML** - Styled output for web documentation:
+
+```python
+# Generate HTML with styled tables
+html_docs = AppConfig.describe(output_format="html")
+
+# Save to file
+with open("config.html", "w") as f:
+    f.write(html_docs)
+```
+
+**Dotenv Format** - For generating `.env.example` files:
+
+```python
+# Generate .env.example format
+dotenv_docs = AppConfig.describe(output_format="dotenv")
+print(dotenv_docs)
+```
+
+### File Export
+
+Save documentation directly to files using the `output` parameter:
+
+```python
+# Save as markdown
+AppConfig.describe(output_format="markdown", output="docs/config.md")
+
+# Save as HTML
+AppConfig.describe(output_format="html", output="docs/config.html")
+
+# Save as JSON
+AppConfig.describe(output_format="json", output="config-schema.json")
+```
+
+### Generate `.env.example` Files
+
+Automatically generate `.env.example` files for onboarding new developers:
+
+```python
+from dotenvmodel import DotEnvConfig, Field, SecretStr
+
+class AppConfig(DotEnvConfig):
+    env_prefix = "APP_"
+
+    api_key: str = Field(
+        min_length=32,
+        max_length=64,
+        description="API key for external service"
+    )
+    port: int = Field(
+        default=8000,
+        ge=1,
+        le=65535,
+        description="Server port number"
+    )
+    database_password: SecretStr = Field(
+        default=SecretStr("change_me_in_production"),
+        min_length=8,
+        description="Database connection password"
+    )
+    allowed_hosts: list[str] = Field(
+        default_factory=list,
+        separator=";",
+        min_items=1,
+        max_items=10,
+        description="Allowed hostnames for CORS"
+    )
+
+# Generate and print .env.example
+print(AppConfig.generate_env_example())
+
+# Or save directly to file
+AppConfig.generate_env_example(output=".env.example")
+```
+
+Output in `.env.example`:
+
+```bash
+# Configuration for AppConfig
+# All variables prefixed with: APP_
+
+# API key for external service
+# Type: str | Constraints: min_length=32, max_length=64
+# Example: APP_API_KEY=your_value_here
+APP_API_KEY=
+
+# Server port number
+# Type: int | Constraints: ge=1, le=65535
+# Example: APP_PORT=8000
+# APP_PORT=8000
+
+# Database connection password
+# Type: SecretStr | Constraints: min_length=8
+# APP_DATABASE_PASSWORD=your_secret_here
+
+# Allowed hostnames for CORS
+# Type: list[str] | Constraints: min_items=1, max_items=10, separator=';'
+# Example: APP_ALLOWED_HOSTS=[]
+# APP_ALLOWED_HOSTS=[]
+```
+
+The `.env.example` file includes:
+
+- **Type information** - Shows the expected Python type
+- **Parsing hints** - Explains how to format complex types (e.g., "comma-separated values" for lists)
+- **Constraints** - Documents validation rules (min/max length, numeric ranges, etc.)
+- **Examples** - Shows example values for required fields
+- **Commented defaults** - Optional fields are commented out with their default values
+- **Secret handling** - SecretStr fields are masked appropriately
+
+### Document Multiple Configurations
+
+Use `describe_configs()` to document multiple related configuration classes:
+
+```python
+from dotenvmodel import DotEnvConfig, Field, describe_configs
+
+class DatabaseConfig(DotEnvConfig):
+    env_prefix = "DB_"
+    host: str = Field(description="Database host")
+    port: int = Field(default=5432, description="Database port")
+
+class RedisConfig(DotEnvConfig):
+    env_prefix = "REDIS_"
+    host: str = Field(description="Redis host")
+    port: int = Field(default=6379, description="Redis port")
+
+# Generate documentation for all configs
+all_docs = describe_configs([DatabaseConfig, RedisConfig], output_format="markdown")
+print(all_docs)
+```
+
+### Practical Use Cases
+
+**1. Generate `.env.example` files for onboarding:**
+
+```python
+# Generate .env.example with helpful comments and type information
+AppConfig.generate_env_example(output=".env.example")
+
+# Or combine multiple configs
+from dotenvmodel import describe_configs
+
+with open(".env.example", "w") as f:
+    f.write("# Application Configuration\n\n")
+    f.write("# Copy this file to .env and fill in the values\n\n")
+    for config_cls in [AppConfig, DatabaseConfig, RedisConfig]:
+        f.write(config_cls.generate_env_example())
+        f.write("\n\n")
+```
+
+**2. CI Configuration Validation:**
+
+```python
+import json
+import os
+
+# Get required environment variables from config schema
+spec = json.loads(AppConfig.describe(output_format="json"))
+required_vars = [f["env_var"] for f in spec["fields"] if f["required"]]
+
+# Validate all required vars are set
+missing = [var for var in required_vars if var not in os.environ]
+if missing:
+    print(f"ERROR: Missing required environment variables: {', '.join(missing)}")
+    exit(1)
+```
+
+**3. Developer Onboarding:**
+
+```python
+import os
+
+# Display configuration reference in development mode
+if os.getenv("ENV") == "dev":
+    print("\n" + "=" * 80)
+    print("CONFIGURATION REFERENCE")
+    print("=" * 80)
+    print(AppConfig.describe())
+    print("=" * 80 + "\n")
+```
+
+**4. Generate Documentation Website:**
+
+```python
+from dotenvmodel import describe_configs
+
+# Generate markdown docs for all config classes
+configs = [AppConfig, DatabaseConfig, RedisConfig, CacheConfig]
+
+# Save as markdown
+describe_configs(configs, output_format="markdown", output="docs/configuration.md")
+
+# Or generate HTML version with styling
+describe_configs(configs, output_format="html", output="docs/configuration.html")
+```
+
+**5. Build Tool Integration:**
+
+```python
+# build_docs.py - Run during build process
+from your_app.config import AppConfig, DatabaseConfig
+
+# Generate .env.example for repository
+AppConfig.generate_env_example(output=".env.example")
+
+# Generate markdown docs
+AppConfig.describe(output_format="markdown", output="docs/CONFIG.md")
+
+# Generate HTML for internal wiki
+AppConfig.describe(output_format="html", output="docs/config.html")
+
+print("✓ Configuration documentation generated")
+```
+
 ## Environment Variable Prefixes
 
 Use class-level prefixes to namespace environment variables: