python-skills 1.0.0__py3-none-any.whl

skills/engineering/database.md

@@ -0,0 +1,240 @@
+---
+name: engineering_database
+purpose: Database access patterns and best practices
+category: engineering
+triggers:
+  - database
+  - sql
+  - query
+  - orm
+  - sqlite
+  - postgresql
+  - mysql
+  - migration
+dependencies:
+  - security/sql_injection.md
+  - engineering/configuration.md
+  - generation/async_concurrency.md
+  - generation/error_handling.md
+  - testing/organization.md
+priority: primary
+estimated_tokens: 2200
+---
+# Engineering: Database
+
+**Purpose**: Database access patterns and best practices.
+
+**When to use**: Any code interacting with databases.
+
+---
+
+## Core Rules
+
+### Driver Selection
+| Database | Async Driver | Sync Driver |
+|----------|--------------|-------------|
+| PostgreSQL | `asyncpg` | `psycopg` (v3) |
+| MySQL | `aiomysql` | `pymysql` |
+| SQLite | `aiosqlite` | `sqlite3` (stdlib) |
+| MongoDB | `motor` | `pymongo` |
+
+### Connection Management
+```python
+# Async (asyncpg example)
+import asyncpg
+
+pool: asyncpg.Pool = await asyncpg.create_pool(
+    dsn="postgresql://user:pass@host/db",
+    min_size=5,
+    max_size=20,
+    command_timeout=30,
+)
+
+async def get_user(user_id: int) -> User | None:
+    async with pool.acquire() as conn:
+        row = await conn.fetchrow("SELECT * FROM users WHERE id = $1", user_id)
+        return User(**row) if row else None
+
+# Sync (psycopg)
+import psycopg
+from psycopg_pool import ConnectionPool
+
+pool = ConnectionPool("postgresql://user:pass@host/db", min_size=5, max_size=20)
+
+def get_user(user_id: int) -> User | None:
+    with pool.connection() as conn:
+        with conn.cursor() as cur:
+            cur.execute("SELECT * FROM users WHERE id = %s", (user_id,))
+            row = cur.fetchone()
+            return User(*row) if row else None
+```
+
+### Parameterized Queries (SQL Injection Prevention)
+```python
+# CORRECT — parameterized
+cursor.execute("SELECT * FROM users WHERE email = %s", (email,))
+cursor.execute("SELECT * FROM users WHERE id = $1", (user_id,))  # asyncpg
+
+# WRONG — string interpolation
+cursor.execute(f"SELECT * FROM users WHERE email = '{email}'")  # INJECTION!
+cursor.execute("SELECT * FROM users WHERE id = " + str(user_id))  # INJECTION!
+```
+
+### ORM (SQLAlchemy 2.0+)
+```python
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+class Base(DeclarativeBase):
+    pass
+
+class User(Base):
+    __tablename__ = "users"
+    id: Mapped[int] = mapped_column(primary_key=True)
+    email: Mapped[str] = mapped_column(unique=True)
+    name: Mapped[str]
+
+engine = create_async_engine("postgresql+asyncpg://user:pass@host/db")
+async_session = async_sessionmaker(engine, expire_on_commit=False)
+
+async def get_user(session: AsyncSession, user_id: int) -> User | None:
+    return await session.get(User, user_id)
+
+async def create_user(session: AsyncSession, email: str, name: str) -> User:
+    user = User(email=email, name=name)
+    session.add(user)
+    await session.commit()
+    return user
+```
+
+### Migrations (Alembic)
+```bash
+# Initialize
+alembic init alembic
+
+# Create migration
+alembic revision --autogenerate -m "Add users table"
+
+# Apply
+alembic upgrade head
+```
+
+### Repository Pattern
+```python
+from abc import ABC, abstractmethod
+from typing import Protocol
+
+class UserRepository(Protocol):
+    async def get(self, user_id: int) -> User | None: ...
+    async def get_by_email(self, email: str) -> User | None: ...
+    async def save(self, user: User) -> User: ...
+    async def delete(self, user_id: int) -> bool: ...
+
+class PostgresUserRepository:
+    def __init__(self, pool: asyncpg.Pool):
+        self.pool = pool
+    
+    async def get(self, user_id: int) -> User | None:
+        async with self.pool.acquire() as conn:
+            row = await conn.fetchrow("SELECT * FROM users WHERE id = $1", user_id)
+            return User(**row) if row else None
+    
+    # ... implement other methods
+
+# Usage (dependency injection)
+async def handler(repo: UserRepository, user_id: int):
+    user = await repo.get(user_id)
+```
+
+### Transactions
+```python
+# Async
+async with pool.acquire() as conn:
+    async with conn.transaction():
+        await conn.execute("INSERT ...")
+        await conn.execute("UPDATE ...")
+
+# SQLAlchemy
+async with async_session() as session:
+    async with session.begin():
+        session.add(user1)
+        session.add(user2)
+```
+
+---
+
+## Decision Rules
+
+| Need | Approach |
+|------|----------|
+| Simple queries, performance critical | Raw driver (`asyncpg`, `psycopg`) |
+| Complex domain model, migrations | SQLAlchemy + Alembic |
+| Document data | MongoDB (`motor`/`pymongo`) |
+| Embedded/local | SQLite (`aiosqlite`/`sqlite3`) |
+| Testing | In-memory SQLite or testcontainers |
+
+---
+
+## Preferred Patterns
+
+```python
+# Dependency injection for testability
+class Database:
+    def __init__(self, pool: asyncpg.Pool):
+        self.pool = pool
+        self.users = PostgresUserRepository(pool)
+        self.orders = PostgresOrderRepository(pool)
+
+# Context manager for transactions
+@asynccontextmanager
+async def transaction(db: Database):
+    async with db.pool.acquire() as conn:
+        async with conn.transaction():
+            yield conn
+
+# Type-safe queries with dataclasses
+from dataclasses import dataclass
+
+@dataclass
+class UserRow:
+    id: int
+    email: str
+    name: str
+
+async def get_user(conn, user_id: int) -> UserRow | None:
+    row = await conn.fetchrow("SELECT id, email, name FROM users WHERE id = $1", user_id)
+    return UserRow(**row) if row else None
+```
+
+---
+
+## Avoid
+
+- String interpolation in SQL (injection!)
+- Global connection/pool (use DI)
+- Long-running transactions
+- N+1 queries (use joins or batch loading)
+- ORM for everything (raw SQL for complex queries)
+- No connection pooling
+- Committing in loops
+
+---
+
+## Validation Considerations
+
+- Test with real database (testcontainers)
+- Verify parameterized queries used everywhere
+- Check connection pool sizing
+- Test migration up/down
+- Load test connection limits
+
+---
+
+## Related Skills
+
+- `security/sql_injection.md`
+- `engineering/configuration.md`
+- `generation/async_concurrency.md`
+- `generation/error_handling.md`
+- `testing/organization.md`

