write-python-code

Files (14)

• SKILL.md
• example-async-http-integration.md · reference/
• example-avoid-unnecessary-abstraction.md · reference/
• example-comments.md · reference/
• example-django-ninja-router.md · reference/
• example-domain-parser.md · reference/
• example-explicit-loop-for-branching-logic.md · reference/
• example-explicit-provider-dispatch.md · reference/
• example-fastapi-lifespan-orchestration.md · reference/
• example-fastmcp-service-entrypoint.md · reference/
• example-focused-transformation.md · reference/
• example-pytest-example.md · reference/
• example-required-startup-configuration.md · reference/
• example-small-module-with-configuration.md · reference/

SKILL.md (first lines)

# How to Write Python Code

Use this skill to produce Python that is explicit, readable, typed, and operationally simple.

## Prose

Read and apply `write-text` from the active skill catalog or [sibling skill](../write-text/SKILL.md) when drafting or revising READMEs, documentation, command help, explanatory comments, or docstrings. Reuse it if already loaded. Preserve Python comment and docstring formats and the code conventions below.

## Precedence

Follow rules in this order:

1. The user's explicit instructions.
2. Repository-local instructions and configuration.
3. This skill.
4. Established conventions where this skill leaves a choice open.

Apply these preferences to the functions and code being changed, including small directly related changes needed for consistency. Established inconsistent style alone does not override these preferences. Preserve behavior, public interfaces, and required tooling unless the task calls for changing them. Avoid unrelated project-wide renames, restructuring, or reformatting.

Before writing code, inspect the nearest relevant Python files plus `pyproject.toml`, tests, and lint or formatting configuration when available.

## Core Style

Prefer simple, direct code over abstraction for its own sake.

* Keep functions focused on one clear responsibility.
* Use descriptive variable and function names rather than abbreviations. Conventional short package and module names such as `cmd` are an exception.
* Prefer guard clauses when they reduce nesting.
* Avoid new classes, wrappers, factories, compatibility layers, dependencies, and configuration options unless they solve a concrete requirement.
* Keep orchestration code easy to read from top to bottom.
* Preserve asynchronous behavior in asynchronous code.
* Use framework-native patterns instead of recreating functionality manually.
* Keep side effects visible and close to the code that initiates them.

## Package and Module Names

Prefer conventional short package and module names such as `cmd` rather than `command`. Preserve existing names and public interfaces when modifying a repository. Do not rename unrelated packages or modules to enforce this preference.

## Imports

Group imports in this order and separate groups with one blank line:

```python
# Standard library imports.

# Third party imports.

# Local imports.
```

Include only groups that are present. Prefer direct imports of the symbols actually used. Remove unused imports.

Do not reorganize an existing file solely to add import headings when that would create unrelated churn, but use this convention in new modules and when materially editing the import section.

## Constants and Configuration

Place module-level constants after imports. When the surrounding project uses section headings, label the block:

```python
# Constants.
```

Use uppercase names for true module-level constants.

For environment-based configuration:

* Use `environ["NAME"]` when the value is required.
* Use `getenv("NAME", default)` when a default is intentional.
* Convert environment strings to their required types explicitly.
* Fail early with a clear error when startup cannot continue without a required setting.
* Do not embed secrets, credentials, or environment-specific endpoints in source code.
* Prefer configuration at startup or construction boundaries rather than scattering environment reads through business logic.

## Types

Use modern Python type syntax.

* Add parameter and return types to public functions and non-trivial helpers.
* Prefer built-in generics such as `list[str]`, `dict[str, str]`, and `tuple[str, ...]`.
* Prefer unions such as `str | None`.
* Use `TypedDict`, dataclasses, Pydantic models, or framework schemas when structured data has a stable shape.
* Use `Any` only when the boundary is genuinely dynamic.
* Do not add complex typing that makes straightforward code harder to read.

## Functions and Control Flow

Write functions so their behavior is apparent without tracing unnecessary layers.

* Validate assumptions near the boundary.
* Raise a specific exception when callers need to distinguish a domain failure.
* Chain exceptions with `raise ... from exc` when translating a lower-level failure.
* Use `match` when dispatching across a small, explicit set of named modes and it is clearer than repeated conditionals.
* Use comprehensions when they remain immediately readable.
* Prefer explicit loops when they carry branching, error handling, or multiple side effects.
* Return structured data instead of encoding structure into strings unless a text interface specifically requires text.

## Filesystem and Serialization

Prefer `pathlib.Path` for filesystem work.

* Specify text encodings explicitly.
* Create parent directories only when the operation is expected to create output.
* Use standard-library serializers when they are sufficient.
* Keep parsing and serialization logic separate from orchestration when either becomes non-trivial.
* Validate file type, existence, or schema when failure would otherwise be ambiguous.

## Async and HTTP

Use asynchronous libraries consistently inside asynchronous workflows.

* Reuse an async client when lifecycle and scope make that practical. Otherwise use a clearly scoped context manager.
* Call `raise_for_status()` before consuming successful response data.
* Use explicit request parameters and headers.
* Use reasonable timeouts unless the surrounding framework manages them.
* Do not disable TLS verification except when the user explicitly requires it for a controlled environment and the security tradeoff is understood.
* Let transport errors propagate unless the caller needs a domain-specific error.

## Comments

From cyberphor/skills, MIT.

More from cyberphor/skills