@sylix/coworker 2.0.11 → 2.0.12

package/dist/skills/defaults/backend-development/python-code-style.md

@@ -0,0 +1,360 @@
+---
+name: python-code-style
+description: Python code style, linting, formatting, naming conventions, and documentation standards. Use when writing new code, reviewing style, configuring linters, writing docstrings, or establishing project standards.
+---
+
+# Python Code Style & Documentation
+
+Consistent code style and clear documentation make codebases maintainable and collaborative. This skill covers modern Python tooling, naming conventions, and documentation standards.
+
+## When to Use This Skill
+
+- Setting up linting and formatting for a new project
+- Writing or reviewing docstrings
+- Establishing team coding standards
+- Configuring ruff, mypy, or pyright
+- Reviewing code for style consistency
+- Creating project documentation
+
+## Core Concepts
+
+### 1. Automated Formatting
+
+Let tools handle formatting debates. Configure once, enforce automatically.
+
+### 2. Consistent Naming
+
+Follow PEP 8 conventions with meaningful, descriptive names.
+
+### 3. Documentation as Code
+
+Docstrings should be maintained alongside the code they describe.
+
+### 4. Type Annotations
+
+Modern Python code should include type hints for all public APIs.
+
+## Quick Start
+
+```bash
+# Install modern tooling
+pip install ruff mypy
+
+# Configure in pyproject.toml
+[tool.ruff]
+line-length = 120
+target-version = "py312"  # Adjust based on your project's minimum Python version
+
+[tool.mypy]
+strict = true
+```
+
+## Fundamental Patterns
+
+### Pattern 1: Modern Python Tooling
+
+Use `ruff` as an all-in-one linter and formatter. It replaces flake8, isort, and black with a single fast tool.
+
+```toml
+# pyproject.toml
+[tool.ruff]
+line-length = 120
+target-version = "py312"  # Adjust based on your project's minimum Python version
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle errors
+    "W",    # pycodestyle warnings
+    "F",    # pyflakes
+    "I",    # isort
+    "B",    # flake8-bugbear
+    "C4",   # flake8-comprehensions
+    "UP",   # pyupgrade
+    "SIM",  # flake8-simplify
+]
+ignore = ["E501"]  # Line length handled by formatter
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+```
+
+Run with:
+
+```bash
+ruff check --fix .  # Lint and auto-fix
+ruff format .       # Format code
+```
+
+### Pattern 2: Type Checking Configuration
+
+Configure strict type checking for production code.
+
+```toml
+# pyproject.toml
+[tool.mypy]
+python_version = "3.12"
+strict = true
+warn_return_any = true
+warn_unused_ignores = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+```
+
+Alternative: Use `pyright` for faster checking.
+
+```toml
+[tool.pyright]
+pythonVersion = "3.12"
+typeCheckingMode = "strict"
+```
+
+### Pattern 3: Naming Conventions
+
+Follow PEP 8 with emphasis on clarity over brevity.
+
+**Files and Modules:**
+
+```python
+# Good: Descriptive snake_case
+user_repository.py
+order_processing.py
+http_client.py
+
+# Avoid: Abbreviations
+usr_repo.py
+ord_proc.py
+http_cli.py
+```
+
+**Classes and Functions:**
+
+```python
+# Classes: PascalCase
+class UserRepository:
+    pass
+
+class HTTPClientFactory:  # Acronyms stay uppercase
+    pass
+
+# Functions and variables: snake_case
+def get_user_by_email(email: str) -> User | None:
+    retry_count = 3
+    max_connections = 100
+```
+
+**Constants:**
+
+```python
+# Module-level constants: SCREAMING_SNAKE_CASE
+MAX_RETRY_ATTEMPTS = 3
+DEFAULT_TIMEOUT_SECONDS = 30
+API_BASE_URL = "https://api.example.com"
+```
+
+### Pattern 4: Import Organization
+
+Group imports in a consistent order: standard library, third-party, local.
+
+```python
+# Standard library
+import os
+from collections.abc import Callable
+from typing import Any
+
+# Third-party packages
+import httpx
+from pydantic import BaseModel
+from sqlalchemy import Column
+
+# Local imports
+from myproject.models import User
+from myproject.services import UserService
+```
+
+Use absolute imports exclusively:
+
+```python
+# Preferred
+from myproject.utils import retry_decorator
+
+# Avoid relative imports
+from ..utils import retry_decorator
+```
+
+## Advanced Patterns
+
+### Pattern 5: Google-Style Docstrings
+
+Write docstrings for all public classes, methods, and functions.
+
+**Simple Function:**
+
+```python
+def get_user(user_id: str) -> User:
+    """Retrieve a user by their unique identifier."""
+    ...
+```
+
+**Complex Function:**
+
+```python
+def process_batch(
+    items: list[Item],
+    max_workers: int = 4,
+    on_progress: Callable[[int, int], None] | None = None,
+) -> BatchResult:
+    """Process items concurrently using a worker pool.
+
+    Processes each item in the batch using the configured number of
+    workers. Progress can be monitored via the optional callback.
+
+    Args:
+        items: The items to process. Must not be empty.
+        max_workers: Maximum concurrent workers. Defaults to 4.
+        on_progress: Optional callback receiving (completed, total) counts.
+
+    Returns:
+        BatchResult containing succeeded items and any failures with
+        their associated exceptions.
+
+    Raises:
+        ValueError: If items is empty.
+        ProcessingError: If the batch cannot be processed.
+
+    Example:
+        >>> result = process_batch(items, max_workers=8)
+        >>> print(f"Processed {len(result.succeeded)} items")
+    """
+    ...
+```
+
+**Class Docstring:**
+
+```python
+class UserService:
+    """Service for managing user operations.
+
+    Provides methods for creating, retrieving, updating, and
+    deleting users with proper validation and error handling.
+
+    Attributes:
+        repository: The data access layer for user persistence.
+        logger: Logger instance for operation tracking.
+
+    Example:
+        >>> service = UserService(repository, logger)
+        >>> user = service.create_user(CreateUserInput(...))
+    """
+
+    def __init__(self, repository: UserRepository, logger: Logger) -> None:
+        """Initialize the user service.
+
+        Args:
+            repository: Data access layer for users.
+            logger: Logger for tracking operations.
+        """
+        self.repository = repository
+        self.logger = logger
+```
+
+### Pattern 6: Line Length and Formatting
+
+Set line length to 120 characters for modern displays while maintaining readability.
+
+```python
+# Good: Readable line breaks
+def create_user(
+    email: str,
+    name: str,
+    role: UserRole = UserRole.MEMBER,
+    notify: bool = True,
+) -> User:
+    ...
+
+# Good: Chain method calls clearly
+result = (
+    db.query(User)
+    .filter(User.active == True)
+    .order_by(User.created_at.desc())
+    .limit(10)
+    .all()
+)
+
+# Good: Format long strings
+error_message = (
+    f"Failed to process user {user_id}: "
+    f"received status {response.status_code} "
+    f"with body {response.text[:100]}"
+)
+```
+
+### Pattern 7: Project Documentation
+
+**README Structure:**
+
+```markdown
+# Project Name
+
+Brief description of what the project does.
+
+## Installation
+
+\`\`\`bash
+pip install myproject
+\`\`\`
+
+## Quick Start
+
+\`\`\`python
+from myproject import Client
+
+client = Client(api_key="...")
+result = client.process(data)
+\`\`\`
+
+## Configuration
+
+Document environment variables and configuration options.
+
+## Development
+
+\`\`\`bash
+pip install -e ".[dev]"
+pytest
+\`\`\`
+```
+
+**CHANGELOG Format (Keep a Changelog):**
+
+```markdown
+# Changelog
+
+## [Unreleased]
+
+### Added
+- New feature X
+
+### Changed
+- Modified behavior of Y
+
+### Fixed
+- Bug in Z
+```
+
+## Best Practices Summary
+
+1. **Use ruff** - Single tool for linting and formatting
+2. **Enable strict mypy** - Catch type errors before runtime
+3. **120 character lines** - Modern standard for readability
+4. **Descriptive names** - Clarity over brevity
+5. **Absolute imports** - More maintainable than relative
+6. **Google-style docstrings** - Consistent, readable documentation
+7. **Document public APIs** - Every public function needs a docstring
+8. **Keep docs updated** - Treat documentation as code
+9. **Automate in CI** - Run linters on every commit
+10. **Target Python 3.10+** - For new projects, Python 3.12+ is recommended for modern language features