skills/engineering/dependency_management.md

@@ -0,0 +1,205 @@
+# Engineering: Dependency Management
+
+**Purpose**: Rules for adding, updating, and managing dependencies.
+
+**When to use**: Any time a new import or requirement is considered.
+
+---
+
+## Core Rules
+
+### Dependency Decision Tree
+```
+Can stdlib solve this?
+    ↓ YES → Use stdlib
+    ↓ NO
+Is an existing project dependency suitable?
+    ↓ YES → Use existing
+    ↓ NO
+Is a new dependency justified?
+    ↓ YES → Add with justification
+    ↓ NO → Reconsider approach
+```
+
+### Justification Criteria for New Dependencies
+1. **Functionality gap** — stdlib + existing deps cannot reasonably solve
+2. **Maintenance** — Actively maintained (recent releases, responsive issues)
+3. **Security** — No known unpatched vulnerabilities
+4. **Compatibility** — Supports project's Python version range
+5. **License** — Compatible with project license
+6. **Size** — Reasonable install size, minimal transitive deps
+7. **Alternatives evaluated** — Considered lighter alternatives
+
+### Version Constraints
+```toml
+# Libraries: compatible ranges
+dependencies = [
+    "requests>=2.31,<3",      # Semver major
+    "pydantic>=2.0,<3",
+    "click>=8.0,<9",
+]
+
+# Applications: lock files
+# requirements.txt / uv.lock / poetry.lock / pdm.lock
+```
+
+### Dependency Categories
+| Category | Purpose | Version Policy |
+|----------|---------|----------------|
+| Runtime | Required for library/app to work | Compatible range |
+| Optional | Extra features | Compatible range |
+| Dev | Testing, linting, docs | Pinned or loose |
+| Build | Build backend, generators | Pinned |
+
+---
+
+## Lock Files (Applications)
+
+### For Applications (Not Libraries)
+```bash
+# uv (fast, modern)
+uv pip compile pyproject.toml -o requirements.txt
+uv sync
+
+# pip-tools
+pip-compile pyproject.toml -o requirements.txt
+pip-sync requirements.txt
+
+# poetry
+poetry lock
+poetry install
+
+# pdm
+pdm lock
+pdm install
+```
+
+### Lock File Policy
+- **Libraries**: No lock file in repo (only `pyproject.toml`)
+- **Applications**: Lock file committed (`requirements.txt`, `uv.lock`, `poetry.lock`)
+- **CI**: Use lock file for reproducible builds
+
+---
+
+## Dependency Security
+
+### Scanning
+```bash
+# Safety (checks known vulnerabilities)
+safety check
+
+# pip-audit
+pip-audit
+
+# GitHub Dependabot / GitLab Dependency Scanning
+# Configured in CI
+```
+
+### Update Policy
+```bash
+# Check outdated
+uv pip list --outdated
+pip list --outdated
+
+# Update (test first!)
+uv pip install --upgrade package
+# Run full test suite
+```
+
+---
+
+## Vendoring (Last Resort)
+```python
+# Only when:
+# - Dependency abandoned
+# - Need modification
+# - Cannot depend on external (air-gapped)
+
+# Structure
+src/
+└── mypackage/
+    ├── _vendor/
+    │   └── requests/       # Copied source
+    │       └── __init__.py # from _vendor.requests import ...
+    └── ...
+```
+
+---
+
+## Decision Rules
+
+| Situation | Action |
+|-----------|--------|
+| Stdlib has it | Use stdlib |
+| Existing dep has it | Use existing |
+| Simple utility (few lines) | Copy code (with license) |
+| Complex, well-maintained lib | Add dependency |
+| Abandoned dependency | Fork/vendor or replace |
+| Security vulnerability | Upgrade immediately |
+| License conflict | Find alternative |
+
+---
+
+## Preferred Patterns
+
+```toml
+# pyproject.toml - clear separation
+[project]
+dependencies = [
+    # Core runtime deps
+    "httpx>=0.25,<1",
+    "pydantic>=2.0,<3",
+    "python-dotenv>=1.0,<2",
+]
+
+[project.optional-dependencies]
+# Optional features
+async = ["aiohttp>=3.8,<4"]
+redis = ["redis>=5.0,<6"]
+postgres = ["asyncpg>=0.29,<1", "sqlalchemy>=2.0,<3"]
+
+# Dev tools (not installed by users)
+dev = [
+    "pytest>=7.4,<8",
+    "pytest-asyncio>=0.21,<1",
+    "pytest-cov>=4.1,<5",
+    "ruff>=0.5,<1",
+    "mypy>=1.10,<2",
+    "pre-commit>=3.0,<4",
+]
+
+# Build deps (in build-system)
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+```
+
+---
+
+## Avoid
+
+- Adding deps for trivial functionality (`left-pad` style)
+- Pinning exact versions in library `pyproject.toml` (`==1.2.3`)
+- No upper bounds in library deps (breaking changes)
+- Commiting `requirements.txt` for libraries
+- Ignoring security advisories
+- Transitive dependency hell (audit `pipdeptree`)
+
+---
+
+## Validation Considerations
+
+- `pipdeptree` shows dependency graph
+- `pip check` validates consistency
+- `safety check` / `pip-audit` clean
+- License check: `pip-licenses`
+- Build reproducibility: `pip install` from lock file
+
+---
+
+## Related Skills
+
+- `engineering/pyproject_toml.md`
+- `engineering/packaging.md`
+- `engineering/virtual_environments.md`
+- `security/dependency_risks.md`

