plex-playlist/backend/pyproject.toml

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

[dependency-groups]
dev = [
  "ruff==0.14.1",
  "pyright==1.1.410",
  "pydoclint==0.8.3",
  "pytest==8.4.2",
  "pytest-asyncio==1.2.0",
  "pytest-cov==7.0.0",
  "typeguard==4.4.4",
  "httpx==0.28.1",  # For testing async HTTP calls
  "pytest-mock==3.15.1",
  # File format and linting tools
  "pre-commit==4.3.0",  # For running pre-commit hooks in CI
  "pyyaml==6.0.3",
  "yamllint==1.37.1",
  "toml-sort==0.24.3",
  "language-formatters-pre-commit-hooks==2.15.0",  # For pretty-format-toml
  "xdoctest==1.3.0",  # For doctest support
  "poethepoet==0.41.0"  # Task runner for unified development workflows
]

[project]
authors = [{name = "DarkHelm", email = "darkhelm@darkhelm.org"}]
classifiers = [
  "Development Status :: 3 - Alpha",
  "Intended Audience :: Developers",
  "License :: OSI Approved :: MIT License",
  "Programming Language :: Python :: 3",
  "Programming Language :: Python :: 3.14"
]
dependencies = [
  "fastapi==0.120.2",
  "sqlalchemy==2.0.44",
  "psycopg[binary]==3.2.12",
  "uvicorn==0.38.0"
]
description = "Backend service for Plex playlist management"
keywords = ["plex", "playlist", "media", "management"]
license = "MIT"
name = "plex-playlist-backend"
readme = "../README.md"
requires-python = ">=3.14"
version = "0.1.0"

[tool.coverage]

[tool.coverage.report]
exclude_lines = [
  "pragma: no cover",
  "def __repr__",
  "raise AssertionError",
  "raise NotImplementedError",
  "if __name__ == .__main__.:",
  "if TYPE_CHECKING:"
]

[tool.coverage.run]
omit = [
  "*/tests/*",
  "*/venv/*",
  "*/.venv/*",
  "*/node_modules/*",
  "*/migrations/*"
]
source = ["src"]

[tool.hatch.build]
include = [
  "src/backend/**/*.py",
  "src/backend/py.typed"
]

[tool.hatch.build.targets.wheel]
packages = ["src/backend"]

[tool.hatch.version]
path = "src/backend/__init__.py"

[tool.poe]

