pyproject.toml

[build-system]
build-backend = "hatchling.build"
# Lower bound: 1.27 is the first release with PEP 639 license metadata.
requires = ["hatchling>=1.27", "hatch-vcs"]

[project]
name = "harv"
dynamic = ["version"]
description = "Tools for modeling Keplerian systems in astrometric and/or radial velocity data."
authors = [
    { name = "adrn", email = "583379+adrn@users.noreply.github.com" },
]
license = "MIT"
license-files = ["LICENSE"]
requires-python = ">= 3.12"
readme = {"file" = "README.md", "content-type" = "text/markdown"}
# No "License :: OSI Approved :: ..." classifier: deprecated by PEP 639 now that
# `license` above is an SPDX expression.
classifiers = [
    "Development Status :: 2 - Pre-Alpha",
    "Intended Audience :: Science/Research",
    "Operating System :: OS Independent",
    "Programming Language :: Python",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3 :: Only",
    "Programming Language :: Python :: 3.12",
    "Programming Language :: Python :: 3.13",
    "Programming Language :: Python :: 3.14",
    "Topic :: Scientific/Engineering",
    "Typing :: Typed",
]
# TODO: add keywords
keywords = []
dependencies = [
    "equinox>=0.13.2",
    "h5py>=3.15.1",
    "jax>=0.8.1",
    "jaxoplanet>=0.1.0",
    "jaxtyping>=0.3.3",
    # Imported directly across the package; np.trapezoid is 2.0+ (1.x: trapz).
    "numpy>=2.0",
    "numpyro>=0.15.0",
    "quaxed>=0.10.4",
    "unxt>=1.7.2",
]

[project.optional-dependencies]
# GPU builds. jax ships CUDA support as extras of its own, so harv just forwards
# them, pinned to the same jax floor as the CPU install: `pip install harv[cuda13]`
# is `pip install harv jax[cuda13]`. Plain `harv` is the CPU build.
# The linux marker is load-bearing: without it `uv lock` fails on macOS, where the
# nvidia / jax-cuda*-plugin wheels do not exist.
cuda12 = ["jax[cuda12]>=0.8.1; sys_platform == 'linux'"]
cuda13 = ["jax[cuda13]>=0.8.1; sys_platform == 'linux'"]
extra = [
    "gaiaunlimited>=0.3.2",
    "setuptools",  # needed for gaiaunlimited for pkg_resources...
    "arviz>=1.0.0",
    "matplotlib>=3.10.7",
    "tinygp>=0.3.1",
    "healpy>=1.18.1",
    "pooch>=1.8.2",
    "scikit-learn>=1.5",
]

[tool.uv]
override-dependencies = [
    # TODO: remove this once unxt is released with the quantity-stub branch merged.
    "unxt @ git+https://github.com/adrn/unxt.git@quantity-stub",
    "gaiaunlimited @ git+https://github.com/gaia-unlimited/gaiaunlimited.git"
]

