pyproject.toml

# ============================================================
# pyproject.toml (Python project configuration)
# ============================================================

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

[project]
name = "se-manifest-schema" # Package distribution name (lowercase and dashes).
readme = "README.md"
requires-python = ">=3.14"
dynamic = ["version"] # WHY: Version is computed from git tags at build time (see [tool.hatch.version]).
description = "Canonical SE_MANIFEST.toml schema and validation for the Structural Explainability ecosystem."
license = { file = "LICENSE" }
authors = [
    { name = "Structural Explainability", email = "se@structural-explainability.org" },
]
classifiers = [
    "Development Status :: 4 - Beta",
    "Intended Audience :: Developers",
    "License :: OSI Approved :: MIT License",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.14",
    "Topic :: Software Development :: Libraries :: Python Modules",
    "Topic :: Software Development :: Quality Assurance",
    "Typing :: Typed",
]
keywords = [
    "structural-explainability",
    "manifest",
    "schema",
    "validation",
    "toml",
]
dependencies = []

[project.optional-dependencies]
# WHY: Optional dependency groups keep the core install clean and focused.
dev = [
    # REQ.DEV.DEPS: External packages used for linting, testing, type checking, etc.
    "build", # WHY: build tool required for packaging and publishing.
    "pre-commit",
    "pyright",
    "pytest",
    "pytest-cov",
    "ruff",
    "twine", # WHY: Required for artifact validation (twine check dist/*).
]

docs = [
    "mkdocstrings-python", # WHY: Required for API reference generation in documentation.
    "zensical",
]

[project.scripts]
se-manifest = "se_manifest_schema.cli:main"
# WHY: Single CLI entry point.

[project.urls]
Homepage = "https://github.com/structural-explainability/se-manifest-schema"
Repository = "https://github.com/structural-explainability/se-manifest-schema"
Documentation = "https://structural-explainability.github.io/se-manifest-schema/"
Issues = "https://github.com/structural-explainability/se-manifest-schema/issues"
Changelog = "https://github.com/structural-explainability/se-manifest-schema/blob/main/CHANGELOG.md"

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

# === PYRIGHT (TYPE CHECKING HELPS FIND COMMON ERRORS BEFORE THE CODE RUNS) ===

[tool.pyright]
# CUSTOM: Pyright configuration for static type checking.
# WHY: Strict type checking helps catch bugs early.
include = ["src", "tests"] # WHY: Type-check both source and tests.
extraPaths = ["src"] # WHY: Resolve imports relative to src/ for consistent behavior across environments.
exclude = ["**/node_modules", "**/.*", ".venv", "**/__pycache__", "dist", "build"]
pythonVersion = "3.14"
reportMissingTypeStubs = "none" # WHY: Avoid warnings from third-party libraries without type stubs.
reportPrivateUsage = "none" # WHY: Allow usage of private members (e.g., _version.py), common in Python projects.
typeCheckingMode = "strict" # strict | basic | off

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

[tool.pytest.ini_options]
# WHY: Consistent test discovery and coverage visibility.
minversion = "9.0"
testpaths = ["tests"]
addopts = "--cov=se_manifest_schema --cov-report=term-missing --cov-fail-under=90"

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

[tool.ruff]
# WHY: Fast linting and formatting in one tool.
exclude = [
    ".eggs",
    "*.egg-info",
    ".ruff_cache",
    ".venv",
    "__pycache__",
    "build",
    "dist",
    "site",
]
line-length = 88 # WHY: PEP 8 standard, wrap when possible.
preview = false # WHY: Stable features only; avoid preview features.
target-version = "py314" # WHY: match latest supported Python version.
unsafe-fixes = false # WHY: Avoid potentially unsafe automatic fixes.

[tool.ruff.format]
# WHY: Formatter choices should be stable to keep diffs small and predictable.
indent-style = "space" # See also .gitattributes for indent style.
line-ending = "auto" # Match existing files and let .gitattributes handle it.
quote-style = "preserve" # Preserve existing quote styles to minimize churn.

[tool.ruff.lint]
# WHY: Baseline + stricter categories:
select = [
    "E",  # Basic syntax and structural correctness
    "F",  # Undefined names and unused imports
    "W",  # Warnings that catch easy issues early
    "I",  # Deterministic import ordering
    "UP", # Modern Python constructs
    "B",  # Common bug patterns

    "PTH", # Prefer pathlib patterns
    "C4",  # Comprehension correctness and clarity
    "SIM", # Simplify obvious complexity
    "RET", # Return practices

    "D", # Docstring standards (see convention below)
    "S", # Security checks (with deliberate exceptions)
]
ignore = [
    "E501", # line length handled by formatter
    "D203", # conflicts with D211
    "D213", # conflicts with D212 (Google standard summary placement)
    "S101", # allow assert (tests + internal invariants)
]

[tool.ruff.lint.isort]
# WHY: Ordering imports helps keep code diffs (differences) readable.
force-sort-within-sections = true

# === PER-FILE IGNORES (DEPENDS ON DOCSTRING POLICY) ===

[tool.ruff.lint.per-file-ignores]
# WHY: Some files must not be auto-modified.
"src/**/__init__.py" = ["F401"]     # Allow re-export patterns
"src/**/_version.py" = ["ALL"]      # Auto-generated file (do not lint)
"tests/**/*.py" = ["D", "B018", "B011", "S101"]
"src/**/py.typed" = ["ALL"]

# === CHOOSE PROJECT DOC STYLE ===

[tool.ruff.lint.pydocstyle]
# REQ: Google style is the project-wide docstring convention.
convention = "google"   # ALT: "numpy" choose one, never mix.

# ============================================================
# SECTION 3: BUILD SYSTEM (boilerplate; CUSTOM src/ agreement)
# ============================================================
#
# REQ.PROJECT: A build system MUST be declared for package discovery and publishing.
# REQ.STRUCTURE: All importable code MUST live under src/.
# WHY src/ layout: Prevents accidental imports from the repo root;
# ensures consistent behavior across IDEs, tests, CI, and PyPI.

[build-system]
build-backend = "hatchling.build"
requires = ["hatchling", "hatch-vcs"]

[tool.hatch.build.hooks.vcs]
# WHY: Writes computed version into src/*/_version.py at build time.
# CUSTOM: Must match src/ folders.
version-file = "src/se_manifest_schema/_version.py"

[tool.hatch.build.targets.sdist]
include = [
  "manifest-schema.toml",
  "src/se_manifest_schema",
  "README.md",
  "LICENSE",
  "pyproject.toml",
]

[tool.hatch.build.targets.wheel]
# CUSTOM: Must match src/ folders.
packages = ["src/se_manifest_schema"]

[tool.hatch.build.targets.wheel.force-include]
"manifest-schema.toml" = "se_manifest_schema/manifest-schema.toml"
# WHY: Include manifest-schema.toml in the package for runtime access to the schema definition.
# Repo source of truth: (root) manifest-schema.toml
# Installed package runtime artifact: se_manifest_schema/manifest-schema.toml
# Take the single source of truth at repo root.
# Place it inside the wheel package at se_manifest_schema/manifest-schema.toml.

[tool.hatch.version]
# Used when no git tags present (fresh clone, CI). Keep in sync with CITATION.cff.
fallback-version = "0.4.0"
# WHY: Version derived from git tags at build time.
source = "vcs"
# WHY: Allow hatch-vcs to find the Git root when built from a subdirectory,
# temporary build directory, or isolated build env.
search_parent_directories = true
tag-pattern = "^(?:v)?(?P<version>\\d+\\.\\d+\\.\\d+)$"