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
     

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

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

   [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

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

   [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",
   ]
   

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

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

4. Linting and Formatting

   Ruff (all-in-one linter/formatter) accessed 2025-10-26T02:31:27-04:00

   [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

   [tool.black]
   line-length = 100
   target-version = ['py311']
   

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

6. Makefile for Common Commands

   .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

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

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

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

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

4. Entry Points and Scripts (for CLI projects)

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

5. GitHub Actions CI/CD

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

6. 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):

{
  "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)

# 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