wry 0.3.2.dev0__tar.gz → 0.4.0__tar.gz

{wry-0.3.2.dev0 → wry-0.4.0}/.gitignore

@@ -137,3 +137,6 @@ dmypy.json
 
 # macOS
 .DS_Store
+
+# Auto-generated version file (generated by setuptools-scm at build time)
+wry/_version.py

{wry-0.3.2.dev0 → wry-0.4.0}/AI_KNOWLEDGE_BASE.md

@@ -1,7 +1,7 @@
 # wry - Comprehensive AI/LLM Knowledge Base
 
-**Last Updated**: 2025-10-01
-**Version**: 0.2.3+
+**Last Updated**: 2025-10-04
+**Version**: 0.3.2+
 **Purpose**: Complete reference for AI assistants and LLMs to understand wry without reading the entire codebase
 
 ---
@@ -14,11 +14,12 @@
 2. Automatically generating Click CLI parameters
 3. Supporting multiple configuration sources (CLI/ENV/JSON/DEFAULT)
 4. Tracking exactly where each value came from
-5. Enforcing strict precedence: CLI > ENV > JSON > DEFAULT
+5. Enforcing strict precedence: CLI > JSON > ENV > DEFAULT
+6. **NEW v0.3.2**: Automatic alias-based CLI option generation
 
 **Key Innovation**: Single source of truth for configuration with comprehensive source tracking.
 
-**Stats**: 918 lines of code, 407 tests (all passing), 92% coverage, supports Python 3.10-3.12
+**Stats**: 436 tests (all passing), 92%+ coverage, supports Python 3.10-3.12, Pydantic v2.11+ compatible
 
 ---
 
@@ -75,14 +76,25 @@ tests/
     └── multi_model/        # Multi-model
 
 examples/
-├── simple_cli.py                          # Basic usage
-├── source_tracking_comprehensive.py       # ⭐ All 4 sources demo
-├── source_tracking_example.py
-├── explicit_argument_help.py              # Argument help
-├── multi_model_example.py                 # Multiple models
-├── field_exclusion_example.py             # AutoExclude
-└── sample_config.json                     # Sample config
-```
+├── autowrymodel_comprehensive.py          # ⭐ Complete AutoWryModel features
+│   - Simple options, arguments, constraints
+│   - Pydantic aliases for custom CLI names
+│   - Explicit click.option() for short flags
+│   - Field exclusion with AutoExclude
+│   - Environment variables and JSON config
+├── wrymodel_comprehensive.py              # ⭐ WryModel with source tracking
+│   - Manual field annotation (AutoOption/AutoArgument)
+│   - Full source tracking (CLI/ENV/JSON/DEFAULT)
+│   - Pydantic aliases with WryModel
+│   - Configuration precedence demonstration
+├── multimodel_comprehensive.py            # Multi-model usage
+│   - Multiple models in one CLI
+│   - split_kwargs_by_model
+│   - create_models helper
+└── config.json                            # Sample config
+```
+
+**Note**: v0.3.2 consolidated 16 example files into 3 comprehensive examples for easier discovery and learning.
 
 ---
 
@@ -96,12 +108,18 @@ examples/
 
 ```python
 class WryModel(BaseModel):
-    model_config = ConfigDict(arbitrary_types_allowed=True)
+    model_config = ConfigDict(
+        arbitrary_types_allowed=True,
+        validate_by_name=True,      # NEW v0.3.2: Accept field names
+        validate_by_alias=True       # NEW v0.3.2: Accept aliases
+    )
     env_prefix: ClassVar[str] = ""  # Environment variable prefix
     _value_sources: dict[str, ValueSource] = {}  # Tracks where values came from
     _accessor_instances: dict[str, Any] = {}  # Caches property accessors
 ```
 
+**Note**: `validate_by_name=True` and `validate_by_alias=True` enable Pydantic alias support out of the box (v0.3.2+). This allows fields to be populated using either their field name or alias, which is essential for the alias-based CLI option generation feature.
+
 **Property Accessors** (lazy-initialized, cached):
 
 ```python
@@ -499,7 +517,7 @@ Converts constraint dict to human-readable list:
 
 ```python
 @classmethod
