Python Development Skill

Comprehensive guide to modern Python development covering conventions, testing, tooling, security, performance, and ecosystem best practices (2024-2025 standards).

Tier 2 Quick Start

For multi-file projects, team collaboration, and maintained code:

# Install Python 3.12 and uv (see Installation guides)
# Windows: winget install Python.Python.3.12 && winget install astral-sh.uv
# macOS: brew install python@3.13 uv
# Linux: apt install python3.13 && curl -LsSf https://astral.sh/uv/install.sh | sh

# Create new project with modern structure
uv init my-project
cd my-project

# Add dependencies
uv add requests httpx pydantic

# Add development dependencies
uv add --dev pytest pytest-cov ruff mypy

# Set up code quality (create pyproject.toml config - see assets/pyproject-toml-template.toml)
# Configure Ruff, mypy, pytest

# Write tests (pytest)
# tests/test_example.py - mirror src/ structure

# Run quality checks
uv run ruff check .          # Linting
uv run ruff format .         # Formatting
uv run mypy .                # Type checking
uv run pytest                # Run tests
uv run pytest --cov          # With coverage

When to Use This Skill

Invoke this skill when you need guidance on:

• Installation & Setup: Installing Python 3.12/3.14, uv, setting up development environment
• Code Style: Following PEP-8, configuring Ruff/Black, naming conventions
• Project Structure: Organizing code with src/ layout, imports, package structure
• Dependency Management: Using uv, Poetry, pip, virtual environments, pyproject.toml
• Testing: Writing pytest tests, fixtures, parametrization, coverage, mocking
• Type Hints: Modern typing patterns, mypy configuration, protocols, generics
• Code Quality: Setting up Ruff, mypy, Bandit, pre-commit hooks, CI/CD
• Async Programming: asyncio patterns, async/await, TaskGroup, structured concurrency
• Security: OWASP best practices, input validation, dependency scanning
• Performance: Profiling, optimization patterns, Cython
• Packaging: pyproject.toml, PyPI publishing, versioning, distribution
• Common Libraries: Standard library essentials, ecosystem overview
• Documentation: Docstrings (PEP-257), Sphinx, documentation generation

Overview

This skill provides modern Python development guidance aligned with current best practices (2024-2025):

Core Standards:

• Style: PEP-8 (enforced via Ruff)
• Type Hints: PEP-484, PEP-526, modern syntax (PEP-604: str | None)
• Packaging: PEP-517, PEP-518 (pyproject.toml)
• Docstrings: PEP-257
• Testing: pytest (industry standard)
• Dependency Management: uv (fastest) or Poetry (feature-rich)

Modern Tooling (2024-2025):

• Linter/Formatter: Ruff (replaces flake8, isort, optionally Black)
• Type Checker: mypy with strict mode
• Test Framework: pytest
• Dependency Manager: uv or Poetry
• Security Scanner: Bandit + pip-audit
• Project Config: pyproject.toml (universal)

Project Structure:

• src/ layout (modern standard, not flat layout)
• Absolute imports preferred over relative
• Tests mirror src/ structure
• pyproject.toml for all configuration

Official Sources: All guidance backed by official Python documentation, PEPs, and tool documentation:

• docs.python.org
• peps.python.org
• docs.astral.sh/ruff
• docs.astral.sh/uv
• mypy-lang.org
• docs.pytest.org

Quick Tier Selection

Choose your complexity level:

🎯 Tier 1: Minimal (Simple Scripts)

→ Single-file utilities, converting scripts, one-off automation → Just Python code - no tooling overhead → Jump to Minimal Guidance

📦 Tier 2: Standard (Organized Projects)

→ Multi-file modules, team projects, maintained code → Modern project structure + testing → Jump to Standard Guidance

🚀 Tier 3: Full (Production Systems)

→ PyPI packages, enterprise systems, production deployments → Complete tooling ecosystem → Jump to Full Guidance

Not sure? Default to Tier 2 (Standard) - it covers most use cases.

---

Tier 1: Minimal (Simple Scripts)

For: Single-file utilities, script conversions, and simple automation.

Setup

Just Python 3.12+ - no additional tooling required:

• ✅ No uv, no virtual environment needed
• ✅ No pyproject.toml, no src/ layout
• ✅ Optional: Install Ruff for quick linting (pip install ruff)

Code Standards

Follow these simple principles:

• PEP-8 naming: snake_case for functions/variables, PascalCase for classes
• Type hints: Add for clarity (helps readers understand your code)
• Docstrings: Simple descriptions of what functions do
• pathlib: Use pathlib.Path for file operations (not os.path)
• Built-ins: Use Python's built-in json, datetime, sys modules

