pyproject.toml

[project]
name = "vgi-rpc"
version = "0.42.0"
description = "Vector Gateway Interface - RPC framework based on Apache Arrow"
readme = "README.md"
requires-python = ">=3.13"
license = {file = "LICENSE.md"}
authors = [{ name = "Query.farm" }]
keywords = ["rpc", "arrow", "ipc", "serialization", "streaming"]
classifiers = [
  "Development Status :: 4 - Beta",
  "Intended Audience :: Developers",
  "License :: OSI Approved :: Apache Software License",
  "Programming Language :: Python :: 3",
  "Programming Language :: Python :: 3.13",
  "Topic :: Software Development :: Libraries :: Python Modules",
  "Typing :: Typed",
]
dependencies = ["pyarrow>=14.0", "docstring-parser>=0.16", "tzdata>=2024.1; sys_platform == 'win32'", "pywin32>=306; sys_platform == 'win32'"]

[project.urls]
Homepage = "https://github.com/Query-farm/vgi-rpc-python"
Repository = "https://github.com/Query-farm/vgi-rpc-python"
Issues = "https://github.com/Query-farm/vgi-rpc-python/issues"
Documentation = "https://vgi-rpc-python.query.farm/"

[project.optional-dependencies]
http = [
    "falcon>=3.0",
    "httpx2>=2.9.1",
    "waitress>=2.0",
    "zstandard>=0.20",
    "pycryptodome>=3.20",
    # State-token encoding for flat stream states (see the compact codec in
    # vgi_rpc/utils.py). The HTTP state token is its only caller, so it lives
    # here rather than in the core dependency set; without it the codec
    # reports "not applicable" and states fall back to Arrow IPC.
    "msgpack>=1.0",
    # AEAD backend, selected by platform rather than at runtime -- see the
    # BACKENDS section of vgi_rpc/crypto.py. PyNaCl is declared only where it
    # measured faster for our token sizes; elsewhere PyCryptodome is used and
    # this is simply not installed.
    "pynacl>=1.6.0; sys_platform == 'linux'",
]
s3 = ["boto3>=1.28"]
gcs = ["google-cloud-storage>=2.10"]
cli = ["typer>=0.9", "httpx2>=2.9.1", "filelock>=3.13"]
# aiohttp >=3.14.1 picks up a batch of client-side security fixes (CVE-2026-
# 34993, -47265, -502xx, -542xx). The old <3.14 cap existed only because
# aioresponses broke on 3.14's ClientResponse.stream_writer kwarg; the test
# suite has since migrated to aiointercept, so the cap is lifted.
external = ["aiohttp>=3.14.1", "tenacity>=8.0", "zstandard>=0.20"]
otel = ["opentelemetry-api>=1.20", "opentelemetry-sdk>=1.20"]
oauth = ["joserfc>=1.0"]
# Floor is 50.0 for GHSA-g6cj-pr64-35w5 (Bleichenbacher oracle in PKCS#7
# EnvelopedData decryption, 44.0.0–49.x). This package never decrypts PKCS#7 —
# `_mtls.py` only parses x509 and hashes — so the floor is about not handing a
# consumer a resolution into the vulnerable range, not about our own exposure.
mtls = ["cryptography>=50.0"]
sentry = ["sentry-sdk>=2.0"]
conformance = ["jsonschema>=4.0"]

[project.scripts]
vgi-rpc = "vgi_rpc.cli:app"
vgi-rpc-conformance = "vgi_rpc.conformance._cli:main"
vgi-rpc-test = "vgi_rpc.conformance._test_cli:main"

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

[tool.ruff]
line-length = 120
target-version = "py313"

[tool.ruff.lint]
select = ["E", "F", "I", "UP", "B", "SIM", "D", "RUF", "PERF", "RET", "C4", "PIE", "ISC", "FURB110", "TC006"]
ignore = [
  "D203",   # incompatible with D211 (no-blank-line-before-class)
  "D213",   # incompatible with D212 (multi-line-summary-first-line)
  "RUF022", # __all__ is intentionally grouped by category, not sorted
]

[tool.ruff.format]
quote-style = "double"
# ruff >=0.16 formats Python code blocks embedded in Markdown. Our docs use
# mkdocs `pymdownx.snippets` includes (`--8<-- "examples/foo.py"`) inside
# ```python fences; ruff parses those as Python and rewrites them to
# `--8 < --"..."`, silently breaking the docs build. Keep Markdown out.
exclude = ["*.md"]

[tool.mypy]
python_version = "3.13"
strict = true
warn_return_any = true
warn_unused_ignores = true
warn_unreachable = true
# Opt-in error codes beyond strict. All currently report zero findings; they
# guard against future regressions (forgotten awaits, bare type:ignores, etc).
enable_error_code = [
  "ignore-without-code",  # require # type: ignore[code], not bare ignores
  "unused-awaitable",     # catch un-awaited coroutines in the async paths
  "truthy-bool",          # flag `if some_func:` (always-true) mistakes
  "truthy-iterable",      # flag `if some_iterable:` on always-true types
  "mutable-override",     # unsafe mutable-attribute overrides
]

