wry 0.4.1__tar.gz → 0.5.1.dev3__tar.gz

wry-0.5.1.dev3/.cursorrules

@@ -0,0 +1,192 @@
+# Cursor AI Rules for wry Repository
+
+> **Note**: These rules are the AI assistant's quick reference. For comprehensive guidelines,
+> examples, and detailed explanations, see `CONTRIBUTING.md`.
+
+## Pre-Commit Requirements
+
+Before making any commit, AI assistants MUST:
+
+1. **Update Documentation**:
+   - README.md if user-facing changes
+   - AI_KNOWLEDGE_BASE.md if architecture/API changes
+   - CHANGELOG.md with entry under [Unreleased]
+   - Module docstrings if relevant
+
+2. **Ensure Code Quality**:
+   - Add type annotations to all new functions
+   - Add docstrings to all public functions/classes
+   - Follow DRY principles
+   - Remove dead code and unused imports
+
+3. **Update/Add Tests**:
+   - Add tests for new functionality
+   - Update tests for changed behavior
+   - Ensure tests pass (run pytest)
+
+4. **Run Checks**:
+   - Ensure pre-commit hooks will pass
+   - Fix linter errors (ruff, mypy)
+   - Format code properly (ruff format)
+
+5. **Follow Conventional Commits**:
+   - Use format: `type: description`
+   - Types: feat, fix, docs, refactor, test, chore, build
+
+## Reference
+
+**Full development guidelines**: See `CONTRIBUTING.md` for:
+
+- Complete code organization principles
+- Detailed examples of adding features
+- wry-specific development patterns
+- Comprehensive pre-commit checklist
+- Pull request process
+
+**Quick links**:
+
+- Architecture & concepts: `CONTRIBUTING.md` "Core Concepts" section
+- Code patterns: `CONTRIBUTING.md` "Configuration Models" section
+- Testing guide: `CONTRIBUTING.md` "Testing" section
+- Pre-commit checklist: `CONTRIBUTING.md` "Pre-Commit Checklist" section
+
+## Enforcement
+
+The pre-commit hook automatically runs checks on commit.
+All checks must pass before commit succeeds.
+
+## General Development Guidelines
+
+### Date and Time
+
+- Use the `date` terminal command to learn the current date
+- Never assume or hardcode dates in dynamic contexts
+
+### Python Best Practices
+
+#### Type Annotations
+
+- **ALWAYS** add type annotations to all functions, methods, and class attributes
+- Include return types for all functions (use `-> None` for void functions)
+- Use proper generic types from `typing` module
+- Prefer modern Python 3.10+ syntax (e.g., `list[str]` over `List[str]`)
+
+#### Documentation
+
+- Add comprehensive docstrings to:
+  - All modules (at the top of the file)
+  - All classes (describing purpose, attributes, and usage)
+  - All public functions and methods (describing parameters, return values, and exceptions)
+- Use consistent docstring format (Google style preferred)
+
+#### Code Quality
+
+- **DRY Principles**: Don't Repeat Yourself - extract common logic into reusable functions/classes
+- **Clean Code**: Write self-documenting code with clear variable and function names
+- **No Dead Code**: Remove unused variables, functions, and commented-out code unless it serves as important documentation
+- **Maintainability**: Prioritize code that is easy to understand, modify, and extend
+
+### Linter and Type Checker Compliance
+
+#### Fixing Issues Properly
+
+- **ALWAYS** fix linter errors and type checker warnings properly
+- **AVOID** using ignore directives like `# type: ignore`, `# noqa` as quick fixes
+- **AVOID** using `cast()` unless absolutely critical for complex type scenarios
+- Investigate the root cause and fix issues with proper type annotations and code structure
+- If an ignore directive is truly necessary, add a detailed comment explaining why
+
+#### Working Directory
+
+- **ALWAYS** ensure you're in the correct directory before:
+  - Running commands
+  - Creating files
+  - Executing scripts
+  - Making git operations
+
+### Testing
+
+#### Test Coverage
+
+- **NEVER** ignore, skip, or disable test cases just to make test suites pass
+- If a test fails, fix the underlying issue or update the test if requirements changed
+- Add tests for all new functionality
+- Update tests when changing existing behavior
+- Ensure all tests **PASS** before considering work complete
+
+#### Test Organization
+
+- Place test code in the most logical location (follow project structure under `tests/`)
+- Name test files and functions clearly to indicate what they're testing
+- Use descriptive test names: `test_<function>_<scenario>_<expected_result>`
+
+### Documentation Management
+
+#### Markdown Files
+
+- **Do not create excessive markdown files** unless explicitly instructed
+- If markdown files exist, add content to the appropriate existing file
+- If unsure which file is appropriate, **ask the user** where content should go
+- Before creating a new markdown file, consider: Did the user actually request documentation?
+
+### Git Best Practices
+
+#### Committing Changes
+
+- Attempt to commit changes after completing major features or fixes
+- Use **Conventional Commits** format: `<type>: <description>`
+  - Examples: `feat: add comma-separated list support`, `fix: handle ClassVar in AutoWryModel`
+
+#### Pre-Commit Hooks - CRITICAL RULE
+
+- **NEVER** use `git commit --no-verify` or `--no-gpg-sign` to bypass pre-commit hooks
+- **ONLY EXCEPTION**: When the user explicitly says it's okay
+- If pre-commit hooks fail:
+  1. Fix the underlying issue (don't bypass)
+  2. Ask the user for guidance if you can't fix it
+  3. Wait for user approval before using --no-verify
+- Pre-commit hooks catch bugs, enforce quality, and save code review time
+- Bypassing them should be extremely rare (emergency situations only with approval)
+
+#### File Operations
+
+- **Strongly prefer** using Git commands for file operations:
+  - Use `git rm` instead of `rm` when deleting tracked files
+  - Use `git mv` instead of `mv` when moving/renaming tracked files
+- This ensures Git properly tracks file history instead of treating operations as delete+add
+- Always pass `--yes` or appropriate non-interactive flags to avoid user prompts
+- **NEVER** use `git push --force` to main/master without explicit user approval
+- **NEVER** use `git reset --hard` without explicit user approval
+
+## wry-Specific Guidelines
+
+### Model Development
+
+- All `WryModel` and `AutoWryModel` classes should use `ClassVar` for class-level configuration
+- Source tracking is a core feature - ensure it works for new features
+- List fields automatically get `multiple=True` unless `comma_separated_lists` is enabled
+- Document behavior in both README.md and AI_KNOWLEDGE_BASE.md
+
+### Click Integration
+
+- All Click parameter generation should respect Pydantic field metadata
+- Help text should be clear and include constraints
+- Arguments should inject help into docstrings (Click limitation workaround)
+
+### Testing Requirements
+
+- Test all four configuration sources: CLI, ENV, JSON, DEFAULT
+- Test source tracking for new features
+- Test both standard and edge cases
+- Use `CliRunner` for Click command tests
+
+## Summary
+
+These rules ensure:
+
+- High code quality and maintainability
+- Proper type safety and documentation
+- Comprehensive test coverage
+- Clean git history
+- Consistent development practices
+- wry's core features (source tracking, Click integration) work correctly

{wry-0.4.1 → wry-0.5.1.dev3}/AI_KNOWLEDGE_BASE.md

@@ -938,17 +938,175 @@ modified_arg = click.argument("field")  # No help parameter
 
 ### 5. List Fields Auto-Get multiple=True
 
+**Automatic behavior**: wry detects `list[T]` and `tuple[T, ...]` types and automatically adds `multiple=True` to the generated Click option.
+
 ```python
 tags: list[str] = Field(default_factory=list)
 
 # Auto-generates:
 click.option("--tags", multiple=True, type=click.STRING)
 
-# Usage:
+# CORRECT Usage - specify option multiple times:
 # --tags python --tags rust --tags go
 # Result: tags=["python", "rust", "go"]
+
+# Also correct - single value:
+# --tags python
+# Result: tags=["python"]
+
+# Also correct - no values (uses default):
+# (no --tags)
+# Result: tags=[]
+```
+
+**IMPORTANT - Comma-separated values NOT supported**:
+
+```python
+# ❌ INCORRECT - This does NOT work as expected:
+# --tags python,rust,go
+# Result: tags=["python,rust,go"]  ← Single string with commas!
+
+# This is Click's behavior, not a wry limitation.
+# Users MUST pass the option multiple times for multiple values.
+```
+
+**Why not comma-separated?**
+
+- Click's `multiple=True` expects the option to be repeated
+- Comma parsing would require custom Click types
+- This matches standard Unix CLI conventions (see: grep -e, docker -v)
+
+**Works with all list types**:
+
+```python
+tags: list[str]        # Strings
+ports: list[int]       # Integers (with type validation)
+flags: list[bool]      # Booleans
+values: tuple[str, ...]  # Tuples also supported
+```
+
+**Tests**: See `tests/unit/auto_model/test_auto_model_list_fields.py` for comprehensive test coverage (11 tests)
+
+**Comma-Separated Alternative (NEW)**:
+
+For users who prefer comma-separated input, wry offers **two approaches**:
+
+**Approach 1: Per-Field Annotation (fine-grained control)**
+
+```python
+from wry import AutoWryModel, CommaSeparated
+from typing import Annotated
+
+class Config(AutoWryModel):
+    # Standard: --tags a --tags b --tags c
+    standard_tags: list[str] = Field(default_factory=list)
+
+    # Comma-separated: --csv-tags a,b,c
+    csv_tags: Annotated[list[str], CommaSeparated] = Field(
+        default_factory=list,
+        description="Comma-separated tags"
+    )
+
+    # Works with all types:
+    ports: Annotated[list[int], CommaSeparated] = Field(default_factory=list)
+    values: Annotated[list[float], CommaSeparated] = Field(default_factory=list)
+```
+
+**Approach 2: Model-Wide ClassVar (all list fields)**
+
+```python
+from wry import AutoWryModel
+from typing import ClassVar
+
+class Config(AutoWryModel):
+    # Enable comma-separated for ALL list fields
+    comma_separated_lists: ClassVar[bool] = True
+
+    # All these now accept comma-separated input
+    tags: list[str] = Field(default_factory=list)       # --tags a,b,c
+    ports: list[int] = Field(default_factory=list)      # --ports 80,443
+    values: list[float] = Field(default_factory=list)   # --values 1.5,2.7
 ```
 
+**Which to use?**
+
+- **Per-field**: When only specific fields should be comma-separated, or mixing styles
+- **Model-wide**: When all lists should consistently use comma-separated (Docker-style CLIs)
+
+**How it works**:
+
+- **Per-field**: Detects `CommaSeparated` in field metadata
+- **Model-wide**: Checks `comma_separated_lists: ClassVar[bool]` on model class
+- Per-field annotation takes priority over model-wide setting
+- Uses custom Click `ParamType` (CommaSeparatedStrings, CommaSeparatedInts, CommaSeparatedFloats)
+- Disables `multiple=True` for comma-separated fields
+- Parses comma-separated input and strips whitespace
+- Filters out empty items from multiple commas
+
+**Model-wide ClassVar details**:
+
+- Works like `env_prefix: ClassVar[str]` - a class-level configuration
+- Defined as `comma_separated_lists: ClassVar[bool] = False` in WryModel base
+- NOT included in Pydantic model fields (won't appear in `model_fields` or `model_dump()`)
+- AutoWryModel skips ClassVar fields during automatic processing
+- Can be overridden in child classes
+
+**Trade-offs**:
+
+- ✅ More concise for many values
+- ✅ Familiar to users of tools accepting comma-separated lists
+- ⚠️ Cannot combine with repeating option
+- ⚠️ Commas in values need escaping/quoting
+- ⚠️ Less discoverable (users might not know about comma support)
+
+**When to use**:
+
+- Tool has established comma-separated convention
+- Users expect Docker-style `-p 80,443,8080` syntax
+- Values never contain commas
+
+**When NOT to use**:
+
+- Users are accustomed to `grep -e` style repetition
+- Values might contain commas
+- Discoverability is important (repeating options is more obvious)
+
+**Default recommendation**: Use standard `multiple=True` (default behavior) unless you have specific reasons to use comma-separated.
+
+**Test Coverage (22 tests total)**:
+
+Standard `multiple=True` tests (`test_auto_model_list_fields.py` - 11 tests):
+
+- ✅ Auto-generation of `multiple=True` for `list[str]`, `list[int]`, `list[bool]`, `tuple[T, ...]`
+- ✅ Default values (Field default, default_factory)
+- ✅ Pydantic constraints (min_length, max_length) enforcement
+- ✅ Source tracking (CLI/ENV/JSON/DEFAULT)
+- ✅ JSON config integration
+- ✅ Help text generation
+- ✅ Empty list vs no value distinction
+- ✅ Environment variable behavior documented
+
+Comma-separated tests (`test_comma_separated_lists.py` - 11 tests):
+
+- ✅ Per-field annotation: `Annotated[list[T], CommaSeparated]` for str/int/float
+- ✅ Model-wide ClassVar: `comma_separated_lists: ClassVar[bool] = True`
+- ✅ Mixed usage (standard + comma-separated in same model)
+- ✅ Per-field annotation overrides model-wide setting
+- ✅ Whitespace handling, empty item filtering, trailing commas
+- ✅ Type conversion validation (invalid int/float)
+- ✅ Pydantic validation still works (min_length, max_length)
+- ✅ JSON config integration with comma-separated
+- ✅ Source tracking works correctly
+- ✅ ClassVar not included in model_fields or model_dump()
+
+Edge cases validated:
+
+- Multiple consecutive commas → filtered
+- Single value without comma → works
+- Mixing both styles in same model → works
+- Type conversion errors → proper error messages
+- Default values with both approaches → works
+
 ### 6. Optional Types Handled
 
 ```python

{wry-0.4.1 → wry-0.5.1.dev3}/CHANGELOG.md

@@ -7,6 +7,106 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **Development guidelines** 📚
+  - Created `.cursorrules` as AI assistant's quick reference guide
+  - Created `CONTRIBUTING.md` as comprehensive contributor guide
+  - `.cursorrules` references `CONTRIBUTING.md` for detailed explanations
+  - Both tailored specifically for wry development patterns
+
+### Tests
+
+- **Additional comma-separated test** (494 total tests)
+  - `test_model_wide_setting_does_not_affect_non_list_fields`
+  - Validates that `comma_separated_lists: ClassVar[bool] = True` only affects list fields
+  - Non-list fields (str, int, bool) work normally
+  - Explicit `click.option` decorators (like `-vvv` for verbose) are not affected
+  - Tests real-world use case: model-wide comma-separated + verbose counting
+
+## [0.5.0] - 2025-10-14
+
+### Added
+
+- **Comprehensive list field support** 🎯
+  - `list[str]`, `list[int]`, `list[float]`, `tuple[T, ...]` automatically get `multiple=True`
+  - Standard behavior: `--tags python --tags rust --tags go` (repeat option)
+  - Users must repeat the option for multiple values (Click's standard `multiple=True`)
+  - Comma-separated values NOT supported by default (documented as intentional)
+
+- **Comma-separated list input (opt-in)** ✨
+  - Two ways to enable comma-separated parsing:
+    1. **Per-field annotation**: `Annotated[list[str], CommaSeparated]`
+    2. **Model-wide ClassVar**: `comma_separated_lists: ClassVar[bool] = True`
+  - Usage: `--tags python,rust,go` (single invocation with commas)
+  - Works with all list types: `list[str]`, `list[int]`, `list[float]`
+  - Custom Click ParamTypes: `CommaSeparatedStrings`, `CommaSeparatedInts`, `CommaSeparatedFloats`
+  - Per-field annotation takes priority over model-wide setting
+  - Automatically strips whitespace and filters empty items
+  - Full Pydantic validation preserved (min_length, max_length, etc.)
+
+- **ClassVar configuration: `comma_separated_lists`**
+  - Works like `env_prefix: ClassVar[str]` - class-level configuration
+  - NOT included in Pydantic model fields (won't appear in `model_fields` or `model_dump()`)
+  - Can be set on model class to enable comma-separated for all list fields
+  - Can be overridden in child classes
+  - AutoWryModel correctly skips ClassVar fields during processing
+
+### Fixed
+
+- **AutoWryModel ClassVar handling** 🐛
+  - Fixed bug where ClassVar annotations (like `env_prefix`, `comma_separated_lists`) would cause errors
+  - AutoWryModel now properly skips ClassVar fields during automatic processing
+  - Prevents `TypeError: typing.ClassVar[T] is not valid as type argument`
+
+### Tests
+
+- **22 new comprehensive tests** (471 → 493 total tests)
+  - `tests/unit/auto_model/test_auto_model_list_fields.py` - 11 tests for standard behavior
+    - Multiple types (str, int, bool, tuple)
+    - Default values, constraints, source tracking
+    - JSON config, environment variables, help text
+  - `tests/unit/auto_model/test_comma_separated_lists.py` - 11 tests for comma-separated
+    - Per-field annotations (7 tests)
+    - Model-wide ClassVar (2 tests)
+    - Mixed usage (2 tests)
+    - Edge cases: whitespace, empty items, type validation
+
+### Documentation
+
+- **README.md List Type Fields section**
+  - Clear explanation of standard `multiple=True` behavior
+  - Documentation that comma-separated is NOT default (by design)
+  - Two approaches for comma-separated (per-field and model-wide)
+  - Usage examples for both approaches
+  - Trade-offs and recommendations
+  - Implementation notes (ClassVar, priority rules, type support)
+
+- **AI_KNOWLEDGE_BASE.md comprehensive update**
+  - Edge case #5: List Fields Auto-Get multiple=True (expanded significantly)
+  - Detailed explanation of both standard and comma-separated approaches
+  - How it works: detection, type selection, parsing, priority
+  - Model-wide ClassVar details (similar to env_prefix pattern)
+  - Complete test coverage breakdown (22 tests documented)
+  - Edge cases validated
+  - When to use each approach
+
+- **Module docstrings**
+  - `wry/comma_separated.py` - Complete module documentation with both approaches
+  - Custom ParamType implementations with full docstrings
+
+### Technical Details
+
+- New module: `wry/comma_separated.py` with custom Click ParamTypes
+- Modified `wry/core/model.py`: Added `comma_separated_lists: ClassVar[bool] = False`
+- Modified `wry/auto_model.py`: Skip ClassVar fields (lines 62-68)
+- Modified `wry/click_integration.py`: Detect and handle comma-separated (lines 431-454)
+- Export `CommaSeparated` from `wry/__init__.py`
+
+### Breaking Changes
+
+None - all changes are opt-in or additive.
+
 ## [0.4.1] - 2025-10-07
 
 ### Fixed