[dependency-groups]
extra = [
    "gaiaunlimited @ git+https://github.com/gaia-unlimited/gaiaunlimited.git",
    "setuptools",  # needed for gaiaunlimited for pkg_resources...
    "arviz>=1.0.0",
    "matplotlib>=3.10.7",
    "tinygp>=0.3.1",
    "healpy>=1.18.1",
    "pooch>=1.8.2",
    "scikit-learn>=1.5",
]
dev = [
    {include-group = "extra"},
    {include-group = "test"},
    {include-group = "docs"},
    {include-group = "nox"},
    "hatch",
    "ipykernel",
    "ipywidgets",
    "pre-commit",
    # >=7: hatchling>=1.27 emits core metadata 2.5 for PEP 639 license fields, and
    # twine only learned to read that in 7.0 (pypa/twine#1327). Older twine fails
    # `twine check` on a perfectly valid wheel. The release workflow gets twine 7
    # via build-and-inspect-python-package; this keeps local checks in step.
    "twine>=7",
    # Keep in lockstep with the ruff-pre-commit rev in .pre-commit-config.yaml.
    # When they drift, `uv run ruff` and CI disagree about which rules exist --
    # that is how CPY001 stayed invisible locally while failing pre-commit.
    "ruff==0.16.0",
    "ty>=0.0.22",
    "jedi==0.19.1",
]
docs = [
    {include-group = "extra"},
    "sphinx~=8.0",
    "myst-parser>=4.0",
    "sphinx-autobuild>=2024.10.3",
    "sphinx-design>=0.6.1",
    "sphinx-copybutton>=0.5.2",
    "sphinx_autodoc_typehints>=2.5",
    "corner>=2.2.3",
    "ipykernel>=7.1.0",
    "myst-nb>=1.4.0",
    "nbconvert>=7.17.1",
    "rtds-action>=1.1.0",
    "furo>=2024.8.6",
]
test = [
    "pytest",
    "pytest-cov",
    "pytest-raises",
    # "pytest-randomly",
    "pytest-xdist",
    "beartype",
    "matplotlib>=3.10.7",
    "sybil>=10.0.1",
    # Optional runtime deps the suite exercises. CI installs only this group
    # (uv sync --no-default-groups --group test), so anything missing here is
    # silently lost coverage rather than a failure -- and before that change CI
    # installed the whole `dev` group, so these all ran. Keep this list complete:
    #   corner       -> Samples.plot_corner
    #   scikit-learn -> Samples.period_modes
    #   arviz        -> Samples.to_arviz (and the tests that monkeypatch samples.az)
    #   tinygp       -> the GP likelihood extension
    # What is deliberately absent is the *docs* toolchain, nox, hatch, and the git
    # checkout of gaiaunlimited -- that is the weight this scoping removes.
    "corner>=2.2.3",
    "scikit-learn>=1.5",
    "arviz>=1.0.0",
    "tinygp>=0.3.1",
]
nox = [
    "nox>=2026.4.10",
    "nox-uv>=0.8.0",
]
bench-cuda = [
    # CUDA-enabled jaxlib for the GPU benchmark run. Marked linux-only: the CUDA
    # plugin wheels are only published for Linux:
    "jax[cuda13]>=0.8.1; sys_platform == 'linux'",
]
bench = [
    # Deliberately NOT included in `dev`, and CI installs only the `test` group
    # (`uv sync --no-default-groups --group test`), so pytest-benchmark is never
    # present on CI. That absence is one of the belts keeping benchmarks/ off CI;
    # see docs/running-benchmarks.md.
    "pytest",
    "pytest-benchmark>=5.0",
    "matplotlib>=3.10.7",
    "h5py>=3.15.1",
]

[project.urls]
Homepage = "https://github.com/adrn/harv"
"Source Code" = "https://github.com/adrn/harv"
"Bug Tracker" = "https://github.com/adrn/harv/issues"
Documentation = "https://harvey.readthedocs.io"
Download = "https://pypi.org/project/harv/#files"

################################################################################
# Tool Configuration
################################################################################

# Hatch is building your package's wheel and sdist
# This tells hatch to only include Python packages (i.e., folders with __init__.py) in the build.
# read more about package building, here:
# https://www.pyopensci.org/python-package-guide/package-structure-code/python-package-distribution-files-sdist-wheel.html
[tool.hatch.build]
only-packages = true

# This tells Hatch to build the package from the src/ directory.
# Read more about src layouts here: https://www.pyopensci.org/python-package-guide/package-structure-code/python-package-structure.html
[tool.hatch.build.targets.wheel]
packages = ["src/harv"]


[tool.hatch.build.hooks.vcs]
version-file = "src/harv/_version.py"

[tool.hatch.version]
source = "vcs"

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

######## Configure pytest for your test suite ########
[tool.pytest.ini_options]
minversion = "8.3"
addopts = [
    "-ra",              # short summary of all non-passing outcomes
    "--showlocals",
    "--strict-markers", # an unregistered marker is an error, not a typo that silently does nothing
    "--strict-config",  # an unknown key in this table is an error
]
xfail_strict = true
log_cli_level = "INFO"
testpaths = ["README.md", "tests", "src"]
markers = ["raises"] # Tells pytest to not raise a warning if you use @pytest.mark.raises
# Warnings are errors: harv tracks fast-moving upstreams (jax, unxt, numpyro) and a
# deprecation that only prints is a deprecation nobody acts on. Add a narrow
# "ignore:<regex>:<Category>" line per warning that is genuinely not ours to fix, and
# delete it once upstream does.
filterwarnings = [
    "error",
    # -- harv's own advisory warnings -------------------------------------------
    # Both fire on paths the suite deliberately exercises: a non-Gaussian linear
    # prior that cannot be marginalized, and an optimizer given deliberately hard
    # data. Advisory by design, not defects. Matched by message so that a *new*
    # warning from the same module still fails the suite.
    "ignore:Non-Gaussian linear prior:UserWarning",       # samplers/_prior_resolution.py
    "ignore:BFGS did not converge:UserWarning",           # samplers/numpyro.py
    # Fires on every small rejection run in the suite -- toy data with a few
    # thousand prior samples really is under-resolved.  The warning's own
    # behavior (fires when it should, stays quiet when it should not) is
    # covered by tests/unit/test_samplers/test_acceptance_diagnostics.py,
    # which uses pytest.warns / catch_warnings and so is unaffected by this.
    "ignore:Under-resolved rejection run:UserWarning",    # samplers/rejection.py
    # -- third-party chatter ----------------------------------------------------
    "ignore:The figure layout has changed to tight:UserWarning",  # matplotlib
]

