AGENT SKILL

python-pro

Use when building Python 3.11+ applications requiring type safety, async programming, or robust error handling. Generates type-annotated Python code, configures mypy in strict mode, writes pytest test suites with fixtures and mocking, and validates code with black and ruff. Invoke for type hints, async/await patterns, dataclasses, dependency injection, logging configuration, and structured error handling.

License 许可
MIT
最近更新
2026-07-29
Stars
★ 0
Forks
0

01 前言 Front Matter

name
python-pro
license
MIT
metadata
{ "role": "specialist", "scope": "implementation", "author": "https://github.com/Jeffallan", "domain": "language", "version": "1.1.0", "triggers": "Python development, type hints, async Python, pytest, mypy, dataclasses, Python best practices, Pythonic code", "output-format": "code", "related-skills": "fastapi-expert, devops-engineer" }
description
Use when building Python 3.11+ applications requiring type safety, async programming, or robust error handling. Generates type-annotated Python code, configures mypy in strict mode, writes pytest test suites with fixtures and mocking, and validates code with black and ruff. Invoke for type hints, async/await patterns, dataclasses, dependency injection, logging configuration, and structured error handling.

03 SKILL.md 正文

Python Pro

Modern Python 3.11+ specialist focused on type-safe, async-first, production-ready code.

When to Use This Skill

  • Writing type-safe Python with complete type coverage
  • Implementing async/await patterns for I/O operations
  • Setting up pytest test suites with fixtures and mocking
  • Creating Pythonic code with comprehensions, generators, context managers
  • Building packages with Poetry and proper project structure
  • Performance optimization and profiling

Core Workflow

  1. Analyze codebase — Review structure, dependencies, type coverage, test suite
  2. Design interfaces — Define protocols, dataclasses, type aliases
  3. Implement — Write Pythonic code with full type hints and error handling
  4. Test — Create comprehensive pytest suite with >90% coverage
  5. Validate — Run mypy --strict, black, ruff
    • If mypy fails: fix type errors reported and re-run before proceeding
    • If tests fail: debug assertions, update fixtures, and iterate until green
    • If ruff/black reports issues: apply auto-fixes, then re-validate

Reference Guide

Load detailed guidance based on context:

Topic Reference Load When
Type System references/type-system.md Type hints, mypy, generics, Protocol
Async Patterns references/async-patterns.md async/await, asyncio, task groups
Standard Library references/standard-library.md pathlib, dataclasses, functools, itertools
Testing references/testing.md pytest, fixtures, mocking, parametrize
Packaging references/packaging.md poetry, pip, pyproject.toml, distribution

Constraints

MUST DO

  • Type hints for all function signatures and class attributes
  • PEP 8 compliance with black formatting
  • Comprehensive docstrings (Google style)
  • Test coverage exceeding 90% with pytest
  • Use X | None instead of Optional[X] (Python 3.10+)
  • Async/await for I/O-bound operations
  • Dataclasses over manual init methods
  • Context managers for resource handling

MUST NOT DO

  • Skip type annotations on public APIs
  • Use mutable default arguments
  • Mix sync and async code improperly
  • Ignore mypy errors in strict mode
  • Use bare except clauses
  • Hardcode secrets or configuration
  • Use deprecated stdlib modules (use pathlib not os.path)

Code Examples

Type-annotated function with error handling

from pathlib import Path

def read_config(path: Path) -> dict[str, str]:
    """Read configuration from a file.

    Args:
        path: Path to the configuration file.

    Returns:
        Parsed key-value configuration entries.

    Raises:
        FileNotFoundError: If the config file does not exist.
        ValueError: If a line cannot be parsed.
    """
    config: dict[str, str] = {}
    with path.open() as f:
        for line in f:
            key, _, value = line.partition("=")
            if not key.strip():
                raise ValueError(f"Invalid config line: {line!r}")
            config[key.strip()] = value.strip()
    return config

Dataclass with validation

from dataclasses import dataclass, field

@dataclass
class AppConfig:
    host: str
    port: int
    debug: bool = False
    allowed_origins: list[str] = field(default_factory=list)

    def __post_init__(self) -> None:
        if not (1 <= self.port <= 65535):
            raise ValueError(f"Invalid port: {self.port}")

Async pattern

import asyncio
import httpx

async def fetch_all(urls: list[str]) -> list[bytes]:
    """Fetch multiple URLs concurrently."""
    async with httpx.AsyncClient() as client:
        tasks = [client.get(url) for url in urls]
        responses = await asyncio.gather(*tasks)
        return [r.content for r in responses]

pytest fixture and parametrize

import pytest
from pathlib import Path

@pytest.fixture
def config_file(tmp_path: Path) -> Path:
    cfg = tmp_path / "config.txt"
    cfg.write_text("host=localhost\nport=8080\n")
    return cfg

@pytest.mark.parametrize("port,valid", [(8080, True), (0, False), (99999, False)])
def test_app_config_port_validation(port: int, valid: bool) -> None:
    if valid:
        AppConfig(host="localhost", port=port)
    else:
        with pytest.raises(ValueError):
            AppConfig(host="localhost", port=port)

mypy strict configuration (pyproject.toml)

[tool.mypy]
python_version = "3.11"
strict = true
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true

Clean mypy --strict output looks like:

Success: no issues found in 12 source files

Any reported error (e.g., error: Function is missing a return type annotation) must be resolved before the implementation is considered complete.

Output Templates

When implementing Python features, provide:

  1. Module file with complete type hints
  2. Test file with pytest fixtures
  3. Type checking confirmation (mypy --strict passes)
  4. Brief explanation of Pythonic patterns used

Knowledge Reference

Python 3.11+, typing module, mypy, pytest, black, ruff, dataclasses, async/await, asyncio, pathlib, functools, itertools, Poetry, Pydantic, contextlib, collections.abc, Protocol

Documentation

04 同仓库更多 Skills

Snuc1925
Snuc1925/SWE-AI-Agent

linear

Manage issues, projects & team workflows in Linear. Use when the user wants to read, create or updates tickets in Linear.

★ 0
Snuc1925
Snuc1925/SWE-AI-Agent

define-goal

Help the user define a concrete, measurable goal before starting work, especially when they ask to use the goal tool, create a goal, set an objective, clarify success criteria, or turn a fuzzy intention into a quantitative outcome. Use this skill for goal creation and goal refinement only; it does not manage durable snapshots, decision logs, or long-running execution artifacts.

★ 0
Snuc1925
Snuc1925/SWE-AI-Agent

webapp-testing

Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.

★ 0
Snuc1925
Snuc1925/SWE-AI-Agent

test-master

Generates test files, creates mocking strategies, analyzes code coverage, designs test architectures, and produces test plans and defect reports across functional, performance, and security testing disciplines. Use when writing unit tests, integration tests, or E2E tests; creating test strategies or automation frameworks; analyzing coverage gaps; performance testing with k6 or Artillery; security testing with OWASP methods; debugging flaky tests; or working on QA, regression, test automation, quality gates, shift-left testing, or test maintenance.

★ 0
Snuc1925
Snuc1925/SWE-AI-Agent

playwright

Use when the task requires automating a real browser from the terminal (navigation, form filling, snapshots, screenshots, data extraction, UI-flow debugging) via `playwright-cli` or the bundled wrapper script.

★ 0
Snuc1925
Snuc1925/SWE-AI-Agent

playwright-interactive

Persistent browser and Electron interaction through `js_repl` for fast iterative UI debugging.

★ 0