# warn_unreachable is valuable in library code but produces false positives in
# tests, where assert-narrowing collides with mutation mypy can't see (state
# changed via background threads / methods) and with pyarrow stub imprecision.
# CI type-checks vgi_rpc/ only; tests are checked via the pytest-mypy plugin.
[[tool.mypy.overrides]]
module = "tests.*"
warn_unreachable = false

[[tool.mypy.overrides]]
module = "falcon.*"
ignore_missing_imports = true

[[tool.mypy.overrides]]
module = "msgpack.*"
ignore_missing_imports = true

[[tool.mypy.overrides]]
module = "waitress.*"
ignore_missing_imports = true

[[tool.mypy.overrides]]
# PyNaCl ships no stubs. Only used behind the AEAD backend selection in
# vgi_rpc.crypto, and only installed on platforms where it is the faster one.
module = "nacl.*"
ignore_missing_imports = true

[[tool.mypy.overrides]]
module = "boto3.*"
ignore_missing_imports = true

[[tool.mypy.overrides]]
module = "moto.*"
ignore_missing_imports = true

[[tool.mypy.overrides]]
module = "google.cloud.*"
ignore_missing_imports = true

[[tool.mypy.overrides]]
module = "typer.*"
ignore_missing_imports = true

[[tool.mypy.overrides]]
module = "opentelemetry.*"
ignore_missing_imports = true

# pywin32 (Windows-only; no stubs installed on the Linux CI runner).
[[tool.mypy.overrides]]
module = ["win32file", "win32pipe", "winerror", "pywintypes"]
ignore_missing_imports = true

[[tool.mypy.overrides]]
module = "joserfc.*"
ignore_missing_imports = true

[[tool.mypy.overrides]]
module = "sentry_sdk.*"
ignore_missing_imports = true

[[tool.mypy.overrides]]
module = "cryptography.*"
ignore_missing_imports = true

[[tool.mypy.overrides]]
module = "Crypto.*"
ignore_missing_imports = true

[[tool.mypy.overrides]]
module = "pytest_benchmark.*"
ignore_missing_imports = true

[[tool.mypy.overrides]]
module = ["tests.*", "vgi_rpc.conformance._pytest_suite"]
# Protocol classes are passed as type markers (not instantiated) to serve_pipe/connect/http_connect;
# type[P] correctly triggers type-abstract for abstract Protocol classes.
disable_error_code = ["type-abstract"]

[tool.ty.rules]
unused-type-ignore-comment = "ignore"  # these comments are required by mypy

[tool.ty.environment]
python-version = "3.13"

[tool.pytest.ini_options]
# -n auto: the suite is subprocess- and socket-heavy, so it spends much of its
#   wall-clock blocked rather than computing. Server fixtures are session-scoped
#   and bind ephemeral ports / uuid-suffixed socket paths, so each xdist worker
#   builds its own isolated set with no cross-worker collisions.
# --dist loadfile: distribute by module, not by individual test. Two reasons,
#   both load-bearing:
#     1. Session-scoped fixtures are per-*worker*. Splitting one module across
#        workers makes each of them spawn its own copy of that module's server
#        farm (test_conformance.py alone pulls in ~15 worker subprocesses), and
#        that spawn storm is what pushes fixture setup past its budget.
#     2. It preserves within-module test ordering, which the stats tests rely on.
# --durations=25: keep the slowest tests visible. Without it, regressions in
#   test runtime are invisible until the whole suite feels slow.
addopts = "-n auto --dist loadfile --durations=25 --mypy --ruff --timeout=50 --benchmark-disable -m 'not benchmark'"
markers = ["benchmark: performance benchmarks (deselected by default)"]
testpaths = ["tests"]
# Charge the timeout to the test body only, not to fixture setup/teardown.
# The conformance suite's `pytest.mark.timeout(5)` (see
# vgi_rpc/conformance/_pytest_suite.py) exists to catch a hung RPC call; without
# this, that same 5s budget also has to cover session-scoped fixtures spawning
# worker subprocesses. That was always fragile and became a hard failure under
# `-n auto`, where several workers spawn their server farms at once and a cold
# subprocess start easily exceeds 5s.
timeout_func_only = true

[tool.coverage.run]
# Each subprocess writes to its own data file (.coverage.<hostname>.<pid>)
parallel = true
# Handle SIGTERM gracefully (writes coverage data before exit)
sigterm = true
# Measure branch coverage
branch = true
# What to measure
source = ["vgi_rpc"]
# Omit test files and examples from coverage
omit = ["vgi_rpc/examples/*", "tests/*"]

[tool.coverage.report]
# Fail if coverage drops below this threshold
fail_under = 80
# Show missing lines in the report
show_missing = true
# Exclude common patterns from coverage
exclude_lines = [
  "pragma: no cover",
  "if TYPE_CHECKING:",
  "if __name__ == .__main__.:",
  "@overload",
  "raise NotImplementedError",
  "\\.\\.\\.",                  # Ellipsis in stub files
]

