pyproject.toml

[project]
name = "vgi-python"
version = "0.8.1"
description = "Vector Gateway Interface - Connect DuckDB to external programs via Apache Arrow"
readme = "README.md"
keywords = [
    "duckdb",
    "apache-arrow",
    "arrow",
    "pyarrow",
    "udf",
    "user-defined-functions",
    "sql",
    "database",
    "data-engineering",
    "analytics",
    "rpc",
    "vgi",
]
license = { file = "LICENSE" }
authors = [{ name = "Rusty Conover", email = "rusty@query.farm" }]
maintainers = [{ name = "Query Farm LLC", email = "hello@query.farm" }]
classifiers = [
    "License :: Other/Proprietary License",
    "Development Status :: 4 - Beta",
    "Intended Audience :: Developers",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3 :: Only",
    "Programming Language :: Python :: 3.13",
    "Programming Language :: Python :: 3.14",
    "Topic :: Database",
    "Topic :: Database :: Database Engines/Servers",
    "Topic :: Software Development :: Libraries :: Python Modules",
    "Operating System :: OS Independent",
    "Typing :: Typed",
]
requires-python = ">=3.13"
dependencies = [
    "click",
    "pyarrow",
    "typer>=0.9",
    "platformdirs",
    "vgi-rpc>=0.20.4",
    "httpx>=0.24",
]

[project.optional-dependencies]
# A DuckDB-compatible engine is needed at runtime only for expression-filter
# evaluation, the transactor, and the statistics fixtures. It is resolved
# lazily in vgi/_duckdb.py: haybarn is preferred, stock duckdb is the
# fallback. Neither is a hard dependency — install one via these extras.
haybarn = ["haybarn>=1.5.3rc10"]
duckdb = ["duckdb>=1.5.3"]
http = ["vgi-rpc[http]"]
oauth = ["vgi-rpc[oauth]"]
otel = ["vgi-rpc[otel]"]
sentry = ["vgi-rpc[sentry]"]
azure = [
    "pymssql>=2.3.0",
    "azure-identity>=1.16.0",
]
test-fixtures = ["numpy>=2.4.1"]
# Note: actually *running* the transactor requires an engine build with the
# VGI fork's subcursor() extension (see vgi/transactor/_duckdb_compat.py).
# That code has not yet been merged into haybarn or upstreamed to duckdb,
# so for now only local fork builds of duckdb-python provide it.
transactor = ["sqlglot"]
# Convenience extra: pulls the companion `vgi-fixtures` distribution, which
# restores vgi/_test_fixtures + the vgi-fixture-* worker commands for users who
# want the example/test workers from a traditional install.
fixtures = ["vgi-fixtures"]
test-fixtures-writable = [
    "vgi-python[test-fixtures]",
    "vgi-python[transactor]",
]
dev = [
    "duckdb>=1.5.3",
    "mypy",
    "pyarrow-stubs",
    "pydoclint",
    "pytest",
    "pytest-cov",
    "pytest-examples",
    "pytest-ruff",
    "pytest-xdist",
    "ruff",
    "vgi-python[test-fixtures,test-fixtures-writable,http,oauth,otel,sentry,azure]",
    "vgi-rpc[conformance,external,http,oauth,otel,sentry]",
]
[project.scripts]
vgi-serve = "vgi.serve:main"
vgi-secret-serve = "vgi.secret_service:main"
vgi-client = "vgi.client.cli:main"
vgi-transactor = "vgi.transactor.server:main"
# The vgi-fixture-* worker commands are intentionally NOT registered here so
# they don't ship in the public wheel / pollute end-user PATH. They are provided
# by the dev-only sidecar distribution in packages/vgi-fixtures (see its
# pyproject.toml), which is installed via the uv workspace for tests.

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

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

[tool.hatch.build.targets.wheel]
# The distribution is named `vgi-python` but the import package is `vgi`;
# name them explicitly so hatchling's name-based heuristic doesn't look for
# a (nonexistent) `vgi_python/` directory.
packages = ["vgi"]
# TEMPORARY: vgi/_test_fixtures is folded INTO this wheel while the separate
# `vgi-fixtures` PyPI project is unavailable. It stays import-only — core vgi
# never imports it, and its numpy/sqlglot deps remain behind the
# `test-fixtures`/`transactor` extras, so a plain `pip install vgi-python`
# is unaffected. To split it back out into the vgi-fixtures companion wheel,
# re-add "vgi/_test_fixtures" to the exclude list below and publish
# vgi-fixtures (see packages/vgi-fixtures).
exclude = ["vgi/codegen"]

[tool.hatch.build.targets.sdist]
exclude = []

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

[tool.ruff.lint]
select = ["E", "F", "I", "UP", "B", "SIM", "D"]

[tool.ruff.lint.pydocstyle]
convention = "google"

[tool.ruff.format]
quote-style = "double"

[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 via `uv run pydoclint vgi/`.
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
# 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.
skip_checking_raises = true
# Document constructor params in the class docstring, not __init__ (suppresses
# DOC301). pydoclint 0.8.x has no per-code ignore, so the noisy families are
# turned off via these family switches instead.
allow_init_docstring = true
# No baseline: vgi/ 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/

[tool.mypy]
python_version = "3.13"
strict = true
warn_return_any = true
warn_unused_ignores = true

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

[[tool.mypy.overrides]]
# These files have type: ignore comments for ty that mypy doesn't need
module = ["vgi._test_fixtures.scalar.null_handling", "vgi.table_function"]
warn_unused_ignores = false

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

[tool.pytest.ini_options]
addopts = "--ruff"
testpaths = ["tests"]

[tool.coverage.run]
# Enable subprocess coverage - automatically patches subprocess.Popen
# to inject coverage measurement into spawned worker processes
patch = ["subprocess"]
# 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"]
# Omit test fixtures and tests from coverage
omit = ["vgi/_test_fixtures/*", "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.uv.workspace]
members = ["packages/vgi-fixtures"]

[tool.uv.sources]
# duckdb = { path = "/path/to/duckdb-python/dist/duckdb-*.whl" }  # local engine-build override
vgi-fixtures = { workspace = true }

[dependency-groups]
dev = ["lxml>=6.0.2", "pytest-timeout>=2.4.0", "ty>=0.0.8", "vgi-fixtures"]
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",
    "ruff>=0.1",
]