@coralai/sps-cli 0.55.12 → 0.56.0

package/skills/python/references/idioms.md

@@ -1,279 +0,0 @@
-# Python Idioms
-
-Core Pythonic patterns. Language-focused (no architecture here).
-
-## EAFP — Easier to Ask Forgiveness Than Permission
-
-Python prefers exception handling over condition checking.
-
-```python
-# Good: EAFP
-def get_value(d: dict, key: str, default=None):
-    try:
-        return d[key]
-    except KeyError:
-        return default
-
-# Bad: LBYL (Look Before You Leap) — race condition risk, slower, less Pythonic
-def get_value(d: dict, key: str, default=None):
-    if key in d:
-        return d[key]
-    return default
-```
-
-When to use which: EAFP is Pythonic for dict / attr / file access. LBYL is fine for user-facing validation where the failure message matters.
-
-## Comprehensions
-
-Prefer comprehensions over `map`/`filter` + lambda. Readability wins.
-
-```python
-# List / set / dict comprehensions
-active_names = [u.name for u in users if u.is_active]
-unique_tags = {t.strip() for tag_group in raw for t in tag_group.split(',')}
-user_ages = {u.id: u.age for u in users}
-
-# Generator expression (lazy, memory-efficient)
-total = sum(order.total for order in orders if order.paid)
-```
-
-**Rule**: If the comprehension doesn't fit on 2 lines, rewrite as a `for` loop. Nested comprehensions (`[x for x in y for z in w]`) are almost always unreadable.
-
-## Generator Functions
-
-Lazy iteration for large datasets. Use `yield` to avoid loading everything into memory.
-
-```python
-def read_large_file(path: str) -> Iterator[str]:
-    with open(path) as f:
-        for line in f:
-            yield line.strip()
-
-# Caller: streams one line at a time
-for line in read_large_file('huge.log'):
-    process(line)
-```
-
-Generator expressions (parentheses not brackets):
-```python
-squared = (x * x for x in range(10_000_000))  # 0 memory allocated
-```
-
-## Context Managers (`with`)
-
-Use `with` for any resource (file, lock, DB conn, etc.). Never manual `open()` / `close()`.
-
-```python
-# File
-with open('data.json') as f:
-    data = json.load(f)
-
-# Multiple resources
-with open('in.txt') as src, open('out.txt', 'w') as dst:
-    dst.write(src.read().upper())
-
-# Custom context manager (contextlib)
-from contextlib import contextmanager
-
-@contextmanager
-def temp_directory():
-    d = tempfile.mkdtemp()
-    try:
-        yield d
-    finally:
-        shutil.rmtree(d)
-
-with temp_directory() as d:
-    # use d, auto-cleaned
-    pass
-```
-
-## Decorators
-
-Use for cross-cutting concerns (logging, caching, timing, auth). Don't nest more than 2 deep.
-
-```python
-# Simple decorator
-from functools import wraps
-
-def timed(func):
-    @wraps(func)  # preserve name, docstring, signature
-    def wrapper(*args, **kwargs):
-        start = time.perf_counter()
-        result = func(*args, **kwargs)
-        duration = time.perf_counter() - start
-        logger.info(f"{func.__name__} took {duration:.3f}s")
-        return result
-    return wrapper
-
-@timed
-def expensive_operation(x: int) -> int:
-    time.sleep(1)
-    return x * 2
-```
-
-Parameterized decorators (3 levels deep — use sparingly):
-```python
-def retry(max_attempts: int = 3):
-    def decorator(func):
-        @wraps(func)
-        def wrapper(*args, **kwargs):
-            for attempt in range(max_attempts):
-                try:
-                    return func(*args, **kwargs)
-                except Exception:
-                    if attempt == max_attempts - 1:
-                        raise
-        return wrapper
-    return decorator
-
-@retry(max_attempts=5)
-def flaky_api_call(): ...
-```
-
-## Data Classes
-
-Prefer `dataclass` over manual `__init__` for value objects. Use `frozen=True` for immutability.
-
-```python
-from dataclasses import dataclass, field
-from typing import ClassVar
-
-@dataclass(frozen=True, slots=True)
-class User:
-    id: str
-    name: str
-    email: str
-    roles: list[str] = field(default_factory=list)  # never mutable default!
-    created_at: datetime = field(default_factory=datetime.now)
-
-    # Class-level constant
-    MAX_ROLES: ClassVar[int] = 10
-```
-
-**Rules**:
-- `slots=True` for performance (Python 3.10+)
-- `frozen=True` if the object shouldn't change after creation
-- Never use mutable default (`roles: list[str] = []`) — use `field(default_factory=list)`
-- `ClassVar` for constants that shouldn't become instance attrs
-
-## `pathlib` over `os.path`
-
-```python
-from pathlib import Path
-
-# Good
-config = Path.home() / '.myapp' / 'config.json'
-if config.exists():
-    data = json.loads(config.read_text())
-for log in Path('logs').glob('*.log'):
-    process(log)
-
-# Bad
-import os
-config = os.path.join(os.path.expanduser('~'), '.myapp', 'config.json')
-if os.path.exists(config):
-    with open(config) as f:
-        data = json.load(f)
-```
-
-## `match`/`case` — structural pattern matching (Python 3.10+)
-
-Use for dispatch on shape, not just value. For simple value checks, `if/elif` is still cleaner.
-
-```python
-def describe(point):
-    match point:
-        case (0, 0):
-            return "origin"
-        case (0, y):
-            return f"y-axis at {y}"
-        case (x, 0):
-            return f"x-axis at {x}"
-        case (x, y) if x == y:
-            return f"diagonal at {x}"
-        case (x, y):
-            return f"point ({x}, {y})"
-        case _:
-            return "not a point"
-
-# Class patterns — great for ADTs / sum types
-match event:
-    case Click(x=x, y=y):
-        handle_click(x, y)
-    case KeyPress(key="q"):
-        quit()
-    case KeyPress(key=k):
-        handle_key(k)
-```
-
-**When NOT to use**: straightforward value checks (`if x == 1: ... elif x == 2: ...`). Pattern matching shines for destructuring nested shapes.
-
-## Walrus operator `:=` (Python 3.8+)
-
-Assignment expression — assign and use in the same statement. Use sparingly.
-
-```python
-# Good: avoid double-reading / double-computing
-while chunk := f.read(8192):
-    process(chunk)
-
-if (n := len(data)) > 10:
-    print(f"Too many items ({n})")
-
-# Good in comprehensions: avoid recomputing
-results = [y for x in items if (y := expensive(x)) is not None]
-
-# Bad: over-use where a regular assignment is clearer
-if (user := db.find(uid)) and user.active and (perms := user.get_perms()) and "admin" in perms:
-    ...
-# Prefer:
-user = db.find(uid)
-if user and user.active:
-    perms = user.get_perms()
-    if "admin" in perms: ...
-```
-
-## f-strings (Python 3.6+)
-
-Only use `.format()` or `%` for legacy code.
-
-```python
-# Good
-msg = f"User {user.name} (id={user.id}) logged in at {when:%Y-%m-%d %H:%M}"
-
-# Also good: f-string expressions
-msg = f"Total: ${sum(o.amount for o in orders):,.2f}"
-
-# Python 3.8+: self-documenting expressions with =
-msg = f"{x=}, {y=}"   # => "x=5, y=10"
-
-# Python 3.12+: f-strings accept any quotes, backslashes, and multiline
-msg = f"path: {Path('a') / 'b'}, lines:\n{"\n".join(items)}"
-
-# Bad
-msg = "User {} (id={}) logged in at {}".format(user.name, user.id, when)
-msg = "User %s (id=%d) logged in at %s" % (user.name, user.id, when)
-```
-
-## Forbidden patterns (auto-reject in code review)
-
-| Anti-pattern | Why bad | Fix |
-|---|---|---|
-| `def f(x=[])` | Mutable default shared across calls | `def f(x=None): x = x or []` |
-| `except:` (bare) | Catches SystemExit, KeyboardInterrupt | `except SomeError:` |
-| `from m import *` | Pollutes namespace, hides origin | explicit imports |
-| `global x` in functions | Hidden state | pass explicitly or use a class |
-| `type(x) == Foo` | Doesn't handle subclasses | `isinstance(x, Foo)` |
-| `if x == None` | Identity check, not equality | `if x is None` |
-
-## Naming conventions (PEP 8)
-
-| Kind | Style | Example |
-|---|---|---|
-| Variables, functions | `snake_case` | `user_count`, `get_user()` |
-| Constants | `UPPER_SNAKE` | `MAX_RETRIES`, `DEFAULT_TIMEOUT` |
-| Classes | `PascalCase` | `UserService`, `HTTPClient` |
-| Private (intent) | `_leading_underscore` | `_internal_cache` |
-| Name mangling | `__double_leading` | `__private_attr` (use sparingly) |
-| Module, package | `snake_case` | `user_service.py`, `payment_gateway/` |