-def __init_subclass__(cls, **kwargs):
+def __init_subclass__(cls, **kwargs: Any):
     """Called when subclass is defined."""
     super().__init_subclass__(**kwargs)
 
@@ -538,7 +556,7 @@ def __init_subclass__(cls, **kwargs):
 
 **Result**: All fields become `--options` unless explicitly configured.
 
-**`create_auto_model(name, fields, **kwargs)`**:
+**`create_auto_model(name, fields, **kwargs: Any)`**:
 Dynamic model creation at runtime.
 
 ### 8. `wry/multi_model.py` - Multi-Model Support (48 lines, 100% coverage)
@@ -574,11 +592,11 @@ db = configs[DatabaseConfig]
 ```python
 # Decorator that applies generate_click_parameters for each model
 @multi_model(ServerConfig, DatabaseConfig)
-def serve(ctx, **kwargs):
+def serve(ctx: click.Context, **kwargs: Any):
     # All options from both models available
 ```
 
-**`singleton_option(*args, **kwargs)`**:
+**`singleton_option(*args, **kwargs: Any)`**:
 Wrapper around `click.option` that prevents duplicate options.
 
 ### 9. `wry/help_system.py` - Documentation System (89 lines)
@@ -674,7 +692,7 @@ CLICK PROCESSES (order matters!)
 │   └─> Click detects: ParameterSource.ENVIRONMENT
 │
 └─> 4. CALL COMMAND FUNCTION
-    └─> def main(ctx, **kwargs):
+    └─> def main(ctx: click.Context, **kwargs: Any):
         kwargs = {"host": "api.com", "port": 9000}
 │
 ↓
@@ -877,14 +895,14 @@ class Config(AutoWryModel):
 ```python
 # NO source tracking ❌
 @Config.generate_click_parameters()
-def main(**kwargs):
+def main(**kwargs: Any):
     config = Config(**kwargs)
     # config.source.* always shows CLI
 
 # FULL source tracking ✅
 @Config.generate_click_parameters()
 @click.pass_context
-def main(ctx, **kwargs):
+def main(ctx: click.Context, **kwargs: Any):
     config = Config.from_click_context(ctx, **kwargs)
     # config.source.* shows actual source
 ```
@@ -1007,7 +1025,7 @@ class Config(AutoWryModel):
 
 @click.command()
 @Config.generate_click_parameters()
-def main(**kwargs):
+def main(**kwargs: Any):
     config = Config(**kwargs)
     print(f"{config.host}:{config.port}")
 ```
@@ -1034,7 +1052,7 @@ class Config(AutoWryModel):
 @click.command()
 @Config.generate_click_parameters()
 @click.pass_context  # ⚠️ Required
-def main(ctx, **kwargs):  # ⚠️ ctx parameter required
+def main(ctx: click.Context, **kwargs: Any):  # ⚠️ ctx parameter required
     config = Config.from_click_context(ctx, **kwargs)  # ⚠️ Not Config(**kwargs)
 
     # Access sources
@@ -1062,7 +1080,7 @@ class Config(WryModel):
 
 @click.command()
 @Config.generate_click_parameters()
-def main(**kwargs):
+def main(**kwargs: Any):
     config = Config(**kwargs)
     # Usage: python app.py input.txt output.txt --format yaml --verbose
 ```
@@ -1106,7 +1124,7 @@ class DatabaseConfig(WryModel):
 @click.command()
 @multi_model(ServerConfig, DatabaseConfig)
 @click.pass_context
-def serve(ctx, **kwargs):
+def serve(ctx: click.Context, **kwargs: Any):
     configs = create_models(ctx, kwargs, ServerConfig, DatabaseConfig)
     server = configs[ServerConfig]
     db = configs[DatabaseConfig]
@@ -1137,6 +1155,85 @@ class Config(AutoWryModel):
 - Polymorphic validation fields
 - Secrets not from CLI
 
