@bcelep/capint 0.4.2 → 0.7.0

package/skills/dignified-python/references/README.md

@@ -0,0 +1,319 @@
+# Dignified Python Reference Documentation
+
+Production-quality Python coding standards for writing clean, maintainable, modern Python code.
+
+## Table of Contents
+
+### Core Standards
+
+- **[core-standards.md](./core-standards.md)** - Essential Python standards (always apply)
+  - Modern type syntax (list[str], str | None)
+  - LBYL exception handling patterns
+  - Pathlib operations
+  - Absolute imports
+  - Error boundaries
+
+- **[cli-patterns.md](./cli-patterns.md)** - Command-line interface patterns
+  - Click usage patterns
+  - Argparse best practices
+  - CLI error handling
+  - Configuration management
+
+### Version-Specific Features (`versions/`)
+
+- **[python-3.10.md](./versions/python-3.10.md)** - Python 3.10+ features
+  - Structural pattern matching (match/case)
+  - Parenthesized context managers
+  - Better error messages
+  - Type union operator (X | Y)
+
+- **[python-3.11.md](./versions/python-3.11.md)** - Python 3.11+ features
+  - Exception groups (ExceptionGroup)
+  - except\* syntax
+  - Self type
+  - Variadic generics
+
+- **[python-3.12.md](./versions/python-3.12.md)** - Python 3.12+ features
+  - Type parameter syntax (Generic[T])
+  - Override decorator
+  - Per-interpreter GIL
+  - f-string improvements
+
+- **[python-3.13.md](./versions/python-3.13.md)** - Python 3.13+ features
+  - Experimental free-threading
+  - JIT compilation
+  - Improved error messages
+  - Performance improvements
+
+### Advanced Topics (`advanced/`)
+
+- **[exception-handling.md](./advanced/exception-handling.md)** - Exception patterns
+  - LBYL (Look Before You Leap) patterns
+  - Error boundaries
+  - Exception chaining
+  - Custom exceptions
+
+- **[interfaces.md](./advanced/interfaces.md)** - Interface design
+  - ABC (Abstract Base Class) patterns
+  - Protocol types
+  - Gateway layer interfaces
+  - Type narrowing
+
+- **[typing-advanced.md](./advanced/typing-advanced.md)** - Advanced typing
+  - Generic types
+  - Type narrowing
+  - Literal types
+  - TypedDict and dataclasses
+
+- **[api-design.md](./advanced/api-design.md)** - API design principles
+  - Function signatures
+  - Parameter complexity
+  - Code organization
+  - Production patterns from Dagster Labs
+
+## Philosophy
+
+### Core Principles
+
+**Modern Type Syntax**: Use Python 3.10+ type syntax everywhere
+
+```python
+# Good (modern)
+def process(items: list[str]) -> str | None:
+    pass
+
+# Avoid (legacy)
+from typing import List, Optional
+def process(items: List[str]) -> Optional[str]:
+    pass
+```
+
+**LBYL Over EAFP**: Look Before You Leap, not Easier to Ask for Forgiveness than Permission
+
+```python
+# Good (LBYL)
+if path.exists():
+    content = path.read_text()
+
+# Avoid (EAFP)
+try:
+    content = path.read_text()
+except FileNotFoundError:
+    pass
+```
+
+**Pathlib Over os.path**: Use pathlib for all file operations
+
+```python
+# Good
+from pathlib import Path
+config_path = Path("config.yaml")
+if config_path.exists():
+    content = config_path.read_text()
+
+# Avoid
+import os
+if os.path.exists("config.yaml"):
+    with open("config.yaml") as f:
+        content = f.read()
+```
+
+**Absolute Imports**: Never use relative imports
+
+```python
+# Good
+from myproject.utils import helper
+
+# Avoid
+from .utils import helper
+from ..shared import helper
+```
+
+**Error Boundaries at CLI Level**: Handle errors at the CLI entry point, not deep in the stack
+
+## Quick Reference
+
+### Type Annotations
+
+```python
+# Basic types
+def greet(name: str) -> str:
+    return f"Hello, {name}"
+
+# Collections (modern syntax)
+def process(items: list[str], mapping: dict[str, int]) -> tuple[str, int]:
+    pass
+
+# Optional/Union (modern syntax)
+def find(query: str) -> str | None:
+    pass
+
+# Multiple types
+def parse(value: str | int | float) -> float:
+    pass
+```
+
+### LBYL Patterns
+
+```python
+# File operations
+if path.exists():
+    content = path.read_text()
+
+# Dictionary access
+if "key" in data:
+    value = data["key"]
+
+# Attribute access
+if hasattr(obj, "method"):
+    obj.method()
+
+# Type checking
+if isinstance(value, str):
+    result = value.upper()
+```
+
+### Pathlib Operations
+
+```python
+from pathlib import Path
+
+# Create path
+config = Path("config.yaml")
+data_dir = Path("/data")
+
+# Check existence
+if config.exists():
+    pass
+
+# Read/write
+content = config.read_text()
+config.write_text("data")
+
+# Directory operations
+for file in data_dir.glob("*.txt"):
+    print(file.name)
+
+# Path manipulation
+full_path = data_dir / "subdir" / "file.txt"
+parent = full_path.parent
+name = full_path.name
+```
+
+### CLI Patterns (Click)
+
+```python
+import click
+
+@click.command()
+@click.option("--name", required=True, help="User name")
+@click.option("--count", default=1, help="Number of times")
+def greet(name: str, count: int) -> None:
+    """Greet a user multiple times."""
+    for _ in range(count):
+        click.echo(f"Hello, {name}!")
+
+if __name__ == "__main__":
+    greet()
+```
+
+## Version Detection
+
+**Automatic version detection** determines which Python version features are available:
+
+1. Check `pyproject.toml` for `requires-python` field
+2. Check `setup.py`/`setup.cfg` for `python_requires`
+3. Check `.python-version` file
+4. Default to Python 3.12 if not specified
+
+Based on detected version, appropriate version-specific features are recommended.
+
+## Navigation Tips
+
+- **Start with core-standards.md** for essential patterns that apply to all code
+- **Check version-specific docs** based on your project's Python version
+- **Reference advanced topics** when dealing with specialized patterns
+- **Use cli-patterns.md** when building command-line tools
+
+## When to Read Each Reference
+
+| Situation                  | Reference                      |
+| -------------------------- | ------------------------------ |
+| Writing any Python code    | core-standards.md              |
+| Building a CLI tool        | cli-patterns.md                |
+| Using Python 3.10 features | versions/python-3.10.md        |
+| Using Python 3.11 features | versions/python-3.11.md        |
+| Using Python 3.12 features | versions/python-3.12.md        |
+| Using Python 3.13 features | versions/python-3.13.md        |
+| Handling exceptions        | advanced/exception-handling.md |
+| Designing interfaces       | advanced/interfaces.md         |
+| Complex type hints         | advanced/typing-advanced.md    |
+| API design decisions       | advanced/api-design.md         |
+
+## Related Skills
+
+- **`/dagster-best-practices`** - Dagster-specific patterns (not general Python)
+- **`/dg`** - Dagster CLI operations
+- **`/dagster-expert`** - Dagster expertise including integrations
+
+**Important**: `/dignified-python` is for **general Python standards**, not Dagster-specific
+patterns. For Dagster patterns, use `/dagster-best-practices`.
+
+## Cross-Skill Usage
+
+Users invoke `/dignified-python` when they need Python code quality guidance, regardless of whether
+it's for a Dagster project or any other Python project.
+
+**Workflow:**
+
+```
+User: "Is this good Python code?"
+→ /dignified-python (check core-standards.md)
+→ Apply modern type syntax, LBYL, pathlib patterns
+→ Check version-specific features based on project
+
+User: "How should I structure my Dagster assets?"
+→ /dagster-best-practices (NOT dignified-python)
+→ Learn asset patterns, dependencies, partitions
+```
+
+## Production Patterns
+
+These standards are based on production-tested patterns from Dagster Labs:
+
+- ✅ **Modern type syntax** - Improves IDE support and type checking
+- ✅ **LBYL patterns** - More explicit and easier to debug than EAFP
+- ✅ **Pathlib** - More readable and cross-platform than os.path
+- ✅ **Absolute imports** - Avoid import confusion and relative import issues
+- ✅ **Error boundaries at CLI** - Clean error messages for end users
+
+## Documentation Structure
+
+Each reference document follows a consistent structure:
+
+1. **Overview** - High-level concepts
+2. **Patterns** - Common code patterns with examples
+3. **Best Practices** - Recommended approaches
+4. **Anti-Patterns** - What to avoid
+5. **Real-World Examples** - Production code samples
+6. **Related Topics** - Cross-references
+
+## Self-Selecting Usage
+
+Users only invoke `/dignified-python` when they want Python standards guidance. The skill
+description makes it clear it's for general Python quality, not Dagster-specific patterns, so users
+naturally select it when appropriate.
+
+**Users will invoke this when they want:**
+
+- Code review and quality improvements
+- Modern Python patterns
+- Type annotation guidance
+- Exception handling best practices
+- CLI implementation patterns
+
+**Users will NOT invoke this when they want:**
+
+- Dagster-specific patterns (they'll use `/dagster-best-practices`)
+- Creating Dagster projects (they'll use `/dg`)
+- Finding integrations (they'll use `/dagster-expert`)

package/skills/dignified-python/references/advanced/api-design.md

@@ -0,0 +1,230 @@
+---
+description:
+  Default parameter dangers, keyword-only arguments, ThreadPoolExecutor patterns, speculative test
+  infrastructure.
+---
+
+# API Design Reference
+
+**Read when**: Adding default parameters, functions with 5+ params, using ThreadPoolExecutor
+
+---
+
+## Default Parameter Values Are Dangerous
+
+> **Scope:** This rule applies to **function definitions** (`def foo(bar: bool = False)`), NOT to
+> **function calls** where you pass an argument named `default` (e.g.,
+> `click.confirm(default=True)`). Passing `default=True` to a function that accepts a `default`
+> parameter is perfectly valid—you're not creating a default parameter value, you're explicitly
+> providing a value.
+
+**Avoid default parameter values unless absolutely necessary.** They are a significant source of
+bugs.
+
+**Why defaults are dangerous:**
+
+1. **Silent incorrect behavior** - Callers forget to pass a parameter and get unexpected results
+2. **Hidden coupling** - The default encodes an assumption that may not hold for all callers
+3. **Audit difficulty** - Hard to verify all call sites are using the right value
+4. **Refactoring hazard** - Adding a new parameter with a default doesn't trigger errors at existing
+   call sites
+
+```python
+# DANGEROUS: Default that might be wrong for some callers
+def process_file(path: Path, encoding: str = "utf-8") -> str:
+    return path.read_text(encoding=encoding)
+
+# Caller forgets encoding, silently gets wrong behavior for legacy file
+content = process_file(legacy_latin1_file)  # Bug: should be encoding="latin-1"
+
+# SAFER: Require explicit choice
+def process_file(path: Path, encoding: str) -> str:
+    return path.read_text(encoding=encoding)
+
+# Caller must think about encoding
+content = process_file(legacy_latin1_file, encoding="latin-1")
+```
+
+**When you discover a default is never overridden, eliminate it:**
+
+```python
+# If every call site uses the default...
+activate_worktree(ctx, repo, path, script, "up", preserve_relative_path=True)  # Always True
+activate_worktree(ctx, repo, path, script, "down", preserve_relative_path=True)  # Always True
+
+# CORRECT: Remove the parameter entirely
+def activate_worktree(ctx, repo, path, script, command_name) -> None:
+    # Always preserve relative path - it's just the behavior
+    ...
+```
+
+**Acceptable uses of defaults:**
+
+1. **Truly optional behavior** - Where the default is correct for 95%+ of callers
+2. **Backwards compatibility** - When adding a parameter to existing API (temporary)
+3. **Test helper functions** - Functions in `tests/test_utils/` that exist to reduce test
+   boilerplate are explicitly exempt. These helpers often wrap complex constructors (like
+   `format_plan_header_body`) with sensible defaults, and having many default parameters is their
+   intended purpose—not a code smell
+
+**When reviewing code with defaults, ask:**
+
+- Do all call sites actually want this default?
+- Would a caller forgetting this parameter cause a bug?
+- Is there a safer design that makes the choice explicit?
+
+---
+
+## Keyword-Only Arguments for Complex Functions
+
+**Functions with 5 or more parameters MUST use keyword-only arguments.**
+
+Use the `*` separator after the first positional parameter to enforce keyword-only at the language
+level. This improves call-site readability by forcing explicit parameter names.
+
+```python
+# CORRECT: Keyword-only after first param
+def fetch_data(
+    url,
+    *,
+    timeout: float,
+    retries: int,
+    headers: dict[str, str],
+    auth_token: str,
+) -> Response:
+    ...
+
+# Call site is self-documenting
+response = fetch_data(
+    api_url,
+    timeout=30.0,
+    retries=3,
+    headers={"Accept": "application/json"},
+    auth_token=token,
+)
+
+# WRONG: All positional parameters
+def fetch_data(
+    url,
+    timeout: float,
+    retries: int,
+    headers: dict[str, str],
+    auth_token: str,
+) -> Response:
+    ...
+
+# Call site is unreadable - what do these values mean?
+response = fetch_data(api_url, 30.0, 3, {"Accept": "application/json"}, token)
+```
+
+**Exceptions:**
+
+1. **`self`** - Always positional (Python requirement)
+2. **`ctx` / context objects** - Can remain positional as the first parameter (convention)
+3. **ABC/Protocol methods** - Exempt to avoid forcing all implementations to change signatures
+4. **Click callbacks** - Click injects parameters; follow Click conventions
+
+```python
+# CORRECT: ctx stays positional, rest are keyword-only
+def create_worktree(
+    ctx: ErkContext,
+    *,
+    branch_name: str,
+    base_branch: str,
+    path: Path,
+    checkout: bool,
+) -> WorktreeInfo:
+    ...
+```
+
+---
+
+## ThreadPoolExecutor.submit() Pattern
+
+`ThreadPoolExecutor.submit()` passes arguments positionally to the callable. For functions with
+keyword-only parameters, wrap the call in a lambda:
+
+```python
+# WRONG: submit() passes args positionally - fails with keyword-only functions
+future = executor.submit(fetch_data, url, timeout, retries, headers, token)
+
+# CORRECT: Lambda enables keyword arguments
+future = executor.submit(
+    lambda: fetch_data(
+        url,
+        timeout=timeout,
+        retries=retries,
+        headers=headers,
+        auth_token=token,
+    )
+)
+```
+
+---
+
+## Speculative Test Infrastructure
+
+**Don't add parameters to fakes "just in case" they might be useful for testing.**
+
+Fakes should mirror production interfaces. Adding test-only configuration knobs that never get used
+creates dead code and false complexity.
+
+```python
+# WRONG: Test-only parameter that's never used in production
+class FakeGitHub:
+    def __init__(
+        self,
+        prs: dict[str, PullRequestInfo] | None = None,
+        rate_limited: bool = False,  # "Might test this later"
+    ) -> None:
+        self._rate_limited = rate_limited  # Never set to True anywhere
+
+# CORRECT: Only add infrastructure when you need it
+class FakeGitHub:
+    def __init__(
+        self,
+        prs: dict[str, PullRequestInfo] | None = None,
+    ) -> None:
+        ...
+```
+
+**The test for this:** If grep shows a parameter is only ever passed in test files, and those tests
+are testing hypothetical scenarios rather than actual production behavior, delete both the parameter
+and the tests.
+
+---
+
+## Speculative Tests
+
+```python
+# FORBIDDEN: Tests for future features
+# def test_feature_we_might_add():
+#     pass
+
+# CORRECT: TDD for current implementation
+def test_feature_being_built_now():
+    result = new_feature()
+    assert result == expected
+```
+
+---
+
+## Decision Checklist
+
+Before adding a default parameter value:
+
+- [ ] Do 95%+ of callers actually want this default?
+- [ ] Would forgetting to pass this parameter cause a subtle bug?
+- [ ] Is there a safer design that makes the choice explicit?
+- [ ] If the default is never overridden anywhere, should this parameter exist at all?
+
+**Default: Require explicit values; eliminate unused defaults**
+
+Before adding a function with 5+ parameters:
+
+- [ ] Have I added `*` after the first (or ctx) parameter?
+- [ ] Is only `self`/`ctx` positional?
+- [ ] Is this an ABC/Protocol method? (exempt from rule)
+- [ ] If using ThreadPoolExecutor.submit(), am I using a lambda wrapper?
+
+**Default: All parameters after the first should be keyword-only**