pyproject.toml

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

[project]
name = "policyengine-api"
version = "5.7.0"
description = "PolicyEngine API"
readme = "README.md"
license = "AGPL-3.0-only"
authors = [
    { name = "PolicyEngine", email = "hello@policyengine.org" },
]
requires-python = ">=3.11"
classifiers = [
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
    "Programming Language :: Python :: 3.13",
    "Programming Language :: Python :: 3.14",
    "License :: OSI Approved :: GNU Affero General Public License v3",
]
dependencies = [
    "a2wsgi>=1.10,<2",
    "alembic>=1.14,<2",
    "assertpy",
    "click>=8,<9",
    "cloud-sql-python-connector",
    "faiss-cpu",
    "fastapi>=0.115,<1",
    "flask>=3,<4",
    "flask-cors>=5,<6",
    "Flask-Caching>=2,<3",
    "google-cloud-logging>=3,<4",
    "google-cloud-secret-manager>=2,<3",
    "gunicorn",
    "httpx>=0.27.0",
    "markupsafe>=3,<4",
    "microdf_python>=1.0.0",
    "openai",
    "packaging>=24,<27",
    "policyengine-observability[flask,google,httpx,otlp-grpc]>=3.0.3,<4",
    "policyengine_canada==0.96.3",
    "policyengine-ng==0.5.1",
    "policyengine-il==0.1.0",
    # The models extra pins Core, US, UK, and the SPM calculator to the exact
    # versions certified by this PolicyEngine bundle. Cloud Run installs the
    # complete frozen environment from uv.lock; the generic image installs
    # this requirement directly.
    "policyengine[models]==6.7.5",
    "pydantic",
    "pymysql",
    "python-dotenv",
    "redis",
    "rq",
    "sqlalchemy>=2,<3",
    "streamlit",
    "uvicorn[standard]>=0.32,<1",
    "werkzeug",
    "sqlmodel>=0.0.39,<0.1",
    "psycopg[binary]>=3.3,<4",
    "pyjwt[crypto]>=2.10,<3",
    "typing-extensions>=4.4,<5",
]

[project.optional-dependencies]
dev = [
    "build",
    "coverage",
    "mypy>=1.15,<2",
    "pytest",
    "pytest-snapshot",
    "pytest-timeout",
    "ruff>=0.9.0",
    "towncrier>=24.8.0",
]

[tool.hatch.build.targets.wheel]
packages = ["policyengine_api"]

[tool.hatch.metadata]
allow-direct-references = true

[tool.ruff]
# Directories with no __init__.py on purpose (INP001). Ruff treats each one, and
# every directory below it, as a package when it resolves modules.
# - policyengine_api is a namespace package, which mypy reads with
#   explicit_package_bases. This also covers its routes and libs directories,
#   which have no __init__.py either.
# - .github (with .github/scripts) and migrations/v1 and v2 hold standalone
#   scripts and Alembic environments, run but never imported.
# - rules/fixtures holds rule proof fixtures, which tests read as source.
namespace-packages = [
    ".github",
    "migrations/v1",
    "migrations/v2",
    "policyengine_api",
    "rules/fixtures",
]

[tool.ruff.lint]
# Every ruff rule applies, with no ratchet, apart from the ignores below
# (api.quality.ruff-lint). See docs/engineering/skills/rules-registry.md and
# rules/registry.toml.
select = ["ALL"]
ignore = [
    # These conflict with ruff format; ruff's documentation says to disable
    # them when using the formatter.
    "COM812", "ISC001",
    # Mutually exclusive pydocstyle pairs: keep D211 (no blank line before a
    # class docstring) and D212 (summary on the first line).
    "D203", "D213",
]
# Alembic revisions must stay exactly as Alembic generates them
# (api.migration.alembic-autogenerated-only), so ruff does not lint them. This
# is an exclusion, not a file-level exception: per-file-ignores are only for
# tests, CI/CD scripts and command-line scripts.
exclude = ["migrations/*/versions/*.py"]

