@martinffx/atelier 2.0.0 → 3.0.0

package/skills/python-build-tools/references/basedpyright.md

@@ -1,321 +0,0 @@
-# basedpyright - Strict Type Checking
-
-Fast type checker forked from pyright with improved performance and stricter defaults. Recommended for production Python codebases.
-
-## Configuration
-
-Complete `[tool.basedpyright]` section in pyproject.toml:
-
-```toml
-[tool.basedpyright]
-typeCheckingMode = "strict"
-pythonVersion = "3.12"
-pythonPlatform = "Linux"
-
-# Paths
-include = ["src", "tests"]
-exclude = ["**/__pycache__", ".venv", "build", "dist"]
-ignore = []
-typeshedPath = ""
-stubPath = ""
-
-# Reporting
-reportMissingImports = true
-reportMissingTypeStubs = false
-reportMissingModuleSource = true
-reportUndefinedVariable = true
-reportPrivateUsage = false
-reportGeneralTypeIssues = true
-reportOptionalMemberAccess = true
-reportOptionalSubscript = true
-reportOptionalCall = true
-reportOptionalIterable = true
-reportOptionalContextManager = true
-reportOptionalOperand = true
-reportOptionalTypeArg = true
-reportUnusedImport = true
-reportUnusedClass = true
-reportUnusedFunction = true
-reportUnusedVariable = true
-reportDuplicateImport = true
-reportIncompatibleMethodOverride = true
-reportIncompatibleVariableOverride = true
-reportAssignmentType = true
-reportReturnType = true
-
-# Lenient mode (use sparingly)
-reportIncompatibleMethodOverride = "warning"
-reportOptionalMemberAccess = "warning"
-```
-
-## Type Checking Modes
-
-- **off**: No type checking
-- **basic**: Basic type checking (fastest)
-- **standard**: Standard type checking (default)
-- **strict**: Strict type checking (recommended for production)
-
-Recommend `strict` for new projects. For existing codebases, start with `basic` and incrementally increase.
-
-## Common Type Patterns
-
-### Basic Types
-
-```python
-from typing import Optional, Union, Any
-from decimal import Decimal
-
-# Basic types
-name: str = "Alice"
-age: int = 30
-price: float = 19.99
-decimal_price: Decimal = Decimal("19.99")
-is_active: bool = True
-
-# Collections
-items: list[str] = ["apple", "banana"]
-mapping: dict[str, int] = {"count": 5}
-unique: set[str] = {"a", "b", "c"}
-coords: tuple[int, int] = (10, 20)
-
-# Optional (value or None)
-nickname: Optional[str] = None
-nickname = "Bob"  # OK
-
-# Union (multiple types)
-value: Union[int, str] = 42
-value = "text"  # OK
-
-# Generic unknown
-data: Any = {"key": "value"}  # Avoid when possible
-```
-
-### Functions
-
-```python
-def calculate_discount(
-    total: Decimal,
-    rate: Optional[Decimal] = None
-) -> Decimal:
-    """Calculate discount amount."""
-    if rate is None:
-        rate = Decimal("0.1")
-    return total * rate
-
-def process_items(items: list[str]) -> None:
-    """Process items - no return value."""
-    for item in items:
-        print(item)
-
-def get_or_default(value: Optional[str]) -> str:
-    """Return value or default."""
-    return value or "default"
-```
-
-### Classes
-
-```python
-from dataclasses import dataclass
-
-@dataclass
-class User:
-    """User entity with type hints."""
-    id: int
-    name: str
-    email: str
-    age: Optional[int] = None
-
-    def validate(self) -> None:
-        """Validate user data."""
-        if not self.name:
-            raise ValueError("Name required")
-        if self.age is not None and self.age < 0:
-            raise ValueError("Age must be positive")
-
-    @property
-    def is_adult(self) -> bool:
-        """Check if adult."""
-        if self.age is None:
-            return False
-        return self.age >= 18
-
-    def __str__(self) -> str:
-        return f"{self.name} ({self.email})"
-```
-
-### Generics
-
-```python
-from typing import Generic, TypeVar
-
-T = TypeVar("T")
-
-class Container(Generic[T]):
-    """Generic container."""
-    def __init__(self, item: T) -> None:
-        self.item = item
-
-    def get(self) -> T:
-        return self.item
-
-# Usage
-int_container: Container[int] = Container(42)
-value: int = int_container.get()
-
-str_container: Container[str] = Container("hello")
-text: str = str_container.get()
-```
-
-### Protocol (Structural Typing)
-
-```python
-from typing import Protocol
-
-class Logger(Protocol):
-    """Logger protocol."""
-    def log(self, message: str) -> None: ...
-    def error(self, message: str) -> None: ...
-
-class ConsoleLogger:
-    """Implements Logger protocol."""
-    def log(self, message: str) -> None:
-        print(f"INFO: {message}")
-
-    def error(self, message: str) -> None:
-        print(f"ERROR: {message}")
-
-def use_logger(logger: Logger) -> None:
-    """Use any logger that implements protocol."""
-    logger.log("Starting")
-    logger.error("Something failed")
-
-# ConsoleLogger satisfies Logger protocol
-use_logger(ConsoleLogger())
-```
-
-## Commands
-
-```bash
-# Type check entire project
-basedpyright
-
-# Type check specific file
-basedpyright src/main.py
-
-# Type check specific directory
-basedpyright src/
-
-# Verbose output
-basedpyright --verbose
-
-# Show warnings
-basedpyright --warnings
-
-# Output format
-basedpyright --outputjson
-
-# Type checking statistics
-basedpyright --stats
-
-# Configuration
-basedpyright --configfile custom.toml
-```
-
-## Integration
-
-### With VS Code
-
-Install extension: Pylance or Basedpyright (by Bazel)
-
-Add to `.vscode/settings.json`:
-
-```json
-{
-    "python.linting.enabled": true,
-    "[python]": {
-        "editor.defaultFormatter": "charliermarsh.ruff",
-        "editor.formatOnSave": true,
-        "editor.codeActionsOnSave": {
-            "source.organizeImports": "explicit"
-        }
-    },
-    "basedpyright.typeCheckingMode": "strict"
-}
-```
-
-### Pre-commit Hook
-
-Add to `.pre-commit-config.yaml`:
-
-```yaml
-- repo: local
-  hooks:
-    - id: basedpyright
-      name: basedpyright
-      entry: basedpyright
-      language: system
-      types: [python]
-      require_serial: true
-```
-
-### GitHub Actions
-
-```yaml
-- name: Type check with basedpyright
-  run: basedpyright
-```
-
-## Common Issues
-
-### Missing Type Stubs
-
-Install type stubs for third-party packages:
-
-```bash
-uv add --dev types-requests types-pyyaml types-click
-```
-
-### Ignoring Type Errors
-
-```python
-# Ignore entire line
-value: int = some_string_func()  # type: ignore
-
-# Ignore specific error
-value: int = some_string_func()  # type: ignore[assignment]
-```
-
-Use sparingly - type hints should be fixed, not ignored.
-
-### Strict Mode Challenges
-
-If strict mode is too strict, consider:
-
-1. Using `type: ignore` for legacy code
-2. Starting with `standard` mode and gradually increasing strictness
-3. Configuring `reportPrivateUsage = false` for internal APIs
-4. Excluding test code: `exclude = ["tests"]`
-
-## Performance
-
-Basedpyright is 2-5x faster than mypy on large codebases.
-
-Typical project:
-- mypy: 10-30 seconds
-- basedpyright: 2-10 seconds
-
-## Troubleshooting
-
-```bash
-# Clear cache
-rm -rf .basedpyright
-
-# Verbose error messages
-basedpyright --verbose
-
-# Check configuration
-basedpyright --showconfig
-
-# Update tool
-uv add --upgrade basedpyright
-```

