williamzujkowski/Python Tooling Specialist

Purpose & When-To-Use

Trigger conditions:

• Starting a new Python project requiring modern tooling
• Migrating legacy Python projects to contemporary best practices
• Standardizing tooling across multiple Python projects
• Setting up CI/CD pipelines with proper quality gates
• Onboarding developers to Python development workflows

Not for:

• Django/Flask-specific project templates (use framework CLIs)
• Jupyter notebook environments (use JupyterLab/conda)
• Simple scripts without dependencies or testing needs

Pre-Checks

Time normalization:

• Compute NOW_ET using NIST/time.gov semantics (America/New_York, ISO-8601)
• Use NOW_ET for all citation access dates

Input validation:

• project_type must be one of: library, application, cli, data-pipeline
• dependency_manager must be one of: poetry, pipenv, pip-tools
• python_version must be one of: 3.9, 3.10, 3.11, 3.12 (string format)
• project_name must be valid Python package name (lowercase, hyphens allowed)

Source freshness:

• Poetry docs must be accessible accessed 2025-10-26T02:31:27-04:00
• pytest docs must be accessible accessed 2025-10-26T02:31:27-04:00
• mypy docs must be accessible accessed 2025-10-26T02:31:27-04:00
• Ruff docs must be accessible accessed 2025-10-26T02:31:27-04:00

Procedure

T1: Basic Project Structure (≤2k tokens)

Fast path for common cases:

1. Directory Layout Generation

• Create standard Python project structure:

project_name/ src/project_name/ # for library/cli __init__.py py.typed # PEP 561 marker project_name/ # for application/data-pipeline __init__.py tests/ __init__.py conftest.py docs/ .gitignore README.md pyproject.toml

1. Core pyproject.toml Generation

• Project metadata (name, version, description, authors)
• Python version constraint (from python_version input)
• Basic tool configuration placeholders
• License and repository links

1. Basic .gitignore

• Python-specific ignores (__pycache__, .pyc, .pytest_cache, .mypy_cache)
• Environment files (.env, .venv)
• Build artifacts (dist/, build/, .egg-info)

Decision: If only basic scaffolding needed → STOP at T1; otherwise proceed to T2.

T2: Full Tooling Setup (≤6k tokens)

Extended configuration with all tools:

1. Dependency Manager Configuration

Poetry (pyproject.toml) accessed 2025-10-26T02:31:27-04:00 toml tool.poetry] name = "project-name" version = "0.1.0" description = "" authors = "Your Name <you@example.com>"]

tool.poetry.dependencies] python = "^3.11"

tool.poetry.group.dev.dependencies] pytest = "^7.4.0" pytest-cov = "^4.1.0" mypy = "^1.5.0" ruff = "^0.1.0" black = "^23.9.0"

pipenv (Pipfile) accessed 2025-10-26T02:31:27-04:00

• Generate Pipfile with dev/prod separation
• Configure pipenv scripts for common tasks

pip-tools (requirements.in) accessed 2025-10-26T02:31:27-04:00

• Create requirements.in and requirements-dev.in
• Add Makefile targets for pip-compile

1. Testing Configuration (pytest) accessed 2025-10-26T02:31:27-04:00

toml [tool.pytest.ini_options] minversion = "7.0" addopts = "-ra -q --strict-markers --cov=src" testpaths = ["tests"] pythonpath = ["src"] markers = [ "slow: marks tests as slow", "integration: marks tests as integration tests", ]

1. Type Checking (mypy) accessed 2025-10-26T02:31:27-04:00

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

1. Linting and Formatting

Ruff (all-in-one linter/formatter) accessed 2025-10-26T02:31:27-04:00 toml [tool.ruff] target-version = "py311" line-length = 100 select = ["E", "F", "I", "N", "W", "UP"] ignore = ["E501"]

Black (code formatter) accessed 2025-10-26T02:31:27-04:00 toml [tool.black] line-length = 100 target-version = ['py311']

1. Pre-commit Hooks accessed 2025-10-26T02:31:27-04:00

• Generate .pre-commit-config.yaml
• Include: ruff, black, mypy, pytest
• Add trailing-whitespace, end-of-file-fixer

1. Makefile for Common Commands

makefile .PHONY: test lint format typecheck install

install: poetry install

test: pytest

lint: ruff check .

format: black . ruff check --fix .

typecheck: mypy src

T3: Packaging and Distribution (≤12k tokens)

Deep configuration for publishable packages:

1. PyPI Publishing Setup accessed 2025-10-26T02:31:27-04:00

• Configure [tool.poetry.build-system] or [build-system]
• Add classifiers and keywords for PyPI
• Set up MANIFEST.in for non-Python files
• Configure package data inclusion

1. Versioning Strategy accessed 2025-10-26T02:31:27-04:00

• Poetry: poetry version integration
• Semantic versioning enforcement
• Git tag automation via Makefile/CI

1. Wheel Building Configuration accessed 2025-10-26T02:31:27-04:00

• Universal vs platform-specific wheels
• Namespace package handling
• C extension compilation (if applicable)

1. Entry Points and Scripts (for CLI projects)

toml [tool.poetry.scripts] my-cli = "project_name.cli:main"

1. GitHub Actions CI/CD