+### Pattern 7: Pydantic Aliases for Custom CLI Names (v0.3.2+)
+
+**New in v0.3.2**: Pydantic field aliases automatically control CLI option names and environment variable names!
+
+```python
+from pydantic import Field
+from wry import AutoWryModel
+
+class DatabaseConfig(AutoWryModel):
+    env_prefix = "DB_"
+
+    # Concise Python field name: db_url
+    # Alias controls CLI option: --database-url
+    # Environment variable: DB_DATABASE_URL
+    db_url: str = Field(
+        alias="database_url",
+        default="sqlite:///app.db",
+        description="Database connection URL"
+    )
+
+    pool_size: int = Field(
+        alias="connection_pool_size",
+        default=5,
+        description="Maximum connection pool size"
+    )
+
+@click.command()
+@DatabaseConfig.generate_click_parameters()
+@click.pass_context
+def main(ctx: click.Context, **kwargs: Any):
+    config = DatabaseConfig.from_click_context(ctx, **kwargs)
+
+    # Access via concise field names
+    print(f"URL: {config.db_url}")
+    print(f"Pool: {config.pool_size}")
+
+    # Source tracking works
+    print(f"URL from: {config.source.db_url.value}")
+```
+
+**How it works**:
+
+- **Python field**: `db_url` (concise, easy to type in code)
+- **CLI option**: `--database-url` (descriptive, user-friendly)
+- **Environment variable**: `DB_DATABASE_URL` (consistent with CLI)
+- **JSON config**: Accepts both `db_url` and `database_url`
+
+**Requirements**:
+
+- **None!** WryModel automatically sets `validate_by_name=True` and `validate_by_alias=True`
+- No configuration needed - it just works!
+
+**Full support**:
+
+- ✅ Aliases automatically control auto-generated option names
+- ✅ Environment variables use alias names (consistent with CLI)
+- ✅ Source tracking works correctly
+- ✅ JSON config accepts both field names and aliases
+
+**Why this pattern exists:**
+
+Before v0.3.2, custom CLI option names required explicit `click.option()` decorators for every field. The alias feature eliminates this boilerplate for the common case.
+
+**For advanced use cases** (short options, custom Click types), combine aliases with explicit decorators:
+
+```python
+class Config(AutoWryModel):
+    # Explicit click.option for short option support
+    verbose: Annotated[int, click.option("-v", "--verbose", count=True)] = Field(default=0)
+
+    # Or combine with aliases for descriptive field names
+    database_connection_string: Annotated[
+        str,
+        click.option("--db-url", "-d", default="sqlite:///app.db")
+    ] = Field(alias='db_url', default="sqlite:///app.db")
+```
+
+See `examples/autowrymodel_comprehensive.py` and `examples/wrymodel_comprehensive.py` for complete examples.
+
 ---
 
 ## Test Coverage Details
@@ -1280,10 +1377,10 @@ format_constraint_text(constraints) → list[str]
 multi_model(*model_classes, strict=False) → decorator
 create_models(ctx, kwargs, *model_classes) → dict[type, instance]
 split_kwargs_by_model(kwargs, *model_classes) → dict[type, dict]
-singleton_option(*args, **kwargs) → decorator
+singleton_option(*args, **kwargs: Any) → decorator
 
 # Auto Model
-create_auto_model(name, fields, **kwargs) → type[AutoWryModel]
+create_auto_model(name, fields, **kwargs: Any) → type[AutoWryModel]
 
 # Field Utilities
 extract_field_constraints(field_info) → dict[str, Any]
@@ -1442,7 +1539,7 @@ python -c "import wry; print(wry.__version__)"
 # WRONG ❌
 @click.command()
 @Config.generate_click_parameters()
-def main(**kwargs):  # No ctx parameter
+def main(**kwargs: Any):  # No ctx parameter
     config = Config(**kwargs)  # Direct instantiation
     # Result: All sources show as CLI
 
