Ref Sp Py Python

Python

Purpose

Provide portable Python defaults that emphasize explicit typing, simple structure, maintainable CLIs, and focused tests.

When to use this skill

• Writing or refactoring Python application code.
• Designing a Python CLI or maintenance script.
• Choosing how to type shared data and interfaces.
• Deciding where tests should live and what they should cover.
• Reviewing Python code for readability and long-term maintainability.

Scope Boundaries

• Use this skill for portable Python structure, typing, CLI, and testing guidance.
• Use ref-sp-dev-coding-patterns for language-agnostic naming, comment, and CLI ergonomics defaults.
• Use ref-sp-dev-projects-architecture for shared-utility thresholds and product-versus-maintenance boundaries.
• Use a repo's own repo-conventions skill (in this repo, ref-sp-dev-repo-conventions) when the question is about that repository's exact package names, top-level folders, or validation commands.

Defaults

• Prefer modern Python with type hints throughout public and shared code.
• If the repo already targets a modern Python baseline such as 3.14+, do not add from __future__ import annotations or similar compatibility boilerplate just to mimic older code.
• Prefer inferred return types for local helpers when the type checker can infer them cleanly; add return annotations when the function defines an API contract or inference would hide ambiguity.
• Prefer pathlib.Path over raw path strings.
• Prefer dataclasses, typed dicts, or small domain objects over loose dictionaries when structure matters.
• Prefer explicit exceptions and clear error messages over silent fallbacks.
• Prefer inert module imports: defer connections, I/O, and client construction to factory functions or lazy accessors rather than running them at module scope.
• Prefer uv for Python dependency management, virtual environments, and runnable project commands unless the repo already mandates another Python workflow.
• In uv-managed repos that use Poe, prefer tasks that invoke installed console entry points through uv run instead of adding tiny wrapper scripts.
• Prefer the repo's standard formatter, type checker, and test task wrappers when they exist.

Task Framing

Core Rules

Typing

• Type function parameters clearly.
• Prefer inferred return types for private/local helpers whose implementation makes the result obvious to the checker and reader.
• Add return annotations for public APIs, shared protocol or callback contracts, abstract methods, recursive functions, overload-style dispatch, CLI entrypoints, and cases where inference would become Any, object, or an overly broad union.
• On modern Python baselines, use standard annotation syntax directly instead of future-compatibility imports for postponed annotations.
• Prefer precise container types like list[str] or dict[str, int].
• Prefer object plus narrowing, focused casts, or type guards at unknown input boundaries instead of defaulting to Any.
• Reserve Any for rare interoperability gaps that cannot be expressed cleanly with narrower types.
• Use Protocol, TypedDict, dataclasses, or type aliases when they improve readability.
• Prefer type guards and restructuring over # type: ignore.
• Treat type hints as the checked parameter contract: Pyright and mypy verify annotations but never read docstring Args:, :param, or Returns: blocks, so a docstring that restates the signature drifts silently and no type check catches it.
• Prefer not to restate typed parameters in prose; if a project genuinely needs API docstrings, enforce them with a dedicated docstring linter, not the type checker. Prefer pydoclint — actively maintained, runs standalone or as a pre-commit hook, and adds no new lint stack; darglint is unmaintained. Ruff's equivalent DOC rules are still preview-only, so do not pull in Ruff just for docstring checks.

Structure

• Group related modules by feature or responsibility.
• Keep tests close to the behavior they cover when the repo layout supports it.
• Extract helper modules only when the behavior is truly shared or the file has become hard to navigate.
• On modern Python baselines, do not create __init__.py files solely to make directories importable; use implicit namespace packages unless package-level code is actually needed.

Module initialization

• Remember that import module executes the module's entire top level, so a module-scope client = SomeClient(...) runs its work at import time and makes import order significant.
• Prefer a factory function or a lazy accessor — for example a get_client() function, optionally memoized with functools.lru_cache — over a ready-built instance at module scope.
• Keep module-scope bindings limited to constants, type aliases, and other inert values; defer connections, configuration or environment reads, and I/O to call time.
• Treat module-scope instantiation of a stateful object as a deliberate, shared decision with a stated reason, not a default; explore a factory first. See ref-sp-dev-coding-patterns for the portable rule.
• In tests, module-scope setup is more acceptable given small modules, but still prefer fixtures over import-time work when it could couple test order.

# avoid: runs at import time, import order now matters
client = ApiClient(os.environ["API_URL"])

# prefer: construction deferred to call time
def get_client() -> ApiClient:
    return ApiClient(settings.api_url)

CLI and scripts

• If a command is part of the installed product, expose a clear main() function and register it as an entrypoint.
• If a uv-managed repo needs a development task for an installed dependency, prefer a Poe task that calls the dependency's console command through uv run, for example sync-shared-tool = "uv run shared-tool sync", instead of a pass-through script like python scripts/run_sync.py.
• If code is only for repo maintenance or one-off automation, keep it as a script.
• Use descriptive subcommands and flags for multi-action CLIs.

Packaging boundaries

• [project.scripts] is distribution metadata, not a local convenience: it becomes entry_points.txt inside the built artifact. There is no internal-only entrypoint, so a command meant to stay in the repo belongs in the task runner instead.
• Keep repo maintenance directories out of the distributed package list. Shipping them installs test files and repo-mutating scripts into every consumer's environment.
• Never distribute a generic top-level import name such as scripts, utils, common, or i18n. A directory with no __init__.py is a namespace package, so it merges across sys.path and silently shadows a consumer's same-named package — the consumer's own code loses, because installed paths usually sort ahead of theirs.
• Do not derive a repo root from __file__ in a module that can be installed. Once it is copied into site-packages the path resolves to the venv rather than the checkout. Walk up from the working directory, or keep the module out of the distribution.

Testing

• Add unit tests for non-trivial logic and error cases.
• Prefer small builders, fixtures, or factory helpers over giant setup blocks.
• Keep test names specific enough that failures are easy to localize.

Example Layouts

Packaged feature with collocated tests

src/package_name/report_sync/
  main.py
  main_test.py
  client.py
  client_test.py
  models.py

Repo maintenance script

scripts/
  update_from_upstream.py
  update_from_upstream_test.py

Give it a task-runner entry rather than a [project.scripts] one, so it keeps a first-class invocation without becoming distribution metadata:

[tool.poe.tasks]
init-project = "python scripts/init_project.py"

Invoked as uv run poe init-project --name cool-app; a cmd-type task forwards arguments through unchanged. The task table is read from the working tree and never lands in the built wheel, which is what makes it internal-only in a way [project.scripts] cannot be. The payoff beyond packaging is consistency: every documented command in the repo becomes uv run poe <task>, instead of one script path standing out from the rest.

Validation

• Public Python code is typed clearly and reads without guesswork.
• Parameter contracts live in type hints; any prose Args: docstrings are backed by a docstring linter, not assumed correct by the type checker.
• Modern-baseline projects do not carry legacy compatibility imports without a version-specific reason.
• Paths, errors, and data structures are explicit.
• Importing a module runs no connections or I/O; stateful clients are built by factories or lazy accessors, not at module scope.
• Product CLIs and maintenance scripts are separated intentionally, and internal commands are task-runner tasks rather than [project.scripts] entries.
• No distributed package claims a generic top-level import name, and no installable module derives a repo root from __file__.
• Tests cover non-trivial logic and stay readable.

References

• Read ./references/checklist.md for a quick Python review pass.
• Read ./assets/trigger-eval-queries.example.json when checking trigger quality for Python-focused prompts.