• Matrix testing across Python versions
• Coverage reporting (codecov/coveralls)
• Automated PyPI publishing on tag push
• Security scanning (bandit, safety)

1. Documentation Setup

• Sphinx configuration for library projects
• MkDocs configuration for application projects
• Docstring style enforcement (pydocstyle)

Decision Rules

Dependency Manager Selection:

• Poetry: Best for libraries and packages destined for PyPI (default recommendation)
• pipenv: Good for applications with deployment focus (Heroku, Docker)
• pip-tools: Minimal overhead, best for simple projects or constrained environments

Project Type Structure:

• library: src-layout with src/package_name/, includes py.typed, strict mypy
• application: flat layout with package_name/, relaxed typing, focus on integration tests
• cli: src-layout with entry points, includes shell completion, argparse/click/typer
• data-pipeline: flat layout, includes Jupyter support, pandas/numpy stubs

Abort Conditions:

• Invalid project_name (contains uppercase, special chars) → error "Invalid package name"
• Unsupported python_version → error "Python version must be 3.9+"
• Conflicting configuration requests → error with suggested alternatives

Tool Version Selection:

• Use latest stable versions as of NOW_ET
• For libraries: pin dev dependencies, use caret ranges for runtime deps
• For applications: pin all dependencies for reproducibility

Output Contract

Schema (JSON):

json
{
  "project_name": "string",
  "project_type": "library | application | cli | data-pipeline",
  "python_version": "string",
  "dependency_manager": "poetry | pipenv | pip-tools",
  "structure": {
    "directories": ["string"],
    "files": {
      "path/to/file": "file content (string)"
    }
  },
  "commands": {
    "install": "string",
    "test": "string",
    "lint": "string",
    "format": "string",
    "publish": "string (optional)"
  },
  "next_steps": ["string"],
  "timestamp": "ISO-8601 string (NOW_ET)"
}

Required Fields:

• project_name, project_type, python_version, dependency_manager, structure, commands, next_steps, timestamp

File Contents:

• All generated files must be syntactically valid (TOML/YAML/Makefile)
• Include inline comments explaining non-obvious configuration choices
• Reference official documentation in comments

Examples

Quick Start: Python Library (35 lines)

python
# examples/library_example.py
from dataclasses import dataclass
from datetime import datetime

@dataclass(frozen=True)
class AnalysisResult:
    length: int
    word_count: int
    analyzed_at: datetime

class TextAnalyzer:
    def __init__(self) -> None:
        self._history: list[str] = []

    def analyze(self, text: str) -> AnalysisResult:
        if not text or not text.strip():
            raise ValueError("Text cannot be empty")
        self._history.append(text)
        word_count = len(text.split())
        return AnalysisResult(len(text), word_count, datetime.utcnow())

    def get_history(self) -> tuple[str, ...]:
        return tuple(self._history)

Additional Examples:

• CLI Tool: examples/cli_example.py (32 lines) - Click framework, file I/O, error handling
• FastAPI: examples/api_example.py (38 lines) - Pydantic models, async endpoints

Template Resources (see resources/)

• pyproject.toml: pyproject-library.toml / pyproject-cli.toml / pyproject-api.toml
• Testing: example_test.py - pytest with fixtures and parametrize
• Pre-commit: pre-commit-config.yaml - ruff, black, mypy hooks

Quality Gates

Token Budgets:

• T1: ≤2k tokens (basic structure + core pyproject.toml)
• T2: ≤6k tokens (full tooling: pytest, mypy, ruff, pre-commit, Makefile)
• T3: ≤12k tokens (packaging, versioning, CI/CD, documentation)

Safety:

• No credential generation or storage
• .gitignore always includes .env and credential files
• pre-commit hooks check for secrets (detect-secrets)

Auditability:

• All tool configurations cite official documentation
• Version constraints are explicit (no floating versions in examples)
• Generated files include generation timestamp and tool versions

Determinism:

• Same inputs → identical file structure and configuration
• Tool versions pinned to major.minor (e.g., "^1.5" for mypy)
• No randomness in file generation

Performance:

• T1 generation: <1 second
• T2 generation: <3 seconds (includes all configs)
• T3 generation: <5 seconds (includes CI/CD templates)

Resources

Official Documentation (accessed 2025-10-26T02:31:27-04:00):

1. Poetry Documentation - Dependency management and packaging
2. pytest Documentation - Testing framework
3. mypy Documentation - Static type checking
4. Ruff Documentation - Fast Python linter
5. Python Packaging User Guide - Official packaging guide
6. Black Documentation - Code formatter
7. pre-commit Documentation - Git hook framework

Tool Configurations:

• /resources/pyproject-templates/ - Complete pyproject.toml templates by project type
• /resources/pre-commit-configs/ - Pre-commit configurations for different tool combinations
• /resources/makefile-templates/ - Makefile templates for poetry/pipenv/pip-tools

Best Practices:

• Python Application Layouts - src vs flat layout
• PEP 517 - Build system interface
• PEP 518 - pyproject.toml specification
• PEP 621 - Project metadata in pyproject.toml

Community Resources:

• Hypermodern Python - Modern tooling guide
• Real Python Packaging Guide - PyPI publishing tutorial