Example: Simple Logging Script

#!/usr/bin/env python3
"""Simple logging utility - converts event to JSON."""

import json
import sys
from datetime import datetime, timezone
from pathlib import Path


def log_event(event_name: str, data: dict) -> None:
    """
    Log an event to daily JSONL file.

    Args:
        event_name: Name of the event
        data: Event data to log
    """
    log_dir = Path(__file__).parent / "logs"
    log_dir.mkdir(exist_ok=True)

    now = datetime.now(timezone.utc)
    log_file = log_dir / f"{now:%Y-%m-%d}.jsonl"

    entry = {
        "timestamp": now.isoformat(),
        "event": event_name,
        "data": data
    }

    with open(log_file, "a", encoding="utf-8") as f:
        f.write(json.dumps(entry) + "\n")


if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("Usage: script.py <event_name>", file=sys.stderr)
        sys.exit(1)
    event_name = sys.argv[1]
    data = json.loads(sys.stdin.read())
    log_event(event_name, data)

Optional: Quick Linting

If you want to check your code style:

# Install Ruff (optional)
pip install ruff

# Check code
ruff check script.py

# Format code
ruff format script.py

When to Upgrade to Tier 2

Consider upgrading to Tier 2 (Standard) when:

• ✅ Script grows to 3+ files
• ✅ Multiple people working on code
• ✅ Need automated testing
• ✅ Managing external dependencies
• ✅ Code will be maintained long-term

---

Tier 2: Standard (Organized Projects)

For: Multi-file modules, team projects, and maintained code.

Modern Python project setup with proper structure, testing, and quality tools.

Installation

Install Python 3.12+ and uv (modern dependency manager). See platform-specific guides:

• Installation Overview - Concepts and version policy
• Windows Installation - WinGet, Python Launcher
• macOS Installation - Homebrew installation
• Linux Installation - apt/dnf or build from source

Project Setup and Organization

Conventions and Style - Follow PEP-8 with Ruff for linting and formatting:

• See Conventions and Style Guide

Project Structure - Use modern src/ layout for proper packaging:

• See Project Structure Guide

Dependency Management - Choose between uv (fastest), Poetry (feature-rich), or pip+venv:

• See Dependency Management Guide

Testing and Quality

Testing - Use pytest with fixtures, parametrization, and coverage:

• See Testing Methodology Guide

Type Hints - Modern typing with mypy, protocols, and generics:

• See Type Hints Guide

Code Quality - Set up Ruff, mypy, Bandit, and pre-commit hooks:

• See Code Quality Tools Guide

Advanced Development

Async Programming - asyncio patterns, TaskGroup, structured concurrency:

• See Async Patterns Guide

Security - OWASP best practices, input validation, secrets management:

• See Security Best Practices Guide

Performance - Profiling, optimization patterns, memory efficiency:

• See Performance Optimization Guide

Packaging - Publish to PyPI with pyproject.toml and semantic versioning:

• See Packaging and Distribution Guide

Libraries - Standard library essentials and ecosystem overview:

• See Common Libraries Guide

Documentation - PEP-257 docstrings, Sphinx, ReadTheDocs:

• See Docstrings and Documentation Guide

---

Tier 3: Full (Production Systems)

For: PyPI packages, enterprise systems, and production deployments.

Everything in Tier 2 (Standard) PLUS:

Security & Quality

• Security scanning: Bandit for code security, pip-audit for dependency vulnerabilities
• Pre-commit hooks: Automated checks before every commit
• Comprehensive type coverage: mypy strict mode across entire codebase
• Code coverage enforcement: Minimum coverage requirements in CI/CD

Distribution

• PyPI packaging: Build and publish Python packages to PyPI
• Semantic versioning: Follow semver for version management
• Binary distributions: Create wheels for faster installation
• Multi-platform support: Test and build for Windows/macOS/Linux

CI/CD

• GitHub Actions / GitLab CI: Automated testing on every push
• Multi-version testing: Test against Python 3.12, 3.13, 3.14
• Coverage tracking: Automated coverage reports and enforcement
• Release automation: Automatic PyPI publishing on tags

Documentation

• Sphinx: Generate API documentation from docstrings
• ReadTheDocs: Host documentation with versioning
• Comprehensive docstrings: Google or NumPy style for all public APIs
• Examples and tutorials: User-facing documentation with examples

Detailed Guides

See these reference files for comprehensive production guidance:

