python
Use when writing, reviewing, or modernizing Python 3.11+ code. Produces fully type-annotated modules, async I/O, dataclasses and protocols, pytest suites, and a lint/type gate built on ruff and mypy --strict. Trigger on "add type hints to this", "mypy is complaining", "convert th
Install
npx skills add https://github.com/nimadorostkar/Claude-Skills-collection/tree/main/skills/languages/python
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install nimadorostkar-claude-skills-collection@llmmart
git clone https://github.com/nimadorostkar/Claude-Skills-collection.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole nimadorostkar/claude-skills-collection collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Python
Purpose
Write production Python that is type-safe, async-first, and testable. This skill sets a single quality bar — annotated, linted, tested — and applies it consistently to new code and to code being modernized.
When to Use
- Writing new Python modules, packages, or services.
- Adding type coverage to an untyped or partially typed codebase.
- Converting blocking I/O to
asyncio, or debugging async behavior. - Standing up a pytest suite, fixtures, or parametrized tests.
- Modernizing Python 2-era or pre-3.10 idioms.
Capabilities
- Full type annotation, including generics,
Protocol,TypedDict, andParamSpec. - Async design: task groups, timeouts, cancellation, structured concurrency.
- Data modeling with
dataclasses,enum, and Pydantic when validation is needed. - Test authoring: fixtures, factories, mocking, property-based tests via Hypothesis.
- Tooling configuration:
pyproject.toml, ruff, mypy, uv or Poetry. - Profiling and hot-path optimization.
Inputs
- Source files or a package path.
- Target Python version (default: 3.12).
- Existing tooling config, if any.
- Runtime constraints: sync vs async, framework, deployment target.
Outputs
- Type-annotated source that passes
mypy --strict. - A pytest suite with meaningful assertions, not coverage padding.
- A
pyproject.tomlsection configuring ruff and mypy. - A short summary of behavioral changes when refactoring.
Workflow
- Survey — Read the module and its imports. Identify the runtime model (sync, async, threaded) and existing conventions. Do not fight established conventions without a reason.
- Model the data — Define dataclasses, enums, and protocols before writing logic. Type the boundaries first.
- Implement — Write the smallest correct version. Prefer standard library over dependencies.
- Test — Cover the contract and the failure modes, not the implementation details.
- Gate — Run
ruff check --fix,ruff format,mypy --strict,pytest. Fix each failure and re-run until all four are clean.
Best Practices
- Use
X | None, notOptional[X]. Uselist[str], notList[str]. - Never use a bare
except:. Catch the narrowest exception that can actually be raised. - Raise domain-specific exceptions; do not signal failure with
Nonereturn values. - Use
pathlib.Pathfor every filesystem path. - Never mutate a default argument. Use
field(default_factory=...). - Guard async code with explicit timeouts; an un-timed
awaiton a network call is a latency bug waiting to happen. - Log with the
loggingmodule and structured extras — neverprintin library code.
Examples
Typed, async, cancellation-safe fetch:
import asyncio
from dataclasses import dataclass
import httpx
@dataclass(frozen=True, slots=True)
class Quote:
symbol: str
price: float
class QuoteUnavailable(Exception):
"""Raised when the upstream cannot serve a quote."""
async def fetch_quotes(symbols: list[str], *, timeout: float = 5.0) -> list[Quote]:
async with httpx.AsyncClient(timeout=timeout) as client:
async with asyncio.TaskGroup() as tg:
tasks = {s: tg.create_task(client.get(f"/quote/{s}")) for s in symbols}
quotes: list[Quote] = []
for symbol, task in tasks.items():
response = task.result()
if response.status_code != 200:
raise QuoteUnavailable(symbol)
quotes.append(Quote(symbol=symbol, price=response.json()["price"]))
return quotes
Test that covers the contract and the failure:
import pytest
@pytest.mark.asyncio
async def test_fetch_quotes_raises_on_upstream_error(mock_client):
mock_client.get.return_value.status_code = 503
with pytest.raises(QuoteUnavailable, match="AAPL"):
await fetch_quotes(["AAPL"])
Notes
TaskGrouprequires Python 3.11+. On 3.10, useasyncio.gather(..., return_exceptions=True)and re-raise explicitly.mypy --stricton a large legacy codebase is a project, not a task. Enable it per-module withdisallow_untyped_defsand expand the surface gradually.- Prefer
uvfor new projects; it is materially faster than Poetry and pip for resolution and installs.
Files (claude-skills-collection)
-
SKILL.md 4.7 KB
--- name: python description: Use when writing, reviewing, or modernizing Python 3.11+ code. Produces fully type-annotated modules, async I/O, dataclasses and protocols, pytest suites, and a lint/type gate built on ruff and mypy --strict. Trigger on "add type hints to this", "mypy is complaining", "convert this to asyncio", "set up pytest for this project". Do not use for FastAPI app structure — see the fastapi skill; for dataframe work, see the pandas skill. metadata: category: languages version: 1.0.0 tags: [python, typing, async, pytest, mypy, ruff] --- # Python ## Purpose Write production Python that is type-safe, async-first, and testable. This skill sets a single quality bar — annotated, linted, tested — and applies it consistently to new code and to code being modernized. ## When to Use - Writing new Python modules, packages, or services. - Adding type coverage to an untyped or partially typed codebase. - Converting blocking I/O to `asyncio`, or debugging async behavior. - Standing up a pytest suite, fixtures, or parametrized tests. - Modernizing Python 2-era or pre-3.10 idioms. ## Capabilities - Full type annotation, including generics, `Protocol`, `TypedDict`, and `ParamSpec`. - Async design: task groups, timeouts, cancellation, structured concurrency. - Data modeling with `dataclasses`, `enum`, and Pydantic when validation is needed. - Test authoring: fixtures, factories, mocking, property-based tests via Hypothesis. - Tooling configuration: `pyproject.toml`, ruff, mypy, uv or Poetry. - Profiling and hot-path optimization. ## Inputs - Source files or a package path. - Target Python version (default: 3.12). - Existing tooling config, if any. - Runtime constraints: sync vs async, framework, deployment target. ## Outputs - Type-annotated source that passes `mypy --strict`. - A pytest suite with meaningful assertions, not coverage padding. - A `pyproject.toml` section configuring ruff and mypy. - A short summary of behavioral changes when refactoring. ## Workflow 1. **Survey** — Read the module and its imports. Identify the runtime model (sync, async, threaded) and existing conventions. Do not fight established conventions without a reason. 2. **Model the data** — Define dataclasses, enums, and protocols before writing logic. Type the boundaries first. 3. **Implement** — Write the smallest correct version. Prefer standard library over dependencies. 4. **Test** — Cover the contract and the failure modes, not the implementation details. 5. **Gate** — Run `ruff check --fix`, `ruff format`, `mypy --strict`, `pytest`. Fix each failure and re-run until all four are clean. ## Best Practices - Use `X | None`, not `Optional[X]`. Use `list[str]`, not `List[str]`. - Never use a bare `except:`. Catch the narrowest exception that can actually be raised. - Raise domain-specific exceptions; do not signal failure with `None` return values. - Use `pathlib.Path` for every filesystem path. - Never mutate a default argument. Use `field(default_factory=...)`. - Guard async code with explicit timeouts; an un-timed `await` on a network call is a latency bug waiting to happen. - Log with the `logging` module and structured extras — never `print` in library code. ## Examples **Typed, async, cancellation-safe fetch:** ```python import asyncio from dataclasses import dataclass import httpx @dataclass(frozen=True, slots=True) class Quote: symbol: str price: float class QuoteUnavailable(Exception): """Raised when the upstream cannot serve a quote.""" async def fetch_quotes(symbols: list[str], *, timeout: float = 5.0) -> list[Quote]: async with httpx.AsyncClient(timeout=timeout) as client: async with asyncio.TaskGroup() as tg: tasks = {s: tg.create_task(client.get(f"/quote/{s}")) for s in symbols} quotes: list[Quote] = [] for symbol, task in tasks.items(): response = task.result() if response.status_code != 200: raise QuoteUnavailable(symbol) quotes.append(Quote(symbol=symbol, price=response.json()["price"])) return quotes ``` **Test that covers the contract and the failure:** ```python import pytest @pytest.mark.asyncio async def test_fetch_quotes_raises_on_upstream_error(mock_client): mock_client.get.return_value.status_code = 503 with pytest.raises(QuoteUnavailable, match="AAPL"): await fetch_quotes(["AAPL"]) ``` ## Notes - `TaskGroup` requires Python 3.11+. On 3.10, use `asyncio.gather(..., return_exceptions=True)` and re-raise explicitly. - `mypy --strict` on a large legacy codebase is a project, not a task. Enable it per-module with `disallow_untyped_defs` and expand the surface gradually. - Prefer `uv` for new projects; it is materially faster than Poetry and pip for resolution and installs.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.