package/skills/python-build-tools/references/ruff.md

@@ -1,225 +0,0 @@
-# ruff - Fast Python Linter and Formatter
-
-Rust-based linter and formatter that replaces black, isort, flake8, and pylint. 10-100x faster with auto-fix and formatting capabilities.
-
-## Configuration
-
-Complete `[tool.ruff]` section in pyproject.toml:
-
-```toml
-[tool.ruff]
-line-length = 100
-target-version = "py312"
-src = ["src", "tests"]
-extend-exclude = [".git", ".venv", "node_modules"]
-
-[tool.ruff.lint]
-select = [
-    "E",      # pycodestyle errors
-    "F",      # pyflakes
-    "W",      # pycodestyle warnings
-    "I",      # isort (import sorting)
-    "N",      # pep8-naming
-    "UP",     # pyupgrade
-    "RUF",    # Ruff-specific rules
-    "B",      # flake8-bugbear
-    "C4",     # flake8-comprehensions
-    "SIM",    # flake8-simplify
-    "PIE",    # flake8-pie
-    "RET",    # flake8-return
-    "Q",      # flake8-quotes
-    "PT",     # flake8-pytest-style
-    "LOG",    # flake8-logging
-]
-ignore = [
-    "E501",   # Line too long (handled by formatter)
-    "E203",   # Whitespace before punctuation
-    "PT004",  # Fixture doesn't return anything
-]
-extend-safe-fixes = ["PIE794", "RUF100"]
-
-[tool.ruff.lint.per-file-ignores]
-"__init__.py" = ["F401"]  # Ignore unused imports in __init__
-"tests/*.py" = ["B008"]   # Ignore mutable defaults in tests
-
-[tool.ruff.lint.isort]
-known-first-party = ["my_app", "my_service"]
-force-single-line = false
-combine-as-imports = true
-
-[tool.ruff.lint.flake8-quotes]
-docstring-quotes = "double"
-inline-quotes = "double"
-
-[tool.ruff.lint.flake8-comprehensions]
-allow-dict-calls-with-keyword-arguments = true
-
-[tool.ruff.format]
-quote-style = "double"
-indent-style = "space"
-skip-magic-trailing-comma = false
-line-ending = "auto"
-docstring-code-format = true
-```
-
-## Rules Reference
-
-### Error Categories
-
-- **E/W**: pycodestyle - Style errors and warnings
-- **F**: pyflakes - Logic errors
-- **I**: isort - Import sorting
-- **N**: pep8-naming - Naming conventions
-- **UP**: pyupgrade - Modernize code
-- **RUF**: Ruff-specific rules
-
-### Common Issues and Fixes
-
-```python
-# ✓ Correct: Double quotes
-message = "hello"
-
-# ✗ Error: Single quotes (unless docstring)
-message = 'hello'
-
-# ✓ Correct: Sorted imports
-import asyncio
-import os
-from typing import Optional
-
-from pydantic import BaseModel
-from sqlalchemy import Column, String
-
-# ✗ Error: Unsorted imports
-from sqlalchemy import Column
-import os
-import asyncio
-
-# ✓ Correct: List comprehension
-squares = [x**2 for x in range(10)]
-
-# ✗ Error: Using map instead of comprehension (C401)
-squares = list(map(lambda x: x**2, range(10)))
-
-# ✓ Correct: Type hints with modern syntax
-items: list[str] = ["apple"]
-config: dict[str, int] = {}
-
-# ✗ Error: Old-style type hints
-items: List[str] = ["apple"]
-config: Dict[str, int] = {}
-```
-
-## Command Line Usage
-
-```bash
-# Check for issues
-ruff check .
-
-# Auto-fix issues
-ruff check --fix .
-
-# Fix specific file
-ruff check --fix src/main.py
-
-# Format code
-ruff format .
-
-# Format and check combined
-ruff check --fix . && ruff format .
-
-# Check specific rule
-ruff check . --select E501
-
-# Ignore specific rule
-ruff check . --ignore F841
-
-# Show statistics
-ruff check . --statistics
-
-# Generate configuration
-ruff config
-
-# Check what would be fixed
-ruff check . --diff
-```
-
-## Integration Examples
-
-### With pytest
-
-In `pyproject.toml`:
-
-```toml
-[tool.ruff.lint]
-select = ["PT"]  # Include pytest-style rules
-
-[tool.ruff.lint.flake8-pytest-style]
-fixture-parentheses = true
-parametrize-names-type = "csv"
-parametrize-values-row-type = "tuple"
-```
-
-### Pre-commit Hook
-
-Create `.pre-commit-config.yaml`:
-
-```yaml
-repos:
-  - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.8.0
-    hooks:
-      - id: ruff
-        args: [--fix]
-      - id: ruff-format
-```
-
-### GitHub Actions
-
-```yaml
-- name: Lint with ruff
-  run: ruff check --fix .
-
-- name: Format with ruff
-  run: ruff format .
-
-- name: Check format
-  run: ruff format --check .
-```
-
-## Performance Notes
-
-- Ruff processes entire codebase in ~200ms
-- Parallel processing on multi-core systems
-- Significantly faster than pycodestyle + isort + black
-
-## Migration from Black/isort
-
-Replace:
-
-```bash
-# Old
-black src/ && isort src/
-
-# New
-ruff format . && ruff check --fix .
-```
-
-## Troubleshooting
-
-```bash
-# Show which rules are active
-ruff rule --all
-
-# Show rule details
-ruff rule E501
-
-# Check what ruff would do (dry run)
-ruff check . --diff
-
-# Clear cache if issues occur
-rm -rf .ruff_cache
-
-# Verbose output
-ruff check . -v
-```