@@ -1450,7 +1547,7 @@ def main(**kwargs):  # No ctx parameter
 @click.command()
 @Config.generate_click_parameters()
 @click.pass_context  # Add this
-def main(ctx, **kwargs):  # Add ctx parameter
+def main(ctx: click.Context, **kwargs: Any):  # Add ctx parameter
     config = Config.from_click_context(ctx, **kwargs)  # Use this
     # Result: Accurate source tracking
 ```
@@ -1647,7 +1744,7 @@ config_data = {"host": TrackedValue("api.com", ValueSource.CLI)}
 ### Why model_dump() Excludes Accessors?
 
 ```python
-def model_dump(self, **kwargs) -> dict[str, Any]:
+def model_dump(self, **kwargs: Any) -> dict[str, Any]:
     data = super().model_dump(**kwargs)
     accessor_keys = {"source", "minimum", "maximum", "constraints", "defaults"}
     return {k: v for k, v in data.items() if k not in accessor_keys}
@@ -1806,7 +1903,7 @@ class Config(AutoWryModel):
 
 ```python
 @click.pass_context
-def main(ctx, **kwargs):
+def main(ctx: click.Context, **kwargs: Any):
     config = Config(**kwargs)  # ⚠️ Not using context
 ```
 
@@ -1837,7 +1934,7 @@ class Config(AutoWryModel):
 
 @click.command()
 @Config.generate_click_parameters()
-def main(**kwargs):
+def main(**kwargs: Any):
     config = Config(**kwargs)
     print(f"Connecting to {config.host}:{config.port}")
 
@@ -1881,7 +1978,7 @@ class Config(AutoWryModel):
 @click.command()
 @Config.generate_click_parameters()
 @click.pass_context  # ⚠️ Required for source tracking
-def main(ctx, **kwargs):  # ⚠️ ctx parameter required
+def main(ctx: click.Context, **kwargs: Any):  # ⚠️ ctx parameter required
     """Process files with configuration."""
     config = Config.from_click_context(ctx, **kwargs)
 
@@ -1943,7 +2040,7 @@ class DatabaseConfig(WryModel):
 @click.command()
 @multi_model(ServerConfig, DatabaseConfig)
 @click.pass_context
-def serve(ctx, **kwargs):
+def serve(ctx: click.Context, **kwargs: Any):
     """Start server with database connection."""
     # Create both models from kwargs
     configs = create_models(ctx, kwargs, ServerConfig, DatabaseConfig)
