Claude Skill

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

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download nimadorostkar-claude-skills-collection-skills_languages_python-1691932.zip · 2 KB

Install

skills CLI npx skills add https://github.com/nimadorostkar/Claude-Skills-collection/tree/main/skills/languages/python
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install nimadorostkar-claude-skills-collection@llmmart
Git 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, 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:

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

  • 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.
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.

No comments yet.

Reviews (0)

No reviews yet.