pyproject.toml

# ============================================================
# pyproject.toml (Python project configuration)
# ============================================================
# Updated: 2026-10-11
#
# REQ: All Python src/ projects SHOULD include pyproject.toml.
# WHAT: Defines project identity, dependencies, and build configuration.
# WHY: Keeps Python project metadata and package requirements together.
# CUSTOM: Update project identity, dependencies, and package paths.

# ============================================================
# === SECTION: PROJECT IDENTITY ===
# ============================================================

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

# ============================================================
# === SECTION: PROJECT RUNTIME DEPENDENCIES ===
# ============================================================
# Add more as you enhance the project,
# then run `uv sync` to update the environment.

dependencies = [
    # CUSTOM: Add any external dependencies the project code requires.
    "marimo>=0.25.1",
]

# ============================================================
# === SECTION: DEVELOPMENT AND DOCUMENTATION DEPENDENCIES ===
# ============================================================
# These packages support developing, testing, and documenting the project.
# They are not required to execute the project code.

[dependency-groups]
# WHY: Development and documentation tools support maintaining, validating,
#      and documenting the project without becoming runtime dependencies.

dev = [
    # REQ.DEV.DEPS: Standard tools for Python development and validation.
    "pytest",     # WHY: Run automated tests.
    "pytest-cov", # WHY: Measure and report test coverage.
    "ruff",       # WHY: Lint and format Python code.
    "ty",         # WHY: Check Python types using static analysis.
]

docs = [
    # REQ.DOCS.DEPS: Standard tools for generating project documentation.
    "mkdocstrings[python]", # WHY: Generate API documentation from Python docstrings.
    "zensical",             # WHY: Build the project documentation website.
]

# ============================================================
# 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.


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

[tool.uv]
# WHY: Install all dependency groups with the canonical uv sync.
default-groups = "all"

# WHY: Allow time for newly published dependency releases to be evaluated.
exclude-newer = "7 days"

# ============================================================
# === SECTION: BUILD SYSTEM ===
# ============================================================
#
# WHAT: Defines how the project's Python package is built and installed.
# WHY: Hatchling enables uv to install the local src/ package so
#      Python modules and tests can import project code consistently.
# REQ: All importable project code MUST live under src/.
# CUSTOM: Match the package directory under src/ exactly.

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

[tool.hatch.build.targets.wheel]
packages = ["src"] # CUSTOM: Adjust as needed.