python-skills 1.0.0__py3-none-any.whl

skills/generation/type_hints.md

@@ -0,0 +1,290 @@
+# Generation: Type Hints
+
+**Purpose**: Modern Python typing guidance for code generation.
+
+**When to use**: All code generation. Type hints improve correctness and maintainability.
+
+---
+
+## Core Rules
+
+### Basic Annotations
+```python
+# Variables
+count: int = 0
+name: str = "default"
+items: list[str] = []
+mapping: dict[str, int] = {}
+
+# Functions
+def func(arg: int, optional: str = "default") -> bool:
+    ...
+
+# Classes
+class MyClass:
+    attr: int
+    def method(self, x: float) -> str: ...
+```
+
+### Built-in Generics (Python 3.9+)
+```python
+# Preferred (no typing import needed)
+list[str]
+dict[str, int]
+set[int]
+tuple[int, str, bool]
+tuple[int, ...]      # Variable-length tuple
+collections.abc.Iterable[int]
+collections.abc.Sequence[str]
+collections.abc.Mapping[str, int]
+```
+
+### Union Types (Python 3.10+)
+```python
+# Preferred
+int | str
+list[int | str]
+dict[str, int | None]
+
+# Legacy (still works)
+from typing import Union
+Union[int, str]
+```
+
+### Optional
+```python
+# Python 3.10+
+str | None
+
+# Legacy
+from typing import Optional
+Optional[str]
+```
+
+### Type Aliases (Python 3.12+)
+```python
+type JSONValue = str | int | float | bool | None | list["JSONValue"] | dict[str, "JSONValue"]
+type UserID = int
+```
+
+### TypeVar and Generics
+```python
+from typing import TypeVar, Generic
+
+T = TypeVar("T")
+K = TypeVar("K")
+V = TypeVar("V")
+
+class Container(Generic[T]):
+    def __init__(self, value: T) -> None:
+        self.value = value
+    
+    def get(self) -> T:
+        return self.value
+
+# Usage
+int_container: Container[int] = Container(42)
+```
+
+### Protocols (Structural Typing)
+```python
+from typing import Protocol
+
+class Drawable(Protocol):
+    def draw(self) -> None: ...
+
+class Circle:
+    def draw(self) -> None:  # Implicitly implements Drawable
+        ...
+
+def render(d: Drawable) -> None:
+    d.draw()
+```
+
+### Callable Types
+```python
+from typing import Callable
+
+# Function taking (int, str) returning bool
+callback: Callable[[int, str], bool]
+
+# More flexible
+from collections.abc import Callable
+handler: Callable[..., Any]
+```
+
+### TypedDict (Structured Dicts)
+```python
+from typing import TypedDict, NotRequired
+
+class UserDict(TypedDict):
+    id: int
+    name: str
+    email: NotRequired[str]  # Optional key (3.11+)
+    # or: email: str | None  # Required key, nullable value
+
+def process_user(user: UserDict) -> None:
+    print(user["name"])
+```
+
+### Dataclasses with Types
+```python
+from dataclasses import dataclass
+from typing import Optional
+
+@dataclass
+class User:
+    id: int
+    name: str
+    email: Optional[str] = None
+    tags: list[str] = field(default_factory=list)
+```
+
+### Overloads
+```python
+from typing import overload
+
+@overload
+def func(x: int) -> int: ...
+@overload
+def func(x: str) -> str: ...
+def func(x: int | str) -> int | str:
+    return x
+```
+
+### Final and Literal
+```python
+from typing import Final, Literal
+
+MAX_SIZE: Final = 100
+Mode = Literal["fast", "slow", "auto"]
+mode: Mode = "fast"
+```
+
+### Self Type (Python 3.11+)
+```python
+from typing import Self
+
+class Builder:
+    def set_name(self, name: str) -> Self:
+        self.name = name
+        return self
+    
+    def build(self) -> Product:
+        return Product(self.name)
+```
+
+### Type Narrowing
+```python
+def process(value: int | str) -> str:
+    if isinstance(value, int):
+        return str(value)  # value is int here
+    return value           # value is str here
+
+# With user-defined guards
+from typing import TypeGuard
+
+def is_int_list(value: list[int] | list[str]) -> TypeGuard[list[int]]:
+    return all(isinstance(x, int) for x in value)
+
+if is_int_list(items):
+    # items is list[int] here
+    ...
+```
+
+---
+
+## Decision Rules
+
+| Situation | Choice |
+|-----------|--------|
+| Simple function | Full annotations |
+| Internal helper | Light annotations or inference |
+| Public API | Full annotations + docstring |
+| Generic container | `Generic[T]` |
+| Interface | `Protocol` |
+| Dict with fixed keys | `TypedDict` |
+| Union of few types | `A | B` |
+| Many union types | `Union[A, B, C, ...]` |
+| Callable | `Callable[[Args], Return]` |
+| Constant | `Final` |
+| Limited string values | `Literal` |
+
+---
+
+## Useful vs Noise
+
+### Useful
+- Function signatures (public API)
+- Complex data structures
+- Generic classes
+- Protocol interfaces
+- Return types of non-trivial functions
+
+### Noise
+- Obvious local variables: `x: int = 5`
+- Loop variables: `for i: int in range(10):`
+- Trivial helpers with clear types
+- Over-annotating private implementation
+
+---
+
+## Project Compatibility
+
+Respect project's Python version and config:
+- Check `pyproject.toml` for `[tool.mypy]` or `[tool.pyright]`
+- Python 3.9+: built-in generics
+- Python 3.10+: `|` union, `TypeGuard`
+- Python 3.11+: `Self`, `NotRequired`, `TypedDict` improvements
+- Python 3.12+: `type` alias, `**kwargs` typing
+
+---
+
+## Preferred Patterns
+
+```python
+# Public API — full types
+def fetch_users(
+    client: APIClient,
+    filters: UserFilters | None = None,
+    limit: int = 100,
+) -> list[User]:
+    ...
+
+# Internal — inference OK
+def _parse_line(line: str) -> ParsedLine:
+    parts = line.split(",")
+    return ParsedLine(int(parts[0]), parts[1])
+
+# Generic utility
+def first_item[T](items: Sequence[T]) -> T | None:
+    return items[0] if items else None
+```
+
+---
+
+## Avoid
+
+- `Any` without justification (disable checking)
+- `object` as "I don't know" (use `Any` or proper type)
+- Complex nested types without aliases
+- Type hints that lie (incorrect types)
+- Ignoring type checker errors without `# type: ignore` comment with reason
+
+---
+
+## Validation Considerations
+
+- Run type checker (`mypy`, `pyright`) on project
+- `--strict` mode for new projects
+- `# type: ignore[code]` with specific error code
+- `typing.TYPE_CHECKING` for imports only needed for types
+
+---
+
+## Related Skills
+
+- `generation/protocols_generics.md`
+- `generation/workflow.md`
+- `quality/type_annotations.md`
+- `engineering/pyproject_toml.md` (tool config)