skills/engineering/http_clients.md

@@ -0,0 +1,267 @@
+---
+name: engineering_http_clients
+purpose: HTTP client selection and usage patterns
+category: engineering
+triggers:
+  - http
+  - request
+  - client
+  - api
+  - rest
+  - webhook
+  - download
+dependencies:
+  - generation/async_concurrency.md
+  - generation/error_handling.md
+  - engineering/configuration.md
+  - security/secrets.md
+  - testing/organization.md
+priority: primary
+estimated_tokens: 2500
+---
+# Engineering: HTTP Clients
+
+**Purpose**: HTTP client selection and usage patterns.
+
+**When to use**: Making HTTP requests (APIs, webhooks, downloads).
+
+---
+
+## Core Rules
+
+### Client Selection
+
+| Need | Client |
+|------|--------|
+| Sync, simple | `requests` |
+| Sync + HTTP/2 | `httpx` (sync) |
+| Async | `httpx` / `aiohttp` |
+| Stdlib only | `urllib.request` (avoid) |
+| Testing | `respx` / `pytest-httpx` / `requests-mock` |
+
+### httpx (Recommended — Sync + Async)
+```python
+import httpx
+
+# Sync
+client = httpx.Client(timeout=30.0, limits=httpx.Limits(max_connections=100))
+response = client.get("https://api.example.com/users")
+client.close()
+
+# Context manager
+with httpx.Client() as client:
+    response = client.get(url)
+
+# Async
+async with httpx.AsyncClient() as client:
+    response = await client.get(url)
+
+# Common options
+client = httpx.Client(
+    base_url="https://api.example.com",
+    headers={"User-Agent": "MyApp/1.0"},
+    timeout=httpx.Timeout(connect=5.0, read=30.0),
+    follow_redirects=True,
+    limits=httpx.Limits(max_keepalive_connections=20),
+)
+```
+
+### Response Handling
+```python
+response = client.get(url)
+
+# Status
+response.status_code
+response.is_success
+response.raise_for_status()  # Raises HTTPStatusError
+
+# Content
+response.text          # str (decoded)
+response.content       # bytes
+response.json()        # Parsed JSON
+response.iter_bytes()  # Stream
+
+# Headers
+response.headers["Content-Type"]
+response.headers.get("X-Custom")
+```
+
+### Error Handling
+```python
+import httpx
+
+try:
+    response = client.get(url, timeout=10.0)
+    response.raise_for_status()
+except httpx.TimeoutException:
+    logger.warning("Request timed out")
+    raise ServiceTimeout()
+except httpx.ConnectError:
+    logger.warning("Connection failed")
+    raise ServiceUnavailable()
+except httpx.HTTPStatusError as e:
+    if e.response.status_code == 404:
+        raise NotFoundError()
+    elif e.response.status_code == 429:
+        raise RateLimited(retry_after=e.response.headers.get("Retry-After"))
+    else:
+        logger.error("HTTP error", status=e.response.status_code)
+        raise ServiceError()
+```
+
+### Retry Logic
+```python
+from httpx import Retry
+from httpx._transports.default import RetryStrategy
+
+# Built-in retry (httpx 0.25+)
+transport = httpx.HTTPTransport(
+    retries=Retry(
+        total=3,
+        backoff_factor=0.5,
+        status_forcelist=[429, 500, 502, 503, 504],
+        allowed_methods=["HEAD", "GET", "OPTIONS"],
+    )
+)
+client = httpx.Client(transport=transport)
+
+# Or use tenacity for complex retry
+from tenacity import retry, stop_after_attempt, wait_exponential
+
+@retry(
+    wait=wait_exponential(multiplier=1, min=1, max=10),
+    stop=stop_after_attempt(3),
+    retry=retry_if_exception_type(httpx.RequestError),
+)
+async def fetch_with_retry(client: httpx.AsyncClient, url: str) -> httpx.Response:
+    return await client.get(url)
+```
+
+### Authentication
+```python
+# Bearer token
+headers = {"Authorization": f"Bearer {token}"}
+
+# Basic auth
+auth = httpx.BasicAuth("user", "pass")
+
+# Custom auth
+class APIKeyAuth(httpx.Auth):
+    def __init__(self, api_key: str):
+        self.api_key = api_key
+    
+    def auth_flow(self, request):
+        request.headers["X-API-Key"] = self.api_key
+        yield request
+
+client = httpx.Client(auth=APIKeyAuth("key"))
+```
+
+### Streaming Large Responses
+```python
+# Download large file
+with client.stream("GET", url) as response:
+    response.raise_for_status()
+    with Path("large_file").open("wb") as f:
+        for chunk in response.iter_bytes(chunk_size=8192):
+            f.write(chunk)
+
+# Async streaming
+async with client.stream("GET", url) as response:
+    async for chunk in response.aiter_bytes():
+        process(chunk)
+```
+
+### Testing
+```python
+import pytest
+import respx
+import httpx
+
+@respx.mock
+async def test_api():
+    respx.get("https://api.example.com/users").mock(
+        return_value=httpx.Response(200, json=[{"id": 1}])
+    )
+    
+    async with httpx.AsyncClient() as client:
+        resp = await client.get("https://api.example.com/users")
+        assert resp.json() == [{"id": 1}]
+```
+
+---
+
+## Decision Rules
+
+| Situation | Pattern |
+|-----------|---------|
+| Simple sync requests | `httpx.Client()` |
+| High concurrency sync | `httpx.Client` with limits |
+| Async application | `httpx.AsyncClient` |
+| Complex retry/backoff | `tenacity` + `httpx` |
+| WebSocket | `httpx` (experimental) or `websockets` |
+| Testing | `respx` (async) or `requests-mock` (sync) |
+
+---
+
+## Preferred Patterns
+
+```python
+# Reusable client factory
+def create_client(
+    base_url: str,
+    timeout: float = 30.0,
+    api_key: str | None = None,
+) -> httpx.Client:
+    headers = {"User-Agent": "MyApp/1.0"}
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+    
+    return httpx.Client(
+        base_url=base_url,
+        headers=headers,
+        timeout=httpx.Timeout(timeout),
+        limits=httpx.Limits(max_connections=50),
+    )
+
+# Service wrapper
+class APIService:
+    def __init__(self, client: httpx.Client):
+        self.client = client
+    
+    def get_user(self, user_id: str) -> User:
+        resp = self.client.get(f"/users/{user_id}")
+        resp.raise_for_status()
+        return User.model_validate(resp.json())
+```
+
+---
+
+## Avoid
+
+- Creating new client per request (no connection pooling)
+- No timeout (hangs forever)
+- Ignoring `raise_for_status()`
+- Blocking sync client in async code
+- Logging full response bodies (may contain secrets)
+- Hardcoding URLs (use config + base_url)
+
+---
+
+## Validation Considerations
+
+- Test timeout behavior
+- Test retry logic
+- Test auth handling
+- Mock external APIs in tests
+- Check connection pooling works
+
+---
+
+## Related Skills
+
+- `generation/async_concurrency.md`
+- `generation/error_handling.md`
+- `engineering/configuration.md`
+- `security/secrets.md`
+- `testing/organization.md`