init pi folder
This commit is contained in:
Matteo Rosati
@@ -0,0 +1,100 @@
|
||||
# Python Reference
|
||||
|
||||
Use this file only when deeper guidance is needed. `SKILL.md` is the default operating contract.
|
||||
|
||||
## When To Consult This File
|
||||
|
||||
- You are choosing between multiple Python design options.
|
||||
- You need stronger guidance for typing, validation, async, or testing.
|
||||
- You are creating new modules or new project structure rather than making a local edit.
|
||||
- You are reviewing code and want a more complete checklist.
|
||||
|
||||
## Stronger Typing Guidance
|
||||
|
||||
- Prefer `collections.abc` and `typing` abstractions such as `Sequence`, `Mapping`, `Callable`, and `Iterator`.
|
||||
- Use `Protocol` for behavioral contracts when inheritance is not required.
|
||||
- Use `TypedDict` for structured dictionary payloads when a dataclass or Pydantic model is not appropriate.
|
||||
- Use `Final` for constants and `ClassVar` for class-level attributes when helpful.
|
||||
- Keep `Any` rare, local, and justified.
|
||||
- If the project supports it, use `@override` on overriding methods.
|
||||
|
||||
## Architecture Heuristics
|
||||
|
||||
- Domain layer: pure business rules, no framework or persistence code.
|
||||
- Repository or data layer: database and external service access.
|
||||
- Service or use-case layer: orchestration across domain rules and collaborators.
|
||||
- Interface layer: HTTP, CLI, events, serialization, request and response shaping.
|
||||
- Infrastructure layer: configuration, logging setup, DB sessions, clients.
|
||||
|
||||
Use this split when it fits the repository. Do not impose it mechanically on smaller scripts or simpler codebases.
|
||||
|
||||
## Data Modeling
|
||||
|
||||
- Use Pydantic for request payloads, config, and data from untrusted sources.
|
||||
- Use dataclasses for internal value objects and simple structured state.
|
||||
- Use `frozen=True` for values that should not change after creation.
|
||||
- Use `slots=True` where the codebase already prefers it or where many instances are created.
|
||||
|
||||
## Error Handling
|
||||
|
||||
- Prefer project-specific exception types over generic `ValueError` or `RuntimeError` when a domain concept exists.
|
||||
- Wrap lower-level exceptions with domain context when crossing layers.
|
||||
- Keep exception handling near boundaries unless recovery is local and explicit.
|
||||
|
||||
## Logging
|
||||
|
||||
- Prefer structured logging when the project supports it.
|
||||
- Log important operational events at service or interface boundaries.
|
||||
- Do not log secrets, credentials, or sensitive user data.
|
||||
- Avoid `print()` for operational behavior unless the program is explicitly a simple script or CLI output path.
|
||||
|
||||
## Async Guidance
|
||||
|
||||
- Use async for I/O-bound workflows, not CPU-bound work.
|
||||
- Keep blocking calls out of coroutines; use thread or process offloading where appropriate.
|
||||
- Prefer `asyncio.TaskGroup` over ad hoc task orchestration when available.
|
||||
- Be explicit about sync-to-async boundaries.
|
||||
|
||||
## Security Guidance
|
||||
|
||||
- Never hardcode secrets or credentials.
|
||||
- Validate all external input before it enters core logic.
|
||||
- Avoid dangerous calls unless explicitly justified and safely constrained:
|
||||
- `eval`, `exec`
|
||||
- `pickle.loads`
|
||||
- `yaml.load`
|
||||
- `subprocess` with `shell=True`
|
||||
- `os.system`
|
||||
- Do not interpolate raw user input into SQL, shell commands, or file-system-sensitive operations.
|
||||
|
||||
## Testing Guidance
|
||||
|
||||
- Update tests whenever behavior changes.
|
||||
- Prefer unit tests for pure logic and integration tests for boundaries.
|
||||
- Use parametrization to improve coverage without duplicating setup.
|
||||
- Test behavior and observable outcomes rather than implementation details.
|
||||
- Mock external boundaries selectively; avoid mocking the core logic you actually want to verify.
|
||||
|
||||
## Review Heuristics
|
||||
|
||||
When reviewing Python changes, prioritize:
|
||||
|
||||
- correctness and regressions
|
||||
- incomplete or misleading typing
|
||||
- invalid assumptions at trust boundaries
|
||||
- misplaced logic between layers
|
||||
- unnecessary abstraction or indirection
|
||||
- missing tests for changed behavior
|
||||
- risky calls, secret handling, or unsafe subprocess use
|
||||
|
||||
## Common Verification Flow
|
||||
|
||||
If the repository uses `uv`, the usual flow is:
|
||||
|
||||
1. `uv run ruff format <paths>`
|
||||
2. `uv run ruff check --fix <paths>`
|
||||
3. `uv run ruff check <paths>`
|
||||
4. `uv run mypy <paths-or-package>`
|
||||
5. `uv run pytest <relevant tests>`
|
||||
|
||||
If the repository uses different commands or tools, follow the repository.
|
||||
@@ -0,0 +1,96 @@
|
||||
---
|
||||
name: python-dev
|
||||
description: |
|
||||
Apply this skill whenever writing, editing, generating, or reviewing Python code. Favor small, typed, idiomatic changes that fit the existing codebase and finish with lint, type checks, and relevant tests passing. Use `REFERENCE.md` only when deeper guidance is needed.
|
||||
version: 3.1.0
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# Python Development
|
||||
|
||||
Use this skill for any task that creates or changes Python code.
|
||||
|
||||
## Operating Mode
|
||||
|
||||
- Match the repository's existing style and architecture before introducing new patterns.
|
||||
- Prefer the smallest correct change over broad refactors.
|
||||
- Keep code easy to read: flat control flow, clear names, limited indirection.
|
||||
- Do not force framework choices or house style upgrades into unrelated work.
|
||||
- Do not add compatibility layers, feature flags, or speculative abstractions unless required.
|
||||
- If an API or library detail is uncertain, check current docs before coding.
|
||||
|
||||
## Defaults
|
||||
|
||||
- Add `from __future__ import annotations` to new Python modules.
|
||||
- Fully annotate public functions and important variables.
|
||||
- Prefer precise types over broad ones.
|
||||
- Use `X | Y` and `X | None` syntax.
|
||||
- Avoid `Any`; if unavoidable, keep it narrow and explain why.
|
||||
- Use `TYPE_CHECKING` for type-only imports when it improves runtime imports or avoids cycles.
|
||||
- Prefer simple functions and dataclasses unless the codebase clearly wants a heavier OO design.
|
||||
- Use classes for durable domain concepts or stateful collaborators, not by default.
|
||||
- Prefer composition over inheritance.
|
||||
- Keep responsibilities separated: domain logic, data access, and interface code should stay distinct.
|
||||
- Do not place business logic directly in route handlers, CLI commands, or persistence code.
|
||||
- Validate untrusted input at the boundary.
|
||||
- Prefer Pydantic for external input, config, or data crossing trust boundaries.
|
||||
- Prefer `@dataclass(slots=True)` for internal structured data.
|
||||
- Use `frozen=True` when immutability is a natural fit.
|
||||
- Prefer `pathlib` over `os.path`.
|
||||
- Prefer f-strings.
|
||||
- Prefer standard idioms like comprehensions, `enumerate`, `zip`, and context managers where appropriate.
|
||||
- Use guard clauses to reduce nesting.
|
||||
- Avoid mutable default arguments, bare `except:`, and `type(x) == T` checks.
|
||||
|
||||
## Error Handling
|
||||
|
||||
- Raise specific exceptions with useful messages.
|
||||
- Keep `try` blocks narrow.
|
||||
- Preserve context with `raise ... from exc` when re-raising.
|
||||
- Do not swallow exceptions silently.
|
||||
- Log at system boundaries or orchestration layers, not deep inside pure domain logic.
|
||||
|
||||
## Async
|
||||
|
||||
- Use `async` only for real I/O-bound workflows.
|
||||
- Do not call blocking I/O directly from coroutines.
|
||||
- Keep sync and async boundaries explicit.
|
||||
|
||||
## Security
|
||||
|
||||
- Never hardcode secrets, tokens, or credentials.
|
||||
- Validate external input before using it.
|
||||
- Avoid dangerous calls unless explicitly justified: `eval`, `exec`, `pickle.loads`, `yaml.load`, `shell=True`, `os.system`.
|
||||
- Do not build shell commands from raw user input.
|
||||
- Avoid logging secrets or sensitive user data.
|
||||
|
||||
## Testing
|
||||
|
||||
- Add or update tests for behavior you change.
|
||||
- Prefer unit tests for pure logic and integration tests for persistence or external boundaries.
|
||||
- Use parametrization to cover multiple cases succinctly.
|
||||
- Mock at external boundaries, not inside the core logic under test, unless the repo uses a different testing style.
|
||||
|
||||
## Tooling
|
||||
|
||||
- Use `uv` for Python dependency and tool execution when the project uses it.
|
||||
- Run formatters, linters, and type checks after Python changes.
|
||||
- Default verification flow: format, lint, type-check, then run relevant tests.
|
||||
- If the repo uses different commands, follow the repo.
|
||||
|
||||
## Completion Checklist
|
||||
|
||||
Before finishing Python work, make sure:
|
||||
|
||||
- the change matches existing project patterns
|
||||
- code is fully typed to the repo's standard
|
||||
- untrusted input is validated at the boundary
|
||||
- logic is kept in the right layer
|
||||
- `ruff` is clean
|
||||
- `mypy` is clean
|
||||
- relevant tests pass
|
||||
- no secrets or risky calls were introduced without justification
|
||||
|
||||
## Reference
|
||||
|
||||
See `REFERENCE.md` for optional deeper guidance on typing, architecture, async patterns, testing, security, and review heuristics.
|
||||
Reference in New Issue
Block a user