skills/generation/validation_pipeline.md

@@ -0,0 +1,274 @@
+# Generation: Validation Pipeline
+
+**Purpose**: Concrete validation process for generated code.
+
+**When to use**: After every code generation or modification.
+---
+---
+name: generation_validation_pipeline
+purpose: Concrete validation process for generated code
+category: generation
+triggers:
+  - validation
+  - pipeline
+  - verification
+  - testing
+  - linting
+  - type checking
+dependencies:
+  - generation/workflow.md
+  - generation/type_hints.md
+  - generation/error_handling.md
+  - testing/organization.md
+  - engineering/pyproject_toml.md
+  - security/dependency_risks.md
+priority: primary
+estimated_tokens: 2000
+---
+
+## Validation Steps (In Order)
+
+### 1. Syntax Check
+```bash
+python -m py_compile file.py
+# or
+python -m py_compile module/
+```
+- Catches syntax errors, indentation errors
+- Fast, runs on single file or directory
+
+### 2. Type Checking
+```bash
+# Detect tool from pyproject.toml
+mypy file.py
+# or
+pyright file.py
+# or
+pytype file.py
+```
+- Catches type mismatches, missing annotations
+- Use project's config (`[tool.mypy]`, `pyrightconfig.json`)
+- `--strict` for new code
+
+### 3. Linting
+```bash
+ruff check file.py
+# or
+flake8 file.py
+# or
+pylint file.py
+```
+- Catches style issues, potential bugs, complexity
+- Use project's config (`ruff.toml`, `.flake8`, `setup.cfg`)
+
+### 4. Formatting Check
+```bash
+ruff format --check file.py
+# or
+black --check file.py
+```
+- Ensures consistent formatting
+- Run formatter if check fails: `ruff format file.py`
+
+### 5. Tests
+```bash
+# Detect test framework
+pytest path/to/tests -v
+# or
+python -m pytest
+# or
+tox
+```
+- Run relevant tests (changed files + related)
+- Full suite for significant changes
+
+### 6. Relevant Execution
+```bash
+# Run the actual code if possible
+python -m module arg1 arg2
+# or
+python script.py
+```
+- Smoke test the functionality
+- Verify integration works
+
+### 7. Security Scan (Optional)
+```bash
+bandit -r file.py
+# or
+safety check
+```
+- Security linting
+- Dependency vulnerability check
+
+---
+
+## Project Tool Detection
+
+Check for config files in project root:
+```bash
+ls pyproject.toml setup.cfg tox.ini ruff.toml .pre-commit-config.yaml pyrightconfig.json
+```
+
+| File | Tools |
+|------|-------|
+| `pyproject.toml` | `[tool.mypy]`, `[tool.ruff]`, `[tool.black]`, `[tool.pytest]`, `[tool.bandit]` |
+| `ruff.toml` | Ruff config |
+| `pyrightconfig.json` | Pyright config |
+| `setup.cfg` | `[flake8]`, `[mypy]`, `[tool:pytest]` |
+| `tox.ini` | Test environments |
+| `.pre-commit-config.yaml` | Pre-commit hooks |
+
+---
+
+## Never Claim Without Evidence
+
+| Claim | Required Evidence |
+|-------|-------------------|
+| "tested" | Test output showing pass |
+| "verified" | Validation pipeline output |
+| "linted" | Linter output (clean) |
+| "type-safe" | Type checker output (clean) |
+| "production-ready" | All above + security scan |
+| "fixed" | Reproduction + fix + regression test |
+
+---
+
+## Validation Script Template
+
+```python
+#!/usr/bin/env python3
+"""Validation pipeline for generated code."""
+import subprocess
+import sys
+from pathlib import Path
+
+def run(cmd: list[str], cwd: Path | None = None) -> subprocess.CompletedProcess:
+    return subprocess.run(cmd, cwd=cwd, capture_output=True, text=True)
+
+def check_syntax(path: Path) -> bool:
+    result = run([sys.executable, "-m", "py_compile", str(path)])
+    if result.returncode != 0:
+        print(f"Syntax error: {result.stderr}")
+        return False
+    return True
+
+def check_types(path: Path, config: Path) -> bool:
+    # Detect mypy/pyright
+    if (config / "pyproject.toml").exists():
+        # Check for mypy config
+        result = run(["mypy", str(path)])
+        if result.returncode != 0:
+            print(f"Type errors: {result.stdout}")
+            return False
+    return True
+
+def check_lint(path: Path) -> bool:
+    result = run(["ruff", "check", str(path)])
+    if result.returncode != 0:
+        print(f"Lint errors: {result.stdout}")
+        return False
+    return True
+
+def check_format(path: Path) -> bool:
+    result = run(["ruff", "format", "--check", str(path)])
+    if result.returncode != 0:
+        print(f"Format issues: {result.stdout}")
+        return False
+    return True
+
+def run_tests(path: Path) -> bool:
+    result = run(["pytest", str(path), "-v"])
+    if result.returncode != 0:
+        print(f"Test failures: {result.stdout}")
+        return False
+    return True
+
+def main():
+    target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path(".")
+    all_pass = True
+    
+    all_pass &= check_syntax(target)
+    all_pass &= check_types(target, target.parent)
+    all_pass &= check_lint(target)
+    all_pass &= check_format(target)
+    all_pass &= run_tests(target)
+    
+    if all_pass:
+        print("✓ All validation checks passed")
+        sys.exit(0)
+    else:
+        print("✗ Validation failed")
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()
+```
+
+---
+
+## Integration with Workflow
+
+```
+IMPLEMENT
+    ↓
+REVIEW (manual)
+    ↓
+VALIDATE (automated — run pipeline)
+    ↓
+FIX (if any step fails)
+    ↓
+RE-VALIDATE
+    ↓
+FINALIZE
+```
+
+**Do not skip validation steps.** Each step catches different issues.
+
+---
+
+## Decision Rules
+
+| Situation | Validation Level |
+|-----------|------------------|
+| New module/file | Full pipeline (all 7 steps) |
+| Bug fix | Syntax + Type + Lint + Tests + Security |
+| Refactoring | Syntax + Type + Lint + Tests |
+| Documentation only | Syntax + Lint |
+| Config change | Syntax + Tests |
+
+---
+
+## Preferred Patterns
+
+```bash
+# Quick validation (syntax + lint + type)
+python -m py_compile file.py && ruff check file.py && mypy file.py
+
+# Full validation with tests
+pytest path/to/tests -v --tb=short && mypy path/ && ruff check path/
+
+# CI validation (all steps)
+python -m py_compile src/ && mypy src/ && ruff check src/ && ruff format --check src/ && pytest tests/ && bandit -r src/
+```
+
+---
+
+## Avoid
+
+- Skipping validation steps (each catches different issues)
+- Claiming "tested" without running tests
+- Running only syntax check
+- Not using project's configured tools
+- Ignoring validation failures
+
+---
+
+## Related Skills
+
+- `generation/workflow.md`
+- `generation/type_hints.md`
+- `generation/error_handling.md`
+- `testing/organization.md`
+- `engineering/pyproject_toml.md`
+- `security/dependency_risks.md`