Python Project Setup

Python Project Setup

When to Use

Use this skill when:

• User asks to set up a new Python project from scratch
• User wants to know Python project structure conventions
• User asks about pyproject.toml, setup.py, or Python packaging
• User mentions virtual environments, dependency management, or lock files
• User asks about configuring mypy, ruff, or Python tooling for a new project
• User wants to create a distributable Python package or library
• User asks about src layout vs flat layout for Python

Do NOT use this skill when:

• The user is asking about Python language features or syntax → use python-idioms
• The user already has a project and wants to add testing → use python-testing-patterns
• The user wants to set up async patterns → use python-async-patterns
• The user is asking about data validation and modeling → use python-data-modeling
• The user wants to improve performance of existing code → use python-performance
• The user is asking about type annotations and generics → use python-type-system
• The user wants to handle errors and exceptions → use python-error-handling

Process

1. Assess the project context. Before generating any files, determine:

   • Is this a library/package (distributed via PyPI) or an application (deployed directly)?
     • If library: src layout is mandatory. Editable installs and packaging are critical.
     • If application: flat layout is acceptable. Focus on reproducibility and deployment.
   • Is this a solo project or team project?
     • If team: enforce pre-commit hooks, stricter linting, and type checking from day one.
     • If solo: still configure tooling but relax some rules for velocity.
   • What is the minimum Python version?
     • If 3.12+: use the new type statement syntax awareness. Enable latest mypy features.
     • If 3.10-3.11: structural pattern matching is available. Standard generics from __future__.
     • If 3.9 or below: avoid unless legacy constraint. Document why in pyproject.toml.

2. Choose the dependency management tool. Apply this decision tree:

   • If the team values fast installs and modern standards: use uv (Rust-based, 10-100x faster than pip, resolves dependencies deterministically, lockfile built-in).
   • If the project needs compatibility with existing CI/CD that only supports the standard Python installer: use pip-tools with requirements.in compiled to requirements.txt.
   • If the project is a library that needs flexible dependency ranges: still use uv or pip-tools, but define loose ranges in pyproject.toml [project.dependencies] and pin exact versions in lock files.
   • NEVER use requirements.txt alone without a lock mechanism. Version drift between developers is the number one Python project reliability problem.

3. Choose the project layout. Apply this decision tree:

   • If building a redistributable package: use src layout (src/package_name/). This prevents accidental imports from the working directory during testing.
   • If building a deployed application with no distribution: flat layout (package_name/ at root) is acceptable and simpler.
   • If building a monorepo with multiple packages: use src layout per package with a workspace definition.

4. Generate the project structure. Create the directory tree and all configuration files per the Output Format below. Every file must be generated - do not leave any configuration for the user to fill in manually.

5. Configure the type checker (mypy). Apply this decision tree:

   • Default: strict = true in [tool.mypy]. This enables all strict flags.
   • If integrating with third-party packages that lack type stubs: add per-module overrides with ignore_missing_imports = true for those specific packages only.
   • If the project uses Pydantic: add plugins = ["pydantic.mypy"] for model validation support.
   • ALWAYS include a py.typed marker file in the package directory for PEP 561 compliance.

6. Configure the linter and formatter (ruff). Apply this decision tree:

   • Use ruff for both linting AND formatting (replaces flake8, black, isort, pyflakes, and more).
   • Default rule set: select = ["E", "F", "W", "I", "N", "UP", "S", "B", "A", "C4", "DTZ", "T10", "ISC", "ICN", "PIE", "PT", "RSE", "RET", "SLF", "SIM", "TID", "TCH", "ARG", "PLC", "PLE", "PLW", "TRY", "FLY", "PERF", "RUF"]
   • If team is migrating from flake8/black: start with select = ["E", "F", "W", "I"] and expand incrementally.
   • Line length: 88 (ruff default, matches black) or 120 (if team prefers wider lines on modern monitors).

7. Configure pre-commit hooks (team projects only). Set up:

   • ruff check (lint)
   • ruff format (format)
   • mypy (type check)
   • pytest (optional, for fast test suites only - do not gate on slow integration tests)

8. Verify the setup. Confirm the following checks pass:

   • uv sync (or editable dev install) succeeds without errors
   • ruff check . passes with no violations
   • ruff format --check . reports no formatting changes needed
   • mypy . passes with zero errors
   • pytest executes successfully (even with minimal tests)

Output Format

{project-name}/
├── src/                          # Only for src layout
│   └── {package_name}/
│       ├── __init__.py
│       ├── py.typed              # PEP 561 marker
│       └── main.py               # Entry point (applications only)
├── tests/
│   ├── __init__.py
│   ├── conftest.py               # Shared fixtures
│   └── test_placeholder.py       # Initial test to verify setup
├── pyproject.toml                # Complete project configuration
├── .python-version               # Pin Python version (e.g., 3.12)
├── .gitignore                    # Python-specific gitignore
├── README.md                     # Project documentation
└── .pre-commit-config.yaml       # Pre-commit hooks (team projects)

pyproject.toml template:

[project]
name = "{project-name}"
version = "0.1.0"
description = "{Project description}"
requires-python = ">={min-python-version}"
license = "MIT"
authors = [
    { name = "{Author Name}", email = "{email}" },
]
dependencies = []

[project.optional-dependencies]
dev = [
    "pytest>=8.0",
    "pytest-cov>=5.0",
    "mypy>=1.10",
    "ruff>=0.5",
    "pre-commit>=3.7",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel]
packages = ["src/{package_name}"]

[tool.ruff]
target-version = "py{min-version-digits}"
line-length = 88

[tool.ruff.lint]
select = [
    "E", "F", "W", "I", "N", "UP", "S", "B", "A", "C4",
    "DTZ", "T10", "ISC", "ICN", "PIE", "PT", "RSE", "RET",
    "SLF", "SIM", "TID", "TCH", "ARG", "PLC", "PLE", "PLW",
    "TRY", "FLY", "PERF", "RUF",
]

[tool.ruff.lint.per-file-ignores]
"tests/**" = ["S101"]  # Allow assert in tests

[tool.mypy]
strict = true
warn_return_any = true
warn_unused_configs = true
plugins = []

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "-ra -q --strict-markers"

conftest.py template:

"""Shared test fixtures for {project-name}."""

import pytest


@pytest.fixture
def sample_data() -> dict[str, str]:
    """Provide sample data for tests. Customize per project."""
    return {"key": "value"}

.pre-commit-config.yaml template:

repos:
  - repo: local
    hooks:
      - id: ruff-check
        name: ruff-check
        entry: ruff check --fix
        language: system
        types: [python]
      - id: ruff-format
        name: ruff-format
        entry: ruff format
        language: system
        types: [python]
      - id: mypy
        name: mypy
        entry: mypy
        language: system
        types: [python]
        pass_filenames: false