[tool.poe.tasks]
build-cicd = {shell = "./scripts/build-cicd-local.sh", help = "Build both CI/CD images"}
# === Docker CI/CD Image Tasks ===
build-cicd-base = {shell = "./scripts/build-cicd-local.sh --base-only", help = "Build CI/CD base image only"}
build-cicd-complete = {shell = "./scripts/build-cicd-local.sh --complete-only", help = "Build CI/CD complete image only"}
build-cicd-force = {shell = "./scripts/build-cicd-local.sh --force", help = "Force rebuild CI/CD images"}
build-if-dockerfile-changed = {shell = "if git diff --quiet HEAD~1 Dockerfile.cicd-base Dockerfile.cicd; then echo 'No Dockerfile changes, skipping build'; else poe build-cicd; fi", help = "Only build CI/CD images if Dockerfiles changed"}
# === Local CI Simulation ===
ci-format-check = [
  {shell = "cd backend && uv run ruff format --check ."},
  {shell = "cd frontend && yarn prettier --check src/"}
]
ci-full = ["ci-format-check", "lint", "type-check", "test-all", "docs-backend"]
ci-quick = ["ci-format-check", "lint", "type-check"]
# === Utility Tasks ===
clean = [
  {shell = "cd backend && find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true"},
  {shell = "cd backend && find . -name '*.pyc' -delete 2>/dev/null || true"},
  {shell = "cd frontend && rm -rf node_modules/.cache dist coverage 2>/dev/null || true"},
  {shell = "docker system prune -f"}
]
deps-check = [
  {shell = "cd backend && uv pip check"},
  {shell = "cd frontend && yarn audit"}
]
# === Dependency Management ===
deps-install = [
  {shell = "cd backend && uv sync --dev"},
  {shell = "cd frontend && yarn install"}
]
deps-update = [
  {shell = "cd backend && uv sync --upgrade --dev"},
  {shell = "cd frontend && yarn upgrade"}
]
# === Development Environment Tasks ===
dev = {shell = "docker compose -f compose.dev.yml up -d", help = "Start development environment"}
dev-down = {shell = "docker compose -f compose.dev.yml down", help = "Stop development environment"}
dev-logs = {shell = "docker compose -f compose.dev.yml logs -f", help = "Follow development environment logs"}
dev-restart = {shell = "docker compose -f compose.dev.yml restart", help = "Restart development environment"}
# === Documentation Tasks ===
docs-backend = {shell = "cd backend && uv run xdoctest --module backend", help = "Run backend docstring tests"}
docs-check = {shell = "cd backend && uv run pydoclint --config=pyproject.toml src/", help = "Check docstring quality"}
format = ["format-backend", "format-frontend"]
# === Code Formatting Tasks ===
format-backend = {shell = "cd backend && uv run ruff format .", help = "Format backend Python code"}
format-frontend = {shell = "cd frontend && yarn prettier --write src/", help = "Format frontend TypeScript code"}
lint = ["lint-backend", "lint-frontend"]
# === Linting Tasks ===
lint-backend = {shell = "cd backend && uv run ruff check .", help = "Lint backend Python code"}
lint-frontend = {shell = "cd frontend && yarn lint", help = "Lint frontend TypeScript code"}
# === Parallel Execution for Speed ===
lint-parallel = {shell = "poe lint-backend & poe lint-frontend & wait", help = "Run linting in parallel for speed"}
# === CI/CD Tasks ===
pre-commit-install = {shell = "pre-commit install --config ../.pre-commit-config.yaml", help = "Install pre-commit hooks"}
pre-commit-run = {shell = "pre-commit run --all-files --config ../.pre-commit-config.yaml", help = "Run all pre-commit hooks"}
pre-commit-update = {shell = "pre-commit autoupdate --config ../.pre-commit-config.yaml", help = "Update pre-commit hook versions"}
# === Quality Gates (Mimics CI Pipeline) ===
quality-gate = [
  {shell = "echo '🔍 Running quality gate checks...'"},
  "ci-format-check",
  "lint",
  "type-check",
  "test-unit",
  "docs-check",
  {shell = "echo '✅ All quality checks passed!'"}
]
reset = [
  "clean",
  {shell = "cd backend && rm -rf .venv 2>/dev/null || true"},
  {shell = "cd frontend && rm -rf node_modules 2>/dev/null || true"},
  "deps-install"
]
runner-diagnostics = {shell = "xonsh ./scripts/gitea-actions/collect_runner_diagnostics.xsh", help = "Collect recent runner, docker, and system diagnostics from all known runner hosts"}
runner-discover = {shell = "xonsh ./scripts/gitea-actions/discover-runners.xsh --batch", help = "Collect runner inventory, labels, and baseline health from all known runner hosts"}
# === Development Setup (New Developer Onboarding) ===
setup = [
  "deps-install",
  "pre-commit-install",
  "dev",
  {shell = "echo '✓ Development environment ready!'"},
  {shell = "echo '  - Frontend: http://localhost:3000'"},
  {shell = "echo '  - Backend API: http://localhost:8000'"},
  {shell = "echo '  - API Docs: http://localhost:8000/docs'"}
]
test-all = ["test-backend", "test-frontend", "test-integration"]
# === Testing Tasks ===
test-backend = {shell = "cd backend && uv run pytest -m 'not integration'", help = "Run backend unit tests (excludes integration marker)"}
test-backend-cov = {shell = "cd backend && uv run pytest -m 'not integration' --cov", help = "Run backend unit tests with coverage (excludes integration marker)"}
test-e2e = {shell = "bash ./scripts/run-ci-e2e-compose.sh", help = "Run E2E tests via compose against deployable runtime images"}
test-frontend = {shell = "cd frontend && yarn test", help = "Run frontend unit tests"}
test-frontend-cov = {shell = "cd frontend && yarn test:coverage", help = "Run frontend tests with coverage"}
test-full = ["test-backend-cov", "test-frontend-cov", "test-integration", "test-e2e"]
# === Smart Conditional Tasks ===
test-if-changed = {shell = "if git diff --quiet HEAD~1 backend/ frontend/; then echo 'No changes detected, skipping tests'; else poe test-unit; fi", help = "Only run tests if code has changed"}
test-integration = {shell = "bash ./scripts/run-ci-integration-compose.sh", help = "Run integration tests via compose against deployable runtime image"}
test-parallel = {shell = "poe test-backend & poe test-frontend & wait", help = "Run unit tests in parallel for speed"}
# === Comprehensive Testing ===
test-unit = ["test-backend", "test-frontend"]
type-check = ["type-check-backend", "type-check-frontend"]
# === Type Checking Tasks ===
type-check-backend = {shell = "cd backend && uv run pyright .", help = "Type check backend Python code"}
type-check-frontend = {shell = "cd frontend && yarn type-check", help = "Type check frontend TypeScript code"}
type-check-parallel = {shell = "poe type-check-backend & poe type-check-frontend & wait", help = "Run type checking in parallel for speed"}

# Pydoclint configuration for backend
[tool.pydoclint]
arg-type-hints-in-docstring = false
arg-type-hints-in-signature = true
check-return-types = false
check-yield-types = false
style = "google"

[tool.pytest.ini_options]
addopts = [
  "--strict-markers",
  "--strict-config",
  "--verbose",
  "--cov=backend",
  "--cov-report=term-missing:skip-covered",
  "--cov-report=html",
  "--cov-report=xml"
]
markers = [
  "slow: marks tests as slow (deselect with '-m \"not slow\"')",
  "integration: marks tests as integration tests"
]
python_classes = ["Test*"]
python_files = ["test_*.py", "*_test.py"]
python_functions = ["test_*"]
testpaths = ["tests"]

[tool.ruff]
line-length = 88
src = ["src"]
target-version = "py314"

[tool.ruff.lint]
ignore = [
  "E501",  # line too long, handled by black
  "B008",  # do not perform function calls in argument defaults
  "B903"  # Use `collections.abc.MutableMapping` instead of `typing.MutableMapping`
]
select = [
  "E",  # pycodestyle errors
  "W",  # pycodestyle warnings
  "F",  # pyflakes
  "I",  # isort
  "B",  # flake8-bugbear
  "C4",  # flake8-comprehensions
  "UP",  # pyupgrade
  "ARG",  # flake8-unused-arguments
  "SIM",  # flake8-simplify
  "TCH"  # flake8-type-checking
]

[tool.ruff.lint.isort]
known-first-party = ["backend"]
section-order = ["future", "standard-library", "third-party", "first-party", "local-folder"]

[tool.ruff.lint.per-file-ignores]
"tests/*" = ["ARG", "S101"]