[tool.coverage.paths]
source = [
    "src/harv",
    "*/site-packages/harv",
]

[tool.coverage.run]
# Ensures code coverage is measured for branches (conditional statements with different outcomes) in your code.
branch = true
parallel = true
omit = [
    "src/harv/_version.py",
]

[tool.coverage.report]
# This configures the output test coverage report.
# `exclude_also` *extends* coverage's built-in defaults (which already cover
# `pragma: no cover`); `exclude_lines` would replace them.
exclude_also = [
    '\.\.\.',
    'if typing.TYPE_CHECKING:',
    'if TYPE_CHECKING:',
]
precision = 2

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

    [tool.ruff.lint]
    select = ["ALL"]
    ignore = [
        "D107",  # 'Missing docstring in __init__' ignored because pydoclint wants us to document the class instead.
        "D203",  # '1 blank line required before class docstring' ignored because we want no blank line.
        "D212",  # 'Multi-line docstring summary should start at the first line' ignored because we want the summary to start on the second line.
        "D407",  # 'Missing dashed underline after section' ignored because Google style docstrings don't underline.
        "D413",  # 'Missing blank line after section' ignored .
        "D401",  # 'First line should be in imperative mood' ignored
        "ANN001",  # Missing type annotation for {arg} in function" ignored
        "ANN201",  # 'Missing type annotation for {return}'.
        "ANN401",  # Dynamically typed expressions (typing.Any) are disallowed
        "ARG001",  # Unused function argument  # TODO: resolve
        "B008",    # Do not perform function calls in argument defaults
        "COM812",  # <- for ruff.format
        "CPY001",  # Missing copyright notice -- this project does not use file headers
        "D103",    # Missing docstring in public function  # TODO: resolve
        "D105",    # Missing docstring in magic method
        "D203",    # 1 blank line required before class docstring
        "D213",    # Multi-line docstring summary should start at the second line
        "ERA001",  # Commented out code
        "F722",    # Syntax error in forward annotation  <- jaxtyping
        "F811",    # redefinition of unused '...'  <- plum-dispatch
        # "F821",    # undefined name '...'  <- jaxtyping
        "FIX002",  # Line contains TODO
        "ISC001",  # Conflicts with formatter
        "PD",      # Pandas
        "PLR09",   # Too many <...>
        "PLR2004", # Magic value used in comparison
        "PYI041",  # Use `complex` instead of `int | complex` <- plum is more strict
        "RUF022",  # `__all__` is not sorted
        "SLF001",  # private-member-access TODO: unignore this.
        "TD002",   # Missing author in TODO
        "TD003",   # Missing issue link on the line following this TODO
        "N806",    # Variable names must be lowercase
        "EM101",   # Assign string to variable for exception
        "EM102",   # Something about f-strings in exceptions
        "TRY003",  # ??
        "INP001",
        "N803",    # Argument name should be lowercase
        "FBT001",  # Some boolean function thing
        "FBT002",  # Some boolean function thing
        "UP037",   # Remove quote from type annotation  <- jaxtyping
        "N802",    # Function name should be lowercase
        "N815",    # Variable name {name} should be lowercase
        "N816",    # should not be mixedCase
        "N817",    # CamelCase
    ]
    exclude = [
        "src/harv/_version.py",
        "docs/conf.py",
        "docs/tutorials/data/*"
    ]

    [tool.ruff.lint.extend-per-file-ignores]
    "__init__.py" = [
        "E401",  # 'Multiple imports on one line'
        "E402",  # 'Module level import not at top of file'
        "F401",  # 'Imported but unused'
        "I001",  # 'Import block is un-sorted or un-formatted' ignored because we may have to import in a particular, not-alphabetical order.
    ]
    "tests/**/*.py" = [
        "ARG002", # Unused argument
        "ANN202", # Missing type annotation"
        "D",  # documentation not important for tests
        "S101",  # Use of assert detected' ignored because we are using pytest.
        "INP001",  # Insecure input ignored because we are testing.
        "ANN201",  # Missing type annotation for {return} ignored because all tests return `None`.
        "ANN204",
    ]
    "benchmarks/**/*.py" = [
        "ARG002", # Unused argument
        "ANN202", # Missing type annotation"
        "D",  # documentation not important for benchmark harness
        "S101",  # Use of assert detected' ignored because we are using pytest.
        "INP001",  # benchmarks/ is a script directory, not an importable package.
        "ANN201",  # Missing type annotation for {return}
        "ANN204",
        "T201",  # print() is the report generator's user interface
        # Imports are deliberately deferred here. benchmarks/conftest.py must set
        # jax_enable_x64 before anything pulls in harv, and report.py has no reason
        # to import harv at all -- it only needs the grid definitions. Each such
        # import carries a comment saying so.
        "PLC0415",
        # jax.config.update(..., True) and ax.grid(True, ...) are third-party APIs
        # that take a positional bool by design.
        "FBT003",
    ]
    "src/harv/samplers/*.py" = [
        "S101",  # 'Use of assert detected' — used for type narrowing of invariants from extract_data
    ]
    "src/harv/likelihood/*.py" = [
        "RUF001",  # ambiguous unicode
        "RUF002",  # ambiguous unicode
        "RUF003",  # ambiguous unicode
    ]
    # Vendored from numpyro-ext -- not ours to lint. Scoped to the vendored
    # modules by name so harv's own code under harv/stats (e.g. grid_density.py)
    # is linted normally.
    "src/harv/stats/numpyro_ext.py" = [
        "ALL",
    ]
    "src/harv/stats/linear_op.py" = [
        "ALL",
    ]
    "docs/**/*" = [
        "E402",  # module-import-not-at-top-of-file
        "T201",  # print
        "FBT003",  # boolean-positional-value-in-call
        "A004",  # astropy.io.ascii - shadows built-in ascii
        "RUF001",  # ambiguous en dash
        "ANN202",  # missing type annotation
    ]
    "docs/_static/*" = ["ALL"]

    [tool.ruff.lint.isort]
    case-sensitive = true
    known-first-party = ["harv"]