@@ -2040,7 +2137,7 @@ Config = create_auto_model(
 # Use like any AutoWryModel
 @click.command()
 @Config.generate_click_parameters()
-def main(**kwargs):
+def main(**kwargs: Any):
     config = Config(**kwargs)
     print(f"{config.host}:{config.port}")
 ```

{wry-0.3.2.dev0 → wry-0.4.0}/CHANGELOG.md

@@ -7,6 +7,56 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2025-10-04
+
+### Added
+
+- **Automatic Pydantic alias-based CLI option generation** 🎉
+  - Aliases now automatically control generated CLI option names and environment variable names
+  - Example: `db_url` field with `alias="database_url"` generates `--database-url` option and `DB_DATABASE_URL` env var
+  - No configuration required - works out of the box!
+  - `WryModel` now sets `validate_by_name=True` and `validate_by_alias=True` by default
+  - Full source tracking support (CLI/ENV/JSON/DEFAULT) with aliases
+  - JSON config files accept both field names and aliases
+  - New example: `examples/field_alias_example.py` demonstrating automatic alias-based generation
+  - Note: For short options (e.g., `-v`), continue using explicit `click.option()` decorators as shown in `examples/auto_model_example.py`
+  - Comprehensive test suite: 20 tests covering all alias scenarios including precedence chains
+
+### Changed
+
+- **Pydantic v2.11+ compatibility** - replaced deprecated `populate_by_name` with `validate_by_name` and `validate_by_alias`
+- `WryModel.model_config` now includes `validate_by_name=True` and `validate_by_alias=True` by default
+- `generate_click_parameters()` now uses field aliases for auto-generated option names
+- `get_env_var_names()` now uses field aliases for environment variable names
+- Updated all documentation (README, AI_KNOWLEDGE_BASE, TODO) with alias feature details
+
+### Fixed
+
+- Source tracking now works correctly when using Pydantic aliases
+- JSON config loading properly handles both field names and aliases
+- Parameter source detection checks both alias and field name for Click compatibility
+- Removed all deprecated `Field(annotation=...)` usage in tests
+- All deprecation warnings eliminated for Pydantic v3 compatibility
+- Click now properly validates required arguments and options, providing native Click error messages
+- Fixed type display in `--show-env-vars` to correctly extract types from Annotated fields
+
+### Technical Details
+
+- Modified `from_click_context()` to build alias-to-field mapping and handle both field names and aliases
+- Enhanced kwargs filtering to accept both field names and aliases, mapping aliases back to field names for source tracking
+- Updated JSON config handling to map aliases to field names
+- Improved parameter source checking with alias fallback
+- Updated `generate_click_parameters()` to use aliases for option name generation
+- Updated `get_env_var_names()` to use aliases for environment variable names
+- Modified argument generation to properly handle `required` flag based on field defaults and environment variables
+- Removed forced `required=False` override in `extract_and_modify_argument_decorator()` to preserve original Click behavior
+- Improved `print_env_vars()` to correctly extract base types from Annotated fields
+- Consolidated 16 example files into 3 comprehensive examples for easier discovery:
+  - `examples/autowrymodel_comprehensive.py` - All AutoWryModel features
+  - `examples/wrymodel_comprehensive.py` - WryModel with source tracking
+  - `examples/multimodel_comprehensive.py` - Multi-model usage
+- All 436 tests pass with 92%+ code coverage
+
 ## [0.3.1] - 2025-10-02
 
 ### Fixed

{wry-0.3.2.dev0 → wry-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wry
-Version: 0.3.2.dev0
+Version: 0.4.0
 Summary: Why Repeat Yourself? - Define your CLI once with Pydantic models
 Author-email: Tyler House <26489166+tahouse@users.noreply.github.com>
 License: MIT
@@ -90,7 +90,7 @@ class AppArgs(AutoWryModel):
 
 @click.command()
 @AppArgs.generate_click_parameters()
-def main(**kwargs):
+def main(**kwargs: Any):
     """My simple CLI application."""
     # Create the model instance from kwargs
     config = AppArgs(**kwargs)
@@ -100,7 +100,10 @@ if __name__ == "__main__":
     main()
 ```
 
-**Note**: Currently, `generate_click_parameters()` passes individual parameters as kwargs to your function. You need to instantiate the model yourself. See the [Future Features](#future-features) section for a potential cleaner API.
+**See comprehensive examples:**
+- `examples/autowrymodel_comprehensive.py` - All AutoWryModel features including aliases
+- `examples/wrymodel_comprehensive.py` - WryModel with source tracking
+- `examples/multimodel_comprehensive.py` - Multi-model usage
 
 Run it:
 
@@ -129,7 +132,7 @@ wry tracks where each configuration value came from, supporting all four sources
 ```python
 @click.command()
 @AppArgs.generate_click_parameters()
-def main(**kwargs):
+def main(**kwargs: Any):
     # Simple instantiation - no source tracking
     config = AppArgs(**kwargs)
     # Works fine, but config.source.* will always show CLI
@@ -143,7 +146,7 @@ To enable accurate source tracking, use `@click.pass_context` and `from_click_co
 @click.command()
 @AppArgs.generate_click_parameters()
 @click.pass_context
-def main(ctx, **kwargs):
+def main(ctx: click.Context, **kwargs: Any):
     # Full source tracking with context
     config = AppArgs.from_click_context(ctx, **kwargs)
 
@@ -181,7 +184,8 @@ python examples/source_tracking_comprehensive.py --config examples/sample_config
 ```
 
 **Output shows source for each field:**
-```
+
+```text
 host         = json-server.com      [from JSON]
 port         = 3000                 [from CLI]    ← CLI overrides JSON
 debug        = True                 [from ENV]
@@ -257,7 +261,7 @@ class DatabaseArgs(WryModel):
 @click.command()
 @multi_model(ServerConfig, DatabaseConfig)
 @click.pass_context
-def serve(ctx, **kwargs):
+def serve(ctx: click.Context, **kwargs: Any):
     # Create model instances
     configs = create_models(ctx, kwargs, ServerConfig, DatabaseConfig)
     server = configs[ServerConfig]
@@ -330,7 +334,7 @@ class AppArgs(WryModel):
 @click.command()
 @multi_model(DatabaseConfig, AppArgs)
 @click.pass_context
-def main(ctx, **kwargs):
+def main(ctx: click.Context, **kwargs: Any):
     # Automatically splits kwargs between models
     configs = create_models(ctx, kwargs, DatabaseConfig, AppArgs)
 
@@ -349,7 +353,7 @@ By default, `generate_click_parameters` runs in strict mode to prevent common mi
 @click.command()
 @Config.generate_click_parameters()  # strict=True by default
 @Config.generate_click_parameters()  # ERROR: Duplicate decorator detected!
-def main(**kwargs):
+def main(**kwargs: Any):
     pass
 ```
 
@@ -391,6 +395,76 @@ class Config(WryModel):
     )
 ```
 
+### Using Pydantic Aliases for Custom CLI Names
+
+**New in v0.3.2+**: Pydantic field aliases automatically control the generated CLI option names and environment variable names!
+
+This allows you to have concise Python field names while exposing descriptive CLI options:
+
+```python
+from pydantic import Field
+from wry import AutoWryModel
+
+class DatabaseConfig(AutoWryModel):
+    env_prefix = "DB_"
+
+    # Concise Python field name: db_url
+    # Alias controls CLI option: --database-url
+    # Environment variable: DB_DATABASE_URL
+    db_url: str = Field(
+        alias="database_url",
+        default="sqlite:///app.db",
+        description="Database connection URL"
+    )
+
+    pool_size: int = Field(
+        alias="connection_pool_size",
+        default=5,
+        description="Maximum connection pool size"
+    )
+```
+
+**How it works:**
+
+- **Python field**: `db_url` (concise, easy to type)
+- **CLI option**: `--database-url` (descriptive, user-friendly)
+- **Environment variable**: `DB_DATABASE_URL` (consistent with CLI)
+- **JSON config**: Accepts both `db_url` and `database_url`
+
+**Requirements:**
+
+- **None!** `WryModel` automatically sets `validate_by_name=True` and `validate_by_alias=True`
+  - This tells Pydantic to accept both field names and aliases
+  - No need to configure anything - it just works!
+- Aliases automatically control option names, env var names, and help text
+
+**Full support (v0.3.2+):**
+
+- ✅ Aliases automatically control auto-generated option names
+- ✅ Environment variables use alias names (consistent with CLI)
+- ✅ Source tracking works correctly
+- ✅ JSON config accepts both field names and aliases
+
+**Why this feature exists:**
+
+Before v0.3.2, if you wanted custom CLI option names, you had to use explicit `click.option()` decorators for every field. The alias feature eliminates this boilerplate for the common case where you just want different names.
+
+**For advanced use cases** (short options, custom Click types):
+
+You can still combine aliases with explicit `click.option()` decorators:
+
+```python
+class Config(AutoWryModel):
+    # Explicit click.option for short option support
+    verbose: Annotated[int, click.option("-v", "--verbose", count=True)] = Field(default=0)
+```
+
+See `examples/autowrymodel_comprehensive.py` for examples of explicit Click decorators.
+
+**See also:**
+- `examples/autowrymodel_comprehensive.py` - Complete AutoWryModel example with aliases
+- `examples/wrymodel_comprehensive.py` - WryModel with aliases and source tracking
+
 ## Development
 
 ### Prerequisites