Python Tooling Specialist

name: "Python Tooling Specialist"
slug: "tooling-python-generator"
description: "Generate Python project scaffolding with Poetry/pipenv, pytest configuration, type hints (mypy), linting (ruff/black), and packaging (setuptools/flit)."
capabilities:
- Project structure generation (library, application, CLI, data pipeline)
- Dependency management setup (Poetry, pipenv, pip-tools)
- Testing framework configuration (pytest, coverage, tox)
- Type checking setup (mypy, pyright)
- Linting and formatting (ruff, black, flake8, isort)
- Pre-commit hook configuration
- Packaging and distribution (PyPI, wheels, versioning)
inputs:
- project_type: "library | application | cli | data-pipeline (string)"
- dependency_manager: "poetry | pipenv | pip-tools (string)"
- python_version: "3.9 | 3.10 | 3.11 | 3.12 (string)"
- project_name: "Name of the project (string)"
outputs:
- project_structure: "Directory layout with all config files (JSON)"
- pyproject_toml: "Complete pyproject.toml configuration (TOML)"
- pre_commit_config: "Pre-commit hooks configuration (YAML)"
- makefile: "Common development commands (Makefile)"
keywords:
- python
- tooling
- poetry
- pytest
- mypy
- ruff
- black
- packaging
- pre-commit
version: "1.0.0"
owner: "cognitive-toolworks"
license: "MIT"
security: "Public; no secrets or PII; safe for open repositories"
links:
- https://python-poetry.org/docs/
- https://docs.pytest.org/
- https://mypy.readthedocs.io/
- https://docs.astral.sh/ruff/
- https://packaging.python.org/

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

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

3. Core pyproject.toml Generation

4. Project metadata (name, version, description, authors)
5. Python version constraint (from python_version input)
6. Basic tool configuration placeholders

7. License and repository links

8. Basic .gitignore

9. Python-specific ignores (pycache, *.pyc, .pytest_cache, .mypy_cache)
10. Environment files (.env, .venv)
11. 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 [email protected]"]

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

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

3. 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
2. Generate .pre-commit-config.yaml
3. Include: ruff, black, mypy, pytest

4. Add trailing-whitespace, end-of-file-fixer

5. 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
2. Configure [tool.poetry.build-system] or [build-system]
3. Add classifiers and keywords for PyPI
4. Set up MANIFEST.in for non-Python files

5. Configure package data inclusion

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

7. Poetry: poetry version integration
8. Semantic versioning enforcement

9. Git tag automation via Makefile/CI

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

11. Universal vs platform-specific wheels
12. Namespace package handling

13. C extension compilation (if applicable)

14. Entry Points and Scripts (for CLI projects)
    toml [tool.poetry.scripts] my-cli = "project_name.cli:main"

15. GitHub Actions CI/CD

16. Matrix testing across Python versions
17. Coverage reporting (codecov/coveralls)
18. Automated PyPI publishing on tag push

19. Security scanning (bandit, safety)

20. Documentation Setup

21. Sphinx configuration for library projects
22. MkDocs configuration for application projects
23. 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