pyproject.toml

[project]
name = "vgi-rpc"
version = "0.21.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", "httpx>=0.24", "waitress>=2.0", "zstandard>=0.20", "pynacl>=1.5"]
s3 = ["boto3>=1.28"]
gcs = ["google-cloud-storage>=2.10"]
cli = ["typer>=0.9", "httpx>=0.24", "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"]
mtls = ["cryptography>=41.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"

[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 = "waitress.*"
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 = "nacl.*"
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]
addopts = "--mypy --ruff --timeout=50 --benchmark-disable -m 'not benchmark'"
markers = ["benchmark: performance benchmarks (deselected by default)"]
testpaths = ["tests"]

[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",
    "httpx>=0.24",
    "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",
    "ruff>=0.1",
    "ty>=0.0.8",
    "typer>=0.9",
    "waitress>=2.0",
    "opentelemetry-api>=1.20",
    "opentelemetry-sdk>=1.20",
    "pytest-benchmark>=4.0",
    "sentry-sdk>=2.0",
    "cryptography>=41.0",
    "pynacl>=1.5",
    "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/