pyproject.toml

# ============================================================
# pyproject.toml (ALL-PY-SRC-REPOS)
# ============================================================
# Updated: 2026-08-23
# REQ: Python src/ projects MUST include pyproject.toml as the single source of truth.
# WHY: Centralizes project configuration.
# CUSTOM: If you change the repository name, update the project identity and build tool src folders accordingly.
# CUSTOM: This project keeps dependencies current; in production, package versions are pinned explicitly.

# ============================================================
# SECTION 1: PROJECT IDENTITY (name, version, CUSTOM dependencies)
# ============================================================

[project]
name = "professional-python-project-explainer" # CUSTOM: Package distribution name (use lowercase and dashes).
readme = "README.md"
requires-python = ">=3.14"
version = "0.1.0"

dependencies = [
    "marimo>=0.19.7",
]

[dependency-groups]
# WHY: Dependency groups provide tooling used to develop, document,
# and interact with the project without making those tools
# runtime dependencies of the analytical code.

dev = [
    # REQ.DEV.DEPS: External packages used for linting, testing, type checking, etc.
    "pre-commit", # WHY: Pre-commit hooks for consistent formatting and linting.
    "pytest",     # WHY: Test framework for unit and integration tests.
    "pytest-cov", # WHY: Test coverage reporting for quality metrics and CI gating.
    "ruff",       # WHY: Fast linting and formatting for Python code.
    "ty",         # WHY: Type checking for static analysis and type safety.
]

# ============================================================
# SECTION 2: TOOL CONFIGURATION (Professional basics)
# ============================================================

# === MARIMO REACTIVE NOTEBOOKS ===

[tool.marimo.save]
autosave = "after_delay"
autosave_delay = 1000
format_on_save = true

[tool.marimo.package_management]
manager = "uv"

[tool.marimo.runtime]
pythonpath = ["./src"]

# === WITH MARIMO, MUST ADD THIS FOR TY (STATIC TYPE CHECKING) ===

[tool.ty.environment]
root = ["./src"] # WHY: Specify the root directory for static type checking.

# === PYTEST (VERIFY LOGIC) ===

[tool.pytest.ini_options]
# WHY: Consistent test discovery and coverage visibility.
pythonpath = ["src"] # add for marimo apps
minversion = "9.0"
testpaths = ["tests"]
addopts = "--cov=src --cov-fail-under=40 --cov-report=term-missing"
filterwarnings = [
    "ignore:FigureCanvasAgg is non-interactive, and thus cannot be shown:UserWarning",
]

# === RUFF (PYTHON FORMATTING AND LINTING) ===

[tool.ruff.lint] # WHY: Evolve with Ruff's defaults; production might pin an explicit set.
extend-select = [
    # --- turn on for additional linting rules ---
    # "D",  # WHY: Require docstrings; VS Code helps generate them.
]

[tool.ruff.lint.isort] # WHY: Sort plain-import and from-import lines together within each section.
force-sort-within-sections = true

[tool.ruff.lint.per-file-ignores] # WHY: Some file types need lint exceptions.
"src/**/__init__.py" = ["F401"] # Allow re-export patterns.
"src/**/_version.py" = ["ALL"]  # Auto-generated file; do not lint.
"tests/**/*.py" = ["D", "B018"] # Tests need no docstrings; B018 is default-on.
"notebooks/**/*.py" = ["B018", "D", "PLR1711", "RUF059"]
"src/app.py" = ["B018", "D", "PLR1711", "RUF059"] # marimo

[tool.ruff.lint.pydocstyle] # WHY: Use Google docstring style when D is enabled.
convention = "google"

# === UV (PYTHON ENVIRONMENT AND DEPENDENCY MANAGEMENT) ===

[tool.uv]
# WHY: Install all dependency groups defined by this repository by default.
# OBS: This keeps the canonical `uv sync` command identical across project types
#      and ensures all repository features work after setup.
default-groups = "all"
package = false