python-skills 1.0.0__py3-none-any.whl

skills/generation/workflow.md

@@ -0,0 +1,190 @@
+# Generation: Workflow
+
+**Purpose**: Explicit code generation workflow for AI agents.
+
+**When to use**: Every code generation or modification task.
+---
+---
+name: generation_workflow
+purpose: Explicit code generation workflow for AI agents
+category: generation
+triggers:
+  - workflow
+  - implementation
+  - code generation
+  - modification
+  - validation
+  - review
+dependencies:
+  - core/* (all core language skills)
+  - generation/type_hints.md
+  - generation/error_handling.md
+  - generation/validation_pipeline.md
+  - engineering/pyproject_toml.md
+  - testing/organization.md
+  - security/*
+priority: primary
+estimated_tokens: 2000
+---
+
+## Workflow Steps
+
+### 1. UNDERSTAND
+- What is the user asking for?
+- What problem does this solve?
+- What are the constraints (performance, compatibility, security)?
+- What is the expected output (function, class, module, fix)?
+
+### 2. INSPECT (Existing Codebase)
+Before touching code, gather:
+- Python version (`pyproject.toml`, CI, Dockerfile, docs)
+- Project structure and package layout
+- `pyproject.toml` (dependencies, tooling, config)
+- Existing dependencies and versions
+- Existing abstractions, utilities, patterns
+- Existing test structure and conventions
+- Related modules and their interfaces
+- Configuration management approach
+- Error-handling conventions
+- Logging setup
+
+**Do not generate code before inspecting.**
+
+### 3. PLAN
+- What files need to change?
+- What new code is needed?
+- Which existing utilities can be reused?
+- What tests need updating?
+- What are the integration points?
+- What could break?
+
+### 4. SELECT RELEVANT SKILLS
+Load skills based on task type (see SKILL.md loading strategy):
+- Task-specific skills (HTTP, CLI, DB, etc.)
+- Always: `generation/error_handling`, `generation/type_hints`, `quality/naming`
+- Security: `security/input_validation`, `security/secrets`
+- Testing: `testing/organization`, `testing/fixtures_mocks`
+
+### 5. IMPLEMENT
+- Write code following project conventions
+- Use existing patterns and utilities
+- Add type hints appropriate to project config
+- Keep functions small and focused
+- Handle errors explicitly
+- No premature optimization
+
+### 6. REVIEW
+- Does it solve the stated problem?
+- Does it preserve existing behavior?
+- Are types correct?
+- Are errors handled?
+- Is it secure?
+- Is it readable?
+- Are names meaningful?
+
+### 7. VALIDATE
+Run project's validation pipeline (detect first):
+```bash
+# Syntax
+python -m py_compile file.py
+
+# Type checking (if configured)
+mypy file.py
+# or
+pyright file.py
+
+# Linting (if configured)
+ruff check file.py
+# or
+flake8 file.py
+
+# Formatting (if configured)
+ruff format file.py
+# or
+black file.py
+
+# Tests
+pytest path/to/tests -v
+# or project's test command
+```
+
+### 8. FIX
+- Address all validation failures
+- Re-run validation until clean
+- Do not skip steps
+
+### 9. FINALIZE
+- Confirm all tests pass
+- Confirm no regressions
+- Document any behavior changes
+- Update related documentation if needed
+
+---
+
+## Validation Pipeline (Project-Dependent)
+
+Detect project tooling first:
+```bash
+# Check for config files
+ls pyproject.toml setup.cfg tox.ini ruff.toml .pre-commit-config.yaml
+```
+
+| Tool | Command | Purpose |
+|------|---------|---------|
+| mypy | `mypy .` | Static type checking |
+| pyright | `pyright` | Fast type checking |
+| ruff | `ruff check .` | Linting (fast) |
+| black | `black --check .` | Formatting check |
+| pytest | `pytest` | Testing |
+| bandit | `bandit -r .` | Security linting |
+
+**Never claim** "tested", "verified", "linted", "type-safe" without running the tools.
+
+---
+
+## Existing Code Modification Rules
+
+When modifying existing code:
+
+1. **Understand first** — read related files, understand the flow
+2. **Minimal change** — smallest coherent change
+3. **Preserve behavior** — existing tests must pass
+4. **Follow conventions** — match existing style, patterns
+5. **Reuse** — use existing utilities, don't duplicate
+6. **Test** — run related tests before and after
+
+---
+
+## Integration Over Perfection
+
+**The agent should understand that integration with the existing codebase is more important than producing an isolated "perfect" implementation.**
+
+- Match the project's architecture
+- Use the project's utilities
+- Follow the project's error handling
+- Respect the project's type hint level
+- Keep the project's test patterns
+
+---
+
+## Decision Checklist (Before Generating)
+
+- [ ] Inspected project structure and conventions
+- [ ] Identified relevant existing code
+- [ ] Selected appropriate skills
+- [ ] Planned minimal coherent change
+- [ ] Know how to validate (test command, lint, type check)
+- [ ] Considered security implications
+- [ ] Considered Python version compatibility
+
+---
+
+## Related Skills
+
+- `core/*` (all core language skills)
+- `generation/type_hints.md`
+- `generation/error_handling.md`
+- `generation/validation_pipeline.md`
+- `engineering/pyproject_toml.md`
+- `testing/organization.md`
+- `security/*`

skills/oop.md

@@ -0,0 +1,228 @@
+# Core: Object-Oriented Programming
+
+**Purpose**: Python OOP patterns, inheritance, composition, and protocols.
+
+**When to use**: Designing classes, inheritance hierarchies, or interfaces.
+
+---
+
+## Core Rules
+
+### Class Definition
+```python
+class ClassName(BaseClass, AnotherBase):
+    """Class docstring."""
+    
+    class_attr: ClassVar[int] = 0  # Class variable (type hint)
+    
+    def __init__(self, param: type) -> None:
+        self.instance_attr: type = param
+    
+    def method(self) -> return_type:
+        return self.instance_attr
+    
+    @classmethod
+    def class_method(cls, arg: type) -> return_type:
+        ...
+    
+    @staticmethod
+    def static_method(arg: type) -> return_type:
+        ...
+    
+    @property
+    def computed(self) -> type:
+        return derive(self.instance_attr)
+```
+
+### Inheritance
+```python
+class Base:
+    def method(self) -> int:
+        return 1
+
+class Derived(Base):
+    def method(self) -> int:
+        return super().method() + 1  # Cooperative inheritance
+```
+
+- Use `super()` for cooperative multiple inheritance
+- Method Resolution Order (MRO): C3 linearization (`Class.__mro__`)
+- Prefer composition over inheritance for code reuse
+
+### Abstract Base Classes (ABC)
+```python
+from abc import ABC, abstractmethod
+
+class Interface(ABC):
+    @abstractmethod
+    def required(self) -> int:
+        ...
+    
+    @property
+    @abstractmethod
+    def value(self) -> str:
+        ...
+    
+    def concrete(self) -> str:
+        return f"value: {self.value}"
+```
+
+### Protocols (Structural Subtyping, Python 3.8+)
+```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()  # Accepts any object with draw()
+```
+- No explicit inheritance required
+- Preferred over ABC for duck-typing interfaces
+- `@runtime_checkable` for `isinstance` checks
+
+### Dataclasses (Python 3.7+)
+```python
+from dataclasses import dataclass, field
+from typing import Optional
+
+@dataclass(order=True, frozen=False)
+class Point:
+    x: float
+    y: float
+    label: str = ""              # Default
+    metadata: dict = field(default_factory=dict)  # Mutable default
+    _private: float = field(init=False, repr=False)  # Computed
+    
+    def __post_init__(self):
+        self._private = self.x * self.y
+```
+
+### Magic Methods (Key Ones)
+| Method | Purpose |
+|--------|---------|
+| `__init__` | Initialization |
+| `__new__` | Instance creation (rare) |
+| `__repr__` | Unambiguous representation (for debugging) |
+| `__str__` | Readable representation (for users) |
+| `__eq__`, `__hash__` | Equality and hashing (together!) |
+| `__lt__`, `__le__`, `__gt__`, `__ge__` | Ordering |
+| `__bool__` | Truth value |
+| `__len__` | Length |
+| `__getitem__`, `__setitem__`, `__delitem__` | Subscripting |
+| `__iter__` | Iteration |
+| `__contains__` | `in` operator |
+| `__enter__`, `__exit__` | Context manager |
+| `__call__` | Callable instances |
+| `__getattr__`, `__getattribute__` | Attribute access |
+| `__slots__` | Memory optimization, restrict attributes |
+
+### Slots
+```python
+class Slotted:
+    __slots__ = ('x', 'y')  # No __dict__, fixed attributes
+    
+    def __init__(self, x: float, y: float):
+        self.x = x
+        self.y = y
+```
+- Reduces memory, prevents arbitrary attributes
+- Incompatible with multiple inheritance (unless all parents use slots)
+
+---
+
+## Composition over Inheritance
+
+```python
+# Composition: has-a relationship
+class Engine:
+    def start(self) -> None: ...
+
+class Car:
+    def __init__(self, engine: Engine):
+        self.engine = engine  # Delegation
+    
+    def start(self) -> None:
+        self.engine.start()
+```
+
+- More flexible, testable, maintainable
+- Avoid deep inheritance hierarchies (>2 levels)
+
+---
+
+## Decision Rules
+
+| Situation | Pattern |
+|-----------|---------|
+| Fixed schema, data container | `@dataclass` |
+| Interface definition | `Protocol` (or `ABC` for runtime checks) |
+| Shared behavior, single hierarchy | Inheritance |
+| Reuse without hierarchy | Composition / Mixins |
+| Value object (immutable) | `@dataclass(frozen=True)` |
+| Need ordering | `@dataclass(order=True)` or `__lt__` |
+| Need hashing in sets/dicts | `__eq__` + `__hash__` (or `frozen=True`) |
+| Memory-critical many instances | `__slots__` |
+| Dynamic attributes | Regular class (no slots) |
+
+---
+
+## Preferred Patterns
+
+```python
+# Immutable data carrier
+@dataclass(frozen=True, slots=True)
+class Config:
+    host: str
+    port: int
+    timeout: float = 5.0
+
+# Protocol for dependency inversion
+class Repository(Protocol):
+    def get(self, id: str) -> User: ...
+    def save(self, user: User) -> None: ...
+
+# Mixin for reusable behavior
+class TimestampMixin:
+    created_at: datetime
+    updated_at: datetime
+    
+    def touch(self) -> None:
+        self.updated_at = datetime.now()
+```
+
+---
+
+## Avoid
+
+- Deep inheritance chains (>2 levels)
+- Multiple inheritance without clear design (diamond problem)
+- Mutable class attributes shared across instances
+- `__del__` (unreliable, use context managers)
+- Overriding `__init__` without calling `super().__init__()`
+- Using `type()` for type checks (use `isinstance`)
+- Properties with side effects
+- Getter/setter methods (use `@property`)
+
+---
+
+## Validation Considerations
+
+- `mypy` verifies protocol conformance
+- `@dataclass` generates `__init__`, `__repr__`, `__eq__`
+- `slots=True` (Python 3.10+) enables slots on dataclasses
+- `frozen=True` makes instances hashable (if all fields hashable)
+
+---
+
+## Related Skills
+
+- `generation/protocols_generics.md`
+- `generation/type_hints.md`
+- `core/advanced_python.md` (descriptors, metaclasses)
+- `quality/abstractions.md`
+- `anti_patterns/index.md` (excessive inheritance)

skills/quality/abstractions.md

@@ -0,0 +1,154 @@
+# Quality: Abstractions
+
+**Purpose**: When and how to create abstractions.
+
+**When to use**: Refactoring, designing new modules, avoiding duplication.
+
+---
+
+## Core Rules
+
+### Abstraction Principles
+
+1. **Wait for 3** — Don't abstract until 3+ concrete use cases
+2. **Prefer composition** — Over inheritance
+3. **Depend on abstractions** — Protocols/Interfaces, not concretions
+4. **Leaky abstractions** — Avoid (abstraction reveals implementation details)
+5. **Wrong abstraction** — Worse than duplication (prefer duplication over wrong abstraction)
+
+### When to Abstract
+```python
+# GOOD — 3+ similar patterns
+def process_user(user):
+    validate(user)
+    save(user)
+    notify(user)
+
+def process_order(order):
+    validate(order)
+    save(order)
+    notify(order)
+
+def process_payment(payment):
+    validate(payment)
+    save(payment)
+    notify(payment)
+
+# Abstract to:
+def process_entity(entity: Entity):
+    validate(entity)
+    save(entity)
+    notify(entity)
+```
+
+### When NOT to Abstract
+```python
+# BAD — premature, different semantics
+def process_user(user):
+    validate_email(user.email)
+    save_user(user)
+    send_welcome_email(user)
+
+def process_file(file):
+    validate_checksum(file.checksum)
+    save_file(file)
+    index_file(file)
+
+# These are DIFFERENT operations, not same pattern
+```
+
+### Interface Design
+```python
+# GOOD — Protocol (structural, flexible)
+class Repository(Protocol[T]):
+    def get(self, id: str) -> T | None: ...
+    def save(self, entity: T) -> T: ...
+
+# GOOD — ABC (when runtime check needed)
+class Cache(ABC):
+    @abstractmethod
+    def get(self, key: str) -> bytes | None: ...
+    @abstractmethod
+    def set(self, key: str, value: bytes, ttl: int) -> None: ...
+
+# BAD — Concrete base class forcing inheritance
+class BaseRepository:
+    def get(self, id: str) -> User:
+        return self.db.query(User).filter_by(id=id).first()
+```
+
+### Abstraction Levels
+```
+High-level policy (business rules)
+       ↓
+Application services (orchestration)
+       ↓
+Domain services (business logic)
+       ↓
+Infrastructure (DB, HTTP, FS)
+```
+
+- Each layer depends only on layer below
+- Domain has NO dependencies on infrastructure
+
+---
+
+## Decision Rules
+
+| Situation | Action |
+|-----------|--------|
+| 3+ similar implementations | Abstract |
+| 1-2 implementations | Keep concrete |
+| Different semantics | Don't abstract |
+| Need runtime swap | Protocol/ABC |
+| Compile-time only | Protocol |
+| Cross-cutting (logging, timing) | Decorator/middleware |
+
+---
+
+## Preferred Patterns
+
+```python
+# Strategy pattern via Protocol
+class Exporter(Protocol):
+    def export(self, data: Data) -> bytes: ...
+
+class JSONExporter:
+    def export(self, data: Data) -> bytes:
+        return json.dumps(data).encode()
+
+class CSVExporter:
+    def export(self, data: Data) -> bytes:
+        return csv_encode(data)
+
+def export_data(data: Data, exporter: Exporter) -> bytes:
+    return exporter.export(data)
+```
+
+---
+
+## Avoid
+
+- Abstract base classes with concrete methods (use composition)
+- Deep inheritance hierarchies (>2 levels)
+- "Manager", "Handler", "Utils", "Helper" classes
+- Abstracting control flow (use functions)
+- Frameworks (inverting control) vs libraries (you call them)
+
+---
+
+## Validation Considerations
+
+- Can implementations be swapped without changing consumers?
+- Are protocols minimal (only what's needed)?
+- Does abstraction leak implementation details?
+- Is there a test for each implementation?
+
+---
+
+## Related Skills
+
+- `quality/maintainability.md`
+- `quality/duplication.md`
+- `generation/protocols_generics.md`
+- `core/oop.md`