package/skills/python/references/packaging.md

@@ -1,233 +0,0 @@
-# Python Packaging & Environments
-
-Modern Python packaging. Defaults: `pyproject.toml` + `uv` (or `pip` + `venv`). No `setup.py`, no `requirements.txt` pinning in libraries.
-
-## Tool landscape (2024–2026)
-
-| Need | Tool | Notes |
-|---|---|---|
-| Env + lockfile + installer | **`uv`** | Fastest; Rust-based; drop-in for pip/venv/pip-tools/poetry |
-| Traditional installer | `pip` | Still the universal fallback |
-| Env isolation only | `venv` (stdlib) | Zero-dependency; fine for simple cases |
-| Project manager (alt) | `poetry`, `hatch`, `pdm` | Mature; pick one per project, don't mix |
-| Build backend | `hatchling`, `setuptools`, `flit-core`, `poetry-core` | Declared in `pyproject.toml` |
-
-Default recommendation: `uv` for new work. Its `pyproject.toml` is standard so projects stay portable.
-
-## `pyproject.toml` — the one config file
-
-```toml
-[project]
-name = "myapp"
-version = "0.1.0"
-description = "Short one-liner"
-readme = "README.md"
-requires-python = ">=3.11"
-license = { text = "MIT" }
-authors = [{ name = "Coral", email = "coral@example.com" }]
-dependencies = [
-    "httpx>=0.27",
-    "pydantic>=2.5",
-]
-
-[project.optional-dependencies]
-dev = [
-    "pytest>=8.0",
-    "pytest-cov",
-    "mypy",
-    "ruff",
-]
-
-[project.scripts]
-myapp = "myapp.cli:main"     # creates a `myapp` executable on install
-
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[tool.hatch.build.targets.wheel]
-packages = ["src/myapp"]
-
-[tool.ruff]
-line-length = 100
-target-version = "py311"
-
-[tool.mypy]
-strict = true
-python_version = "3.11"
-```
-
-## Project layout — `src/` over flat
-
-Keep source under `src/` so `import myapp` during tests uses the installed package, not the working directory. Catches "works locally, broken when installed" bugs early.
-
-```
-myapp/
-├── pyproject.toml
-├── README.md
-├── src/
-│   └── myapp/
-│       ├── __init__.py
-│       ├── cli.py
-│       └── services/
-│           └── user.py
-└── tests/
-    ├── conftest.py
-    └── test_user.py
-```
-
-Avoid: top-level `myapp/` mixed with `tests/` — `sys.path` tricks mask import bugs.
-
-## `uv` — day-to-day commands
-
-```bash
-# Create project
-uv init myapp --package
-
-# Add / remove dependencies (updates pyproject.toml + uv.lock)
-uv add httpx pydantic
-uv add --dev pytest pytest-cov mypy ruff
-uv remove requests
-
-# Install everything (reproducible from lockfile)
-uv sync
-
-# Run anything inside the env
-uv run pytest
-uv run python -m myapp
-uv run ruff check src/
-
-# Pin Python version
-uv python pin 3.12
-
-# Build a wheel / sdist
-uv build
-
-# Upgrade dependencies
-uv lock --upgrade
-uv lock --upgrade-package httpx
-```
-
-Commit `uv.lock` for **applications**. For **libraries**, don't commit it — let downstreams resolve against their own constraints.
-
-## `pip` + `venv` — classic workflow
-
-```bash
-python -m venv .venv
-source .venv/bin/activate     # Windows: .venv\Scripts\activate
-
-pip install -e '.[dev]'       # editable install with dev extras
-pip install --upgrade pip
-
-# Freeze what's installed (for apps, not libs)
-pip freeze > requirements.lock.txt
-pip install -r requirements.lock.txt
-```
-
-Never `pip install` into the system Python. Use a venv per project.
-
-## Dependency specification
-
-```toml
-[project]
-dependencies = [
-    "httpx>=0.27,<1.0",             # library: allow a compatible range
-    "pydantic~=2.5",                # ~= means >=2.5,<3.0
-    "requests; python_version<'3.11'",   # conditional
-    "rich[jupyter]>=13.0",          # with extras
-]
-```
-
-| Specifier | Meaning | Use for |
-|---|---|---|
-| `pkg>=X.Y` | at least this version | libraries |
-| `pkg~=X.Y` | compatible release (=X.*, <X+1) | common default |
-| `pkg==X.Y.Z` | exact pin | applications with lockfile |
-| `pkg>=A,<B` | explicit range | upper bound on known-breaking releases |
-
-**Libraries**: loose constraints (`>=X`). **Applications**: tight lockfile (`uv.lock` or `requirements.lock.txt`).
-
-## Version management
-
-Single source of truth for the version. Don't duplicate in `__init__.py`.
-
-```toml
-# pyproject.toml
-[project]
-dynamic = ["version"]
-
-[tool.hatch.version]
-path = "src/myapp/__about__.py"
-```
-
-```python
-# src/myapp/__about__.py
-__version__ = "0.1.0"
-
-# src/myapp/__init__.py
-from myapp.__about__ import __version__
-__all__ = ["__version__"]
-```
-
-## Python version management
-
-`pyenv` for installing Python versions; `uv python` integrates this. Project-level pin:
-
-```bash
-uv python pin 3.12      # writes .python-version
-```
-
-CI: install the exact version from `.python-version` so prod and dev match.
-
-## Publishing to PyPI
-
-```bash
-uv build
-uv publish                  # uses PyPI API token from UV_PUBLISH_TOKEN
-
-# Or with twine
-python -m build
-twine upload dist/*
-```
-
-Pre-flight checks:
-- `README.md` renders on PyPI (test with `twine check dist/*`)
-- Version bumped
-- `CHANGELOG.md` updated
-- Tag release in git: `git tag v0.1.0 && git push --tags`
-
-## Private packages
-
-```toml
-[tool.uv.sources]
-mycompany-lib = { git = "ssh://git@github.com/mycompany/lib.git", tag = "v1.2.0" }
-internal = { path = "../internal", editable = true }
-```
-
-Or via `--extra-index-url` for private PyPI indexes.
-
-## `__init__.py` — keep it minimal
-
-```python
-# src/myapp/__init__.py
-"""Public API for myapp."""
-from myapp.services import UserService
-from myapp.models import User
-
-__all__ = ["UserService", "User"]
-```
-
-Don't run heavy init logic at import time — it slows down `import myapp` for every caller.
-
-## Common mistakes
-
-| Mistake | Fix |
-|---|---|
-| `setup.py` in a new project | Use `pyproject.toml` only |
-| Committing `venv/` or `.venv/` | Add to `.gitignore` |
-| `pip install` without a venv | Always use `uv` or `venv` |
-| `requirements.txt` in a library | Declare in `pyproject.toml`; let consumers pin |
-| Version duplicated in 3 files | Use `dynamic = ["version"]` |
-| `from myapp import *` in `__init__.py` | Explicit exports via `__all__` |
-| Flat layout causing import surprises | Use `src/` layout |
-| Running tests with local `myapp/` shadowing the installed one | `pip install -e '.[dev]'`, then `pytest` |