[tool.coverage.html]
directory = "htmlcov"

[tool.mutmut]
paths_to_mutate = ["vgi_rpc/utils.py"]
pytest_add_cli_args_test_selection = ["tests/"]
also_copy = ["vgi_rpc/"]
pytest_add_cli_args = ["--timeout=50", "--no-header", "-o", "addopts=", "-o", "pythonpath=.", "--ignore=tests/test_external_fetch.py"]

[dependency-groups]
docs = [
    "mkdocs>=1.6",
    "mkdocs-material>=9.5",
    "mkdocstrings[python]>=0.27",
    "mkdocs-section-index>=0.3",
    "mkdocs-d2-plugin>=1.4",
    "pygments>=2.20",
    "pymdown-extensions>=10.21.2",
]
dev = [
    "aiointercept>=0.1.7",
    "joserfc>=1.0",
    "boto3>=1.28",
    "falcon>=3.0",
    "filelock>=3.13",
    "google-cloud-storage>=2.10",
    "httpx2>=2.9.1",
    "jsonschema>=4.0",
    "types-jsonschema>=4.0",
    "lxml>=6.0.2",
    "moto[s3]>=4.0",
    "mutmut>=3.4.0",
    "mypy>=1.0",
    "pyarrow-stubs>=17.0",
    "pytest>=7.0",
    "pytest-cov>=4.0",
    "pytest-examples>=0.0.10",
    "pytest-mypy>=0.10",
    "pytest-ruff>=0.1",
    "pytest-timeout>=2.4.0",
    "pytest-xdist>=3.6",
    "ruff>=0.1",
    # Capped below 0.0.64: at 0.0.66, `ty check` stopped terminating on the
    # sibling vgi-python tree -- it ran past ten minutes locally and, in CI,
    # hung until the step was cancelled, which `continue-on-error` does not
    # rescue. ty is pre-1.0 and gates nothing here, so the cap costs nothing
    # and stops a routine `uv lock --upgrade` from silently reintroducing it.
    # Retest and lift once upstream terminates again.
    "ty>=0.0.8,<0.0.64",
    "typer>=0.9",
    "waitress>=2.0",
    "opentelemetry-api>=1.20",
    "opentelemetry-sdk>=1.20",
    "pytest-benchmark>=4.0",
    "sentry-sdk>=2.0",
    "cryptography>=50.0",  # see the mtls extra for why this floor is not 41.0
    "pycryptodome>=3.20",
    "hypothesis>=6.155.3",
]
# pydoclint is intentionally NOT a project dependency. It depends on
# `docstring-parser-fork`, which installs into the same `docstring_parser/`
# import namespace as the canonical `docstring-parser` this package needs at
# runtime (vgi_rpc/rpc/_types.py). When both land in one venv, whichever uv
# installs last wins non-deterministically — and the fork-vs-canonical race
# made docstring symbols (e.g. DocstringYields) appear/disappear across
# unrelated dependency bumps, flaking the lint gate. Run pydoclint isolated:
#   uvx --python 3.13 --from pydoclint==0.8.7 pydoclint vgi_rpc/
# (CI uses the same invocation; --python 3.13 is required so the parser
# understands this package's 3.13 syntax.)

[tool.pydoclint]
# Docstring consistency gate (complements ruff's `D` rules, which only check
# docstring *shape*, not whether documented args/attributes match the code).
# Enforced families: DOC001 (parse), DOC101/102/103 (arg<->signature), DOC4xx
# (yields), DOC60x (dataclass attributes). Run isolated (see note by the dev
# group above): `uvx --python 3.13 --from pydoclint==0.8.7 pydoclint vgi_rpc/`.
style = "google"
# We keep types in signatures, not docstrings (Google style) — so don't ask for
# them in docstrings, and don't try to match return/yield *types* against prose.
arg_type_hints_in_docstring = false
check_return_types = false
check_yield_types = false
# Allow `__init__` to carry its own docstring and validate its `Args:` there
# (rather than requiring constructor params to be documented on the class).
allow_init_docstring = true
# Validate that an `Attributes:` section matches the actual dataclass fields.
check_class_attributes = true
# Raises (DOC5xx) are intentionally not gated: this codebase documents
# exceptions via mkdocstrings `[`Exc`][]` cross-refs and raises them indirectly,
# neither of which pydoclint can see. (pydoclint 0.8.x has no per-code ignore,
# so non-gated families are turned off via these family switches instead.)
skip_checking_raises = true
# No baseline: vgi_rpc/ is fully clean under this config, so the gate enforces
# every in-scope violation with no grandfathered exceptions. If a future change
# needs to defer cleanup, freeze the current state and re-add `baseline`:
#   uv run pydoclint --generate-baseline=True --baseline=.pydoclint-baseline vgi_rpc/