[tool.ty.rules]

    [[tool.ty.overrides]]
    # NOTE: this is needed because of a bug or issue in the way ty and jaxtyping
    # interact. ty treats parametric string, e.g., Q["angle"] as a forward reference
    # (PEP 484 semantics), then fails to resolve angle as a Python name. The string is
    # actually a runtime dimension descriptor consumed by unxt/jaxtyping — not a forward
    # annotation.
    include = ["src/harv/custom_types.py"]
    rules = { unresolved-reference = "ignore" }

    [[tool.ty.overrides]]
    include = ["src/harv/plot.py"]
    rules = { possibly-missing-attribute = "ignore", possibly-missing-submodule = "ignore"}

    # quaxed's .pyi stubs declare ArrayLike / Sequence[ArrayLike] for these
    # functions and do not admit unxt.Quantity -- but accepting Quantity and
    # propagating units is the entire reason we call quaxed.numpy rather than
    # jax.numpy. Passing a Quantity here is correct; the stub is what is narrow.
    #
    # These only became visible with the `unxt @ quantity-stub` override in
    # [tool.uv]: that branch gives Quantity a real type, so ty can finally see
    # the mismatch it previously treated as Unknown. Delete this block together
    # with that override once the stubs upstream accept Quantity.
    [[tool.ty.overrides]]
    include = [
        "src/harv/data/helpers.py",
        "src/harv/kepler/body.py",
        "src/harv/kepler/orientation.py",
        "src/harv/models/parameterizations/rv.py",
        "src/harv/plot.py",
    ]
    rules = { invalid-argument-type = "ignore" }

    [[tool.ty.overrides]]
    include = ["src/harv/kepler/constants.py"]
    rules = { unresolved-import = "ignore" }

    [[tool.ty.overrides]]
    include = ["src/harv/stats/numpyro_ext.py", "src/harv/stats/linear_op.py"]
    rules = { all = "ignore" }


[tool.pydoclint]
style = "numpy"
arg-type-hints-in-signature = false
arg-type-hints-in-docstring = true
check-return-types = false
check-yield-types = false
exclude = ["_version.py", "scripts/*"]

# Use UV to create Hatch environments
[tool.hatch.envs.default]
installer = "uv"