• Security Best Practices - OWASP, Bandit, pip-audit
• Packaging and Distribution - PyPI publishing, versioning
• Code Quality Tools - Pre-commit hooks, CI/CD setup
• Docstrings and Documentation - Sphinx, ReadTheDocs

---

Reference Files

All detailed guidance is in the references/ directory:

Installation:

• Installation Overview - Platform-independent concepts
• Windows Installation - Python + uv on Windows
• macOS Installation - Python + uv on macOS
• Linux Installation - Python + uv on Linux

Core Development:

• Conventions and Style - PEP-8, Ruff, Black, naming
• Project Structure - src/ layout, imports, organization
• Dependency Management - uv, Poetry, pip, venv
• Testing Methodology - pytest, fixtures, coverage
• Type Hints - Modern typing, mypy, protocols
• Code Quality Tools - Ruff, mypy, Bandit setup

Advanced Topics:

• Async Patterns - asyncio, TaskGroup, structured concurrency
• Security Best Practices - OWASP, validation, scanning
• Performance Optimization - Profiling, patterns, Cython
• Packaging and Distribution - pyproject.toml, PyPI, versioning
• Common Libraries - Standard library + ecosystem essentials
• Docstrings and Documentation - PEP-257, Sphinx

Assets

Template Files:

• pyproject.toml Template - Modern project configuration template

Testing and Evaluation

This skill includes formal evaluation scenarios to validate effectiveness:

• See Skill Evaluation Scenarios for test cases covering:
  • Minimal Tier (simple scripts)
  • Standard Tier (new projects, code quality tools)
  • Full Tier (production systems)
  • Alternative workflows (Poetry vs uv)
  • Success criteria and testing methodology

Related Skills

• git-commit: Git commit workflow (complements Python project workflow)
• git:git-config: Git configuration (Python projects use Git)
• code-quality:markdown-linting: Markdown linting via plugin (Python projects have READMEs)

Version History

• 1.1.2 (2025-11-25): Comprehensive improvements
  • Fixed deprecated datetime.utcnow() in example code (use datetime.now(timezone.utc))
  • Added Python 3.13 coverage (was missing between 3.12 and 3.14)
  • Updated PEP URLs to modern format (peps.python.org instead of python.org/dev/peps/)
  • Added UTF-8 encoding to file open in example code
  • Added error handling for missing CLI arguments in example
• 1.1.1 (2025-11-25): Version audit update
  • Updated tool version references (Ruff 0.14.x, mypy 1.18.x, pytest 9.x)
  • Verified all reference file links exist and are correct
  • Validated YAML frontmatter against official requirements
• 1.1.0 (2025-11-18): Adaptive tiered guidance
  • Added three-tier complexity system (Minimal/Standard/Full)
  • Tier 1: Minimal guidance for simple scripts (no tooling overhead)
  • Tier 2: Standard guidance for organized projects (original Quick Start)
  • Tier 3: Full guidance for production systems (comprehensive tooling)
  • Context-aware skill automatically selects appropriate tier based on query
  • Prevents "big bang" overengineering for simple scenarios
• 1.0.0 (2025-11-17): Initial release
  • Comprehensive modern Python guidance (2024-2025 standards)
  • Migrated installation docs from docs/python/
  • Added 12 detailed reference files
  • Modern tooling: Ruff, uv, pytest, mypy
  • pyproject.toml template

Official Documentation

Python:

• Official Python Documentation: https://docs.python.org/
• Python 3.12 What's New: https://docs.python.org/3.12/whatsnew/3.12.html
• Python 3.13 What's New: https://docs.python.org/3.13/whatsnew/3.13.html
• Python 3.14 What's New: https://docs.python.org/3.14/whatsnew/3.14.html
• Python Enhancement Proposals (PEPs): https://peps.python.org/

Tools:

• uv Documentation: https://docs.astral.sh/uv/
• Ruff Documentation: https://docs.astral.sh/ruff/
• mypy Documentation: https://mypy-lang.org/
• pytest Documentation: https://docs.pytest.org/
• Poetry Documentation: https://python-poetry.org/docs/

PEPs (Python Enhancement Proposals):

• PEP-8 (Style Guide): https://peps.python.org/pep-0008/
• PEP-257 (Docstring Conventions): https://peps.python.org/pep-0257/
• PEP-484 (Type Hints): https://peps.python.org/pep-0484/
• PEP-517 (Build System): https://peps.python.org/pep-0517/
• PEP-518 (pyproject.toml): https://peps.python.org/pep-0518/
• PEP-604 (Union Types with |): https://peps.python.org/pep-0604/

Last Updated

Date: 2025-11-28 Model: claude-opus-4-5-20251101