package/dist/skills/defaults/backend-development/python-configuration.md

@@ -0,0 +1,368 @@
+---
+name: python-configuration
+description: Python configuration management via environment variables and typed settings. Use when externalizing config, setting up pydantic-settings, managing secrets, or implementing environment-specific behavior.
+---
+
+# Python Configuration Management
+
+Externalize configuration from code using environment variables and typed settings. Well-managed configuration enables the same code to run in any environment without modification.
+
+## When to Use This Skill
+
+- Setting up a new project's configuration system
+- Migrating from hardcoded values to environment variables
+- Implementing pydantic-settings for typed configuration
+- Managing secrets and sensitive values
+- Creating environment-specific settings (dev/staging/prod)
+- Validating configuration at application startup
+
+## Core Concepts
+
+### 1. Externalized Configuration
+
+All environment-specific values (URLs, secrets, feature flags) come from environment variables, not code.
+
+### 2. Typed Settings
+
+Parse and validate configuration into typed objects at startup, not scattered throughout code.
+
+### 3. Fail Fast
+
+Validate all required configuration at application boot. Missing config should crash immediately with a clear message.
+
+### 4. Sensible Defaults
+
+Provide reasonable defaults for local development while requiring explicit values for sensitive settings.
+
+## Quick Start
+
+```python
+from pydantic_settings import BaseSettings
+from pydantic import Field
+
+class Settings(BaseSettings):
+    database_url: str = Field(alias="DATABASE_URL")
+    api_key: str = Field(alias="API_KEY")
+    debug: bool = Field(default=False, alias="DEBUG")
+
+settings = Settings()  # Loads from environment
+```
+
+## Fundamental Patterns
+
+### Pattern 1: Typed Settings with Pydantic
+
+Create a central settings class that loads and validates all configuration.
+
+```python
+from pydantic_settings import BaseSettings
+from pydantic import Field, PostgresDsn, ValidationError
+import sys
+
+class Settings(BaseSettings):
+    """Application configuration loaded from environment variables."""
+
+    # Database
+    db_host: str = Field(alias="DB_HOST")
+    db_port: int = Field(default=5432, alias="DB_PORT")
+    db_name: str = Field(alias="DB_NAME")
+    db_user: str = Field(alias="DB_USER")
+    db_password: str = Field(alias="DB_PASSWORD")
+
+    # Redis
+    redis_url: str = Field(default="redis://localhost:6379", alias="REDIS_URL")
+
+    # API Keys
+    api_secret_key: str = Field(alias="API_SECRET_KEY")
+
+    # Feature flags
+    enable_new_feature: bool = Field(default=False, alias="ENABLE_NEW_FEATURE")
+
+    model_config = {
+        "env_file": ".env",
+        "env_file_encoding": "utf-8",
+    }
+
+# Create singleton instance at module load
+try:
+    settings = Settings()
+except ValidationError as e:
+    print(f"Configuration error:\n{e}")
+    sys.exit(1)
+```
+
+Import `settings` throughout your application:
+
+```python
+from myapp.config import settings
+
+def get_database_connection():
+    return connect(
+        host=settings.db_host,
+        port=settings.db_port,
+        database=settings.db_name,
+    )
+```
+
+### Pattern 2: Fail Fast on Missing Configuration
+
+Required settings should crash the application immediately with a clear error.
+
+```python
+from pydantic_settings import BaseSettings
+from pydantic import Field, ValidationError
+import sys
+
+class Settings(BaseSettings):
+    # Required - no default means it must be set
+    api_key: str = Field(alias="API_KEY")
+    database_url: str = Field(alias="DATABASE_URL")
+
+    # Optional with defaults
+    log_level: str = Field(default="INFO", alias="LOG_LEVEL")
+
+try:
+    settings = Settings()
+except ValidationError as e:
+    print("=" * 60)
+    print("CONFIGURATION ERROR")
+    print("=" * 60)
+    for error in e.errors():
+        field = error["loc"][0]
+        print(f"  - {field}: {error['msg']}")
+    print("\nPlease set the required environment variables.")
+    sys.exit(1)
+```
+
+A clear error at startup is better than a cryptic `None` failure mid-request.
+
+### Pattern 3: Local Development Defaults
+
+Provide sensible defaults for local development while requiring explicit values for secrets.
+
+```python
+class Settings(BaseSettings):
+    # Has local default, but prod will override
+    db_host: str = Field(default="localhost", alias="DB_HOST")
+    db_port: int = Field(default=5432, alias="DB_PORT")
+
+    # Always required - no default for secrets
+    db_password: str = Field(alias="DB_PASSWORD")
+    api_secret_key: str = Field(alias="API_SECRET_KEY")
+
+    # Development convenience
+    debug: bool = Field(default=False, alias="DEBUG")
+
+    model_config = {"env_file": ".env"}
+```
+
+Create a `.env` file for local development (never commit this):
+
+```bash
+# .env (add to .gitignore)
+DB_PASSWORD=local_dev_password
+API_SECRET_KEY=dev-secret-key
+DEBUG=true
+```
+
+### Pattern 4: Namespaced Environment Variables
+
+Prefix related variables for clarity and easy debugging.
+
+```bash
+# Database configuration
+DB_HOST=localhost
+DB_PORT=5432
+DB_NAME=myapp
+DB_USER=admin
+DB_PASSWORD=secret
+
+# Redis configuration
+REDIS_URL=redis://localhost:6379
+REDIS_MAX_CONNECTIONS=10
+
+# Authentication
+AUTH_SECRET_KEY=your-secret-key
+AUTH_TOKEN_EXPIRY_SECONDS=3600
+AUTH_ALGORITHM=HS256
+
+# Feature flags
+FEATURE_NEW_CHECKOUT=true
+FEATURE_BETA_UI=false
+```
+
+Makes `env | grep DB_` useful for debugging.
+
+## Advanced Patterns
+
+### Pattern 5: Type Coercion
+
+Pydantic handles common conversions automatically.
+
+```python
+from pydantic_settings import BaseSettings
+from pydantic import Field, field_validator
+
+class Settings(BaseSettings):
+    # Automatically converts "true", "1", "yes" to True
+    debug: bool = False
+
+    # Automatically converts string to int
+    max_connections: int = 100
+
+    # Parse comma-separated string to list
+    allowed_hosts: list[str] = Field(default_factory=list)
+
+    @field_validator("allowed_hosts", mode="before")
+    @classmethod
+    def parse_allowed_hosts(cls, v: str | list[str]) -> list[str]:
+        if isinstance(v, str):
+            return [host.strip() for host in v.split(",") if host.strip()]
+        return v
+```
+
+Usage:
+
+```bash
+ALLOWED_HOSTS=example.com,api.example.com,localhost
+MAX_CONNECTIONS=50
+DEBUG=true
+```
+
+### Pattern 6: Environment-Specific Configuration
+
+Use an environment enum to switch behavior.
+
+```python
+from enum import Enum
+from pydantic_settings import BaseSettings
+from pydantic import Field, computed_field
+
+class Environment(str, Enum):
+    LOCAL = "local"
+    STAGING = "staging"
+    PRODUCTION = "production"
+
+class Settings(BaseSettings):
+    environment: Environment = Field(
+        default=Environment.LOCAL,
+        alias="ENVIRONMENT",
+    )
+
+    # Settings that vary by environment
+    log_level: str = Field(default="DEBUG", alias="LOG_LEVEL")
+
+    @computed_field
+    @property
+    def is_production(self) -> bool:
+        return self.environment == Environment.PRODUCTION
+
+    @computed_field
+    @property
+    def is_local(self) -> bool:
+        return self.environment == Environment.LOCAL
+
+# Usage
+if settings.is_production:
+    configure_production_logging()
+else:
+    configure_debug_logging()
+```
+
+### Pattern 7: Nested Configuration Groups
+
+Organize related settings into nested models.
+
+```python
+from pydantic import BaseModel
+from pydantic_settings import BaseSettings
+
+class DatabaseSettings(BaseModel):
+    host: str = "localhost"
+    port: int = 5432
+    name: str
+    user: str
+    password: str
+
+class RedisSettings(BaseModel):
+    url: str = "redis://localhost:6379"
+    max_connections: int = 10
+
+class Settings(BaseSettings):
+    database: DatabaseSettings
+    redis: RedisSettings
+    debug: bool = False
+
+    model_config = {
+        "env_nested_delimiter": "__",
+        "env_file": ".env",
+    }
+```
+
+Environment variables use double underscore for nesting:
+
+```bash
+DATABASE__HOST=db.example.com
+DATABASE__PORT=5432
+DATABASE__NAME=myapp
+DATABASE__USER=admin
+DATABASE__PASSWORD=secret
+REDIS__URL=redis://redis.example.com:6379
+```
+
+### Pattern 8: Secrets from Files
+
+For container environments, read secrets from mounted files.
+
+```python
+from pydantic_settings import BaseSettings
+from pydantic import Field
+from pathlib import Path
+
+class Settings(BaseSettings):
+    # Read from environment variable or file
+    db_password: str = Field(alias="DB_PASSWORD")
+
+    model_config = {
+        "secrets_dir": "/run/secrets",  # Docker secrets location
+    }
+```
+
+Pydantic will look for `/run/secrets/db_password` if the env var isn't set.
+
+### Pattern 9: Configuration Validation
+
+Add custom validation for complex requirements.
+
+```python
+from pydantic_settings import BaseSettings
+from pydantic import Field, model_validator
+
+class Settings(BaseSettings):
+    db_host: str = Field(alias="DB_HOST")
+    db_port: int = Field(alias="DB_PORT")
+    read_replica_host: str | None = Field(default=None, alias="READ_REPLICA_HOST")
+    read_replica_port: int = Field(default=5432, alias="READ_REPLICA_PORT")
+
+    @model_validator(mode="after")
+    def validate_replica_settings(self):
+        if self.read_replica_host and self.read_replica_port == self.db_port:
+            if self.read_replica_host == self.db_host:
+                raise ValueError(
+                    "Read replica cannot be the same as primary database"
+                )
+        return self
+```
+
+## Best Practices Summary
+
+1. **Never hardcode config** - All environment-specific values from env vars
+2. **Use typed settings** - Pydantic-settings with validation
+3. **Fail fast** - Crash on missing required config at startup
+4. **Provide dev defaults** - Make local development easy
+5. **Never commit secrets** - Use `.env` files (gitignored) or secret managers
+6. **Namespace variables** - `DB_HOST`, `REDIS_URL` for clarity
+7. **Import settings singleton** - Don't call `os.getenv()` throughout code
+8. **Document all variables** - README should list required env vars
+9. **Validate early** - Check config correctness at boot time
+10. **Use secrets_dir** - Support mounted secrets in containers