[tool.ruff.lint.per-file-ignores]
# File-level exceptions are allowed only for tests, CI/CD scripts and
# command-line scripts; the rules guard checks each pattern covers nothing else
# (docs/engineering/skills/rules-registry.md#file-level-exceptions).
# Tests may use pytest's bare assert, and need no docstrings, annotations or
# named constants for magic numbers. They may also reach into private members,
# live in directories that aren't packages, import inside a test (often after
# patching the environment), and use fake credentials, naive datetimes,
# subprocess calls to repository scripts, SQL built from strings and prints,
# may import the lazily loaded packages at module level, may name a fake's
# methods after the interface it replaces, and may leave a stand-in's
# arguments unused. Every other rule applies to tests.
"**/tests/**" = [
    "ANN", "ARG001", "ARG002", "ARG005", "D1", "DTZ001", "DTZ011", "INP001",
    "N802", "PLC0415", "PLR2004", "S101", "S105", "S106", "S603", "S607",
    "S608", "SLF001", "T201", "TID253",
]
# The shared rules tool needs only the standard library, so its tests use
# unittest on purpose; pytest-style rules don't apply to them.
"scripts/rules/tests/**" = ["PT"]
# CI/CD scripts print their results, fetch fixed URLs, may have hyphenated
# file names and may import the lazily loaded packages at module level.
".github/**" = ["N999", "S310", "T201", "TID253"]
# Command-line scripts print their output, run other programs, fetch fixed
# URLs, stamp today's date and pick random samples.
"scripts/**" = [
    "DTZ011", "S310", "S311", "S603", "S607", "T201",
]
# Modules that also run as command-line programs print their output.
"policyengine_api/{data/v2/catalog/initialization,data/v2/household_migration_qualification,data/v2/policy_migration_qualification,data/v2/privilege_reconciliation,data/v2/user_association_migration_qualification,worker_spm_release}.py" = ["T201"]

[tool.mypy]
python_version = "3.11"
files = [
    "policyengine_api/query_parameters.py",
    "policyengine_api/fastapi_routes/query_parameters.py",
    "policyengine_api/fastapi_routes/dependencies.py",
    "policyengine_api/fastapi_routes/v2",
    "policyengine_api/services/v2",
    "policyengine_api/libs/user_auth.py",
    "policyengine_api/libs/auth0_management.py",
]
explicit_package_bases = true
follow_imports = "silent"
disallow_untyped_defs = true
warn_return_any = true
warn_unused_ignores = true
show_error_codes = true

[tool.towncrier]
package = "policyengine_api"
directory = "changelog.d"
filename = "CHANGELOG.md"
title_format = "## [{version}] - {project_date}"
issue_format = ""
underlines = ["", "", ""]

[[tool.towncrier.type]]
directory = "breaking"
name = "Breaking changes"
showcontent = true

[[tool.towncrier.type]]
directory = "added"
name = "Added"
showcontent = true

[[tool.towncrier.type]]
directory = "changed"
name = "Changed"
showcontent = true

[[tool.towncrier.type]]
directory = "fixed"
name = "Fixed"
showcontent = true

[[tool.towncrier.type]]
directory = "removed"
name = "Removed"
showcontent = true
[tool.ruff.lint.flake8-tidy-imports]
# Packages and modules that load only inside the function that needs them,
# never at module level (TID253 enforces it; TYPE_CHECKING imports are fine):
# policyengine and spm_calculator load country models, the v2 database module
# registers an exit hook at import, the v2 database sessions and services load
# persistence only when a default factory runs, and Auth0 Management and the
# Google Secret Manager client load only when a secret is read. Ruff's PLC0415
# accepts in-function imports of these without a suppression. A module belongs
# here only if no application module imports it at module level.
banned-module-level-imports = [
    "google.cloud.secretmanager",
    "policyengine",
    "policyengine_api.data.v2.database",
    "policyengine_api.libs.auth0_management",
    "policyengine_api.services.v2.households.database_session",
    "policyengine_api.services.v2.households.services",
    "policyengine_api.services.v2.legacy_refs.database_session",
    "policyengine_api.services.v2.legacy_refs.services",
    "policyengine_api.services.v2.metadata.database_session",
    "policyengine_api.services.v2.metadata.services",
    "policyengine_api.services.v2.policies.database_session",
    "policyengine_api.services.v2.policies.services",
    "policyengine_api.services.v2.user_accounts.database_session",
    "policyengine_api.services.v2.user_accounts.services",
    "policyengine_api.services.v2.user_households.database_session",
    "policyengine_api.services.v2.user_households.services",
    "policyengine_api.services.v2.user_policies.database_session",
    "policyengine_api.services.v2.user_policies.services",
    "policyengine_api.services.v2.user_reports.database_session",
    "policyengine_api.services.v2.user_reports.services",
    "policyengine_api.services.v2.user_simulations.database_session",
    "policyengine_api.services.v2.user_simulations.services",
    "spm_calculator",
]

[tool.ruff.lint.flake8-type-checking]
# Classes whose annotations Pydantic, SQLModel or SQLAlchemy evaluate at runtime, so their
# imports must stay at runtime. Ruff checks direct bases only, so every
# project class that other models inherit from is listed.
runtime-evaluated-base-classes = [
    "policyengine_api.data.v2.models.base.IdentifiedModel",
    "policyengine_api.data.v2.models.base.TimestampedModel",
    "policyengine_api.data.v2.models.comparison_runs.Stage12RunTimestamps",
    "policyengine_api.data.v2.models.reports.GeographicImpactBase",
    "policyengine_api.fastapi_routes.v2.households.document_models.HouseholdEntityRecord",
    "policyengine_api.fastapi_routes.v2.households.document_models.StrictHouseholdDocumentModel",
    "policyengine_api.fastapi_routes.v2.households.response_models.HouseholdSuccessResponse",
    "policyengine_api.fastapi_routes.v2.households.response_models.StrictHouseholdAPIModel",
    "policyengine_api.fastapi_routes.v2.me.response_models.AccountSuccessResponse",
    "policyengine_api.fastapi_routes.v2.me.response_models.StrictAccountAPIModel",
    "policyengine_api.fastapi_routes.v2.metadata.response_models.MetadataResourceSuccessResponse",
    "policyengine_api.fastapi_routes.v2.policies.response_models.PolicySuccessResponse",
    "policyengine_api.fastapi_routes.v2.policies.response_models.StrictPolicyAPIModel",
    "policyengine_api.fastapi_routes.v2.user_households.response_models.StrictUserHouseholdAPIModel",
    "policyengine_api.fastapi_routes.v2.user_households.response_models.UserHouseholdSuccessResponse",
    "policyengine_api.fastapi_routes.v2.user_policies.response_models.StrictUserPolicyAPIModel",
    "policyengine_api.fastapi_routes.v2.user_policies.response_models.UserPolicySuccessResponse",
    "policyengine_api.fastapi_routes.v2.user_reports.response_models.StoredSnapshotItem",
    "policyengine_api.fastapi_routes.v2.user_reports.response_models.StrictUserReportAPIModel",
    "policyengine_api.fastapi_routes.v2.user_reports.response_models.UserReportSuccessResponse",
    "policyengine_api.fastapi_routes.v2.user_simulations.response_models.StrictUserSimulationAPIModel",
    "policyengine_api.fastapi_routes.v2.user_simulations.response_models.UserSimulationSuccessResponse",
    "policyengine_api.query_parameters.CatalogQuery",
    "policyengine_api.query_parameters.CountryQuery",
    "policyengine_api.query_parameters.EconomyQuery",
    "policyengine_api.query_parameters.PaginationQuery",
    "policyengine_api.query_parameters.StrictQueryParameters",
    "policyengine_api.services.v2.associations.types.StrictAssociationModel",
    "policyengine_api.services.v2.households.types.HouseholdCreationInput",
    "policyengine_api.services.v2.households.types.StrictHouseholdInput",
    "policyengine_api.services.v2.metadata.types.MetadataModelVersion",
    "policyengine_api.services.v2.metadata.types.StrictResponseModel",
    "policyengine_api.services.v2.policies.types.PolicyCreationInput",
    "policyengine_api.services.v2.policies.types.StrictPolicyInput",
    "policyengine_api.services.v2.simulations.types.StrictContractModel",
    "policyengine_api.services.v2.user_accounts.types.AccountUpdateInput",
    "policyengine_api.services.v2.user_accounts.types.StrictAccountInput",
    "policyengine_api.services.v2.user_households.types.StrictUserHouseholdInput",
    "policyengine_api.services.v2.user_households.types.UserHouseholdCreateFields",
    "policyengine_api.services.v2.user_households.types.UserHouseholdCreationInput",
    "policyengine_api.services.v2.user_households.types.UserHouseholdUpdateInput",
    "policyengine_api.services.v2.user_policies.types.StrictAssociationInput",
    "policyengine_api.services.v2.user_policies.types.UserPolicyCreateFields",
    "policyengine_api.services.v2.user_policies.types.UserPolicyCreationInput",
    "policyengine_api.services.v2.user_policies.types.UserPolicyUpdateInput",
    "policyengine_api.services.v2.user_reports.types.StrictUserReportModel",
    "policyengine_api.services.v2.user_reports.types.UserReportCreateFields",
    "policyengine_api.services.v2.user_reports.types.UserReportUpdateInput",
    "policyengine_api.services.v2.user_reports.types._ReportPresentationFields",
    "policyengine_api.services.v2.user_simulations.types.StrictUserSimulationInput",
    "policyengine_api.services.v2.user_simulations.types.UserSimulationCreateFields",
    "policyengine_api.services.v2.user_simulations.types.UserSimulationUpdateInput",
    "policyengine_api.data.v1_models.V1Base",
    "pydantic.BaseModel",
    "sqlalchemy.orm.DeclarativeBase",
    "sqlmodel.SQLModel",
]
# FastAPI evaluates endpoint annotations when routes are registered.
runtime-evaluated-decorators = [
    "fastapi.APIRouter.api_route",
    "fastapi.APIRouter.delete",
    "fastapi.APIRouter.get",
    "fastapi.APIRouter.patch",
    "fastapi.APIRouter.post",
    "fastapi.APIRouter.put",
]