pyproject.toml

[project]
authors = [
  { name = "GalacticDynamics", email = "nstarman@users.noreply.github.com" },
  { name = "Nathaniel Starkman", email = "nstarman@users.noreply.github.com" },
  { name = "Adrian Price-Whelan", email = "adrianmpw@gmail.com" },
]
classifiers = [
  "Development Status :: 5 - Production/Stable",
  "Intended Audience :: Developers",
  "Intended Audience :: Science/Research",
  "Operating System :: OS Independent",
  "Programming Language :: Python :: 3 :: Only",
  "Programming Language :: Python :: 3",
  "Programming Language :: Python :: 3.12",
  "Programming Language :: Python :: 3.13",
  "Programming Language :: Python :: 3.14",
  "Programming Language :: Python",
  "Topic :: Scientific/Engineering",
  "Typing :: Typed",
]
dependencies = [
  "astropy>=7.1",
  "dataclassish>=0.8.0",
  "equinox>=0.13.7",
  "is-annotated>=1.0",
  "jax>=0.7.2",
  "jaxlib>=0.7.2",
  "jaxtyping>=0.3.9",
  "optional-dependencies>=0.4.1",
  "plum-dispatch>=2.7.0",
  "plum-dispatch>=2.9.0; python_version>='3.14'",
  "quax>=0.4.2",
  "quax-blocks>=0.5.0",
  "quaxed>=0.10.5",
  "traitlets>=5.0.0",
  "unxt-api>=2.0.0",
  "unxts.api>=2.0.0",
  "wadler-lindig>=0.1.5",
]
description = "Quantities in JAX"
dynamic = ["version"]
license = "BSD-3-Clause"
license-files = ["LICENSE"]
name = "unxt"
readme = "README.md"
requires-python = ">=3.12"

[project.optional-dependencies]
# jax extras
cpu          = ["jax[cpu]>=0.7.2"]
cuda         = ["jax[cuda]>=0.7.2"]
cuda12       = ["jax[cuda12]>=0.7.2"]
cuda12_local = ["jax[cuda12_local]>=0.7.2"]
k8s          = ["jax[k8s]>=0.7.2"]
# extra extras
all = ["unxt[backend-astropy,workspace]"]
backend-astropy = ["astropy>=7.1"]
interop-gala = ["unxts.interop.gala"]
interop-mpl = ["unxts.interop.matplotlib"]
interop-xarray = ["unxts.interop.xarray"]
linalg = ["unxts.linalg"]
parametric = ["unxts.parametric"]
workspace = [
  "unxt[interop-gala,interop-mpl,interop-xarray]",
  "unxts.api",
  "unxts.hypothesis",
  "unxts.linalg",
  "unxts.parametric",
]

[project.urls]
"Bug Tracker" = "https://github.com/GalacticDynamics/unxt/issues"
Changelog     = "https://github.com/GalacticDynamics/unxt/releases"
Discussions   = "https://github.com/GalacticDynamics/unxt/discussions"
Homepage      = "https://github.com/GalacticDynamics/unxt"


[build-system]
build-backend = "hatchling.build"
requires      = ["hatch-vcs", "hatchling"]


[dependency-groups]
build = ["build>=1.3.0"]
dev = [
  "ipykernel>=6.29.5",
  "cz-conventional-gitmoji>=0.6.1",
  { include-group = "build" },
  { include-group = "docs" },
  { include-group = "lint" },
  { include-group = "nox" },
  { include-group = "test-all" },
  { include-group = "workspace" },
]
docs = [
  # Sphinx & documentation tools
  "jupytext>=1.16.4",
  "jupyter-cache>=1.0.0",
  "myst-nb>=1.1.2",
  "myst_parser>=0.13",
  "pytz>=2024.2",                    # for copyright date
  "sphobjinv>=2.3",
  "sphinx-autobuild>=2024.9.3",
  "sphinx-book-theme==1.1.3",
  "sphinx-prompt>=1.8.0",
  "sphinx-tippy>=0.4.3",
  "sphinx>=7.0",
  "sphinx_autodoc_typehints>=3.0.0",
  "sphinx_copybutton>=0.5.2",
  "sphinx_design>=0.6.1",
  "sphinx_togglebutton>=0.3.2",
  "sphinxext-opengraph>=0.9.1",
  "sphinxext-rediraffe>=0.2.7",
  # Runtime dependencies for notebook execution
  "jax[cpu]>=0.7.2",
  "jaxlib>=0.7.2",
  "quax>=0.4.2",
]
lint = ["prek>=0.3.9", "pylint>=3.3.8"]
nox = ["nox>=2024.10.9", "nox-uv>=0.6.3"]
pytest-benchmark-parallel = ["pytest-xdist>=3.6.1"]
test = [
  "hypothesis[numpy]>=6.138.14",
  "pytest>=8.4.2",
  "pytest-arraydiff>=0.6.1",
  "pytest-benchmark>=5.1.0",
  "pytest-codspeed>=4.2.0",
  "pytest-cov>=6.2.1",
  "pytest-env>=1.1.5",
  "pytest-github-actions-annotate-failures>=0.3.0",
  "pytest-xdist>=3.6.1",
  "sybil[pytest]>=9.2.0",
]
test-all = [{ include-group = "test" }, { include-group = "test-mpl" }]
test-mpl = ["pytest-mpl>=0.17.0", "matplotlib>=3.8"]
# Pinned so the typing guards cannot drift as new checker releases change
# diagnostics. All scoped to the `tests/typing` fixture; see [tool.pyright],
# [tool.ty.src], and [tool.mypy].
typecheck = ["pyright==1.1.411", "ty==0.0.64", "mypy==2.3.0"]
workspace = [
  "unxt-api",
  "unxt-hypothesis",
  "unxts.api",
  "unxts.hypothesis",
  "unxts.interop.gala",
  "unxts.interop.matplotlib",
  "unxts.interop.xarray",
  "unxts.linalg",
  "unxts.parametric",
]


[tool.hatch]
build.hooks.vcs.version-file = "src/unxt/_version.py"
build.hooks.vcs.version-file-template = """\
version: str = {version!r}
version_tuple: tuple[int, int, int] | tuple[int, int, int, str, str]
version_tuple = {version_tuple!r}
"""
version.source = "vcs"

# Without an explicit sdist target, hatchling bundles everything tracked by git
# -- including all nine separately-published sibling packages under ``packages/``,
# ``paper/``, ``.github/`` and ``.claude/``. Keep the ``unxt`` sdist to this
# project's own files by excluding the monorepo scaffolding. ``scripts/`` holds
# release tooling; its only test (``test_validate_tag.py``) is excluded alongside
# it so the shipped test suite stays runnable from the sdist.
[tool.hatch.build.targets.sdist]
exclude = [
  "packages",
  "paper",
  ".github",
  ".claude",
  "scripts",
  "tests/unit/test_validate_tag.py",
  "uv.lock",
]

[tool.hatch.version.raw-options]
local_scheme = "no-local-version"

[tool.hatch.version.raw-options.scm.git]
describe_command = [
  "git",
  "describe",
  "--dirty",
  "--tags",
  "--long",
  "--match",
  "unxt-v*",
]


[tool.codespell]
skip = ["uv.lock", "paper/paper.bib", "paper/joss-7771.preprint.tex"]

[tool.jupytext]
cell_metadata_filter     = "tags,-all"
formats                  = "ipynb,md:myst"
notebook_metadata_filter = "kernelspec,language_info,jupytext"


[tool.commitizen]
name = "cz_gitmoji"


[tool.coverage]
report.exclude_also = [
  # An `...` *body* (a stub or an abstract method), anchored so it cannot
  # also match an `...` inside a signature -- e.g. `tuple[Any, ...]` or
  # `Int[Array, "..."]`, which excluded the whole function from measurement.
  '^\s*\.\.\.\s*$',
  'if typing.TYPE_CHECKING:',
  'if TYPE_CHECKING:',
]
run.branch = true
run.source = ["unxt"]


# mypy is scoped (via `files`) to the typing smoke fixture -- the same
# `Quantity(1, "m")` constructor guard as pyright ([tool.pyright]) and ty
# ([tool.ty.src]). Widen `files` when more of the tree is mypy-clean.
[tool.mypy]
disallow_incomplete_defs = false
disallow_untyped_defs    = false
enable_error_code        = ["ignore-without-code", "redundant-expr", "truthy-bool"]
files                    = ["tests/typing"]
namespace_packages       = true
python_version           = "3.12"
strict                   = true
warn_return_any          = false
warn_unreachable         = true
warn_unused_configs      = true

[[tool.mypy.overrides]]
disable_error_code       = ["name-defined", "no-redef", "type-arg"]
disallow_incomplete_defs = true
disallow_untyped_defs    = true
module                   = "unxt.*"

[[tool.mypy.overrides]]
ignore_missing_imports = true
module = [
  "astropy.*",
  "equinox.*",
  "hypothesis.*",
  "jax.*",
  "jaxtyping.*",
  "numpy.*",
  "plum.*",
  "quax.*",
  "quaxed.*",
  "unxt.*",
]


# Pyright is scoped to the typing smoke fixture only -- it guards the
# `Quantity(1, "m")` constructor typing (see tests/typing/) without asking the
# whole, not-yet-pyright-clean source tree to pass. Widen `include` when more of
# the tree is type-checked.
[tool.pyright]
include          = ["tests/typing"]
pythonVersion    = "3.12"           # match `requires-python = ">=3.12"`
typeCheckingMode = "basic"


# ty is scoped to the same typing smoke fixture as pyright (the `Quantity(1,
# "m")` constructor guard). Scoping via config -- rather than a CLI path -- keeps
# the nox/pre-commit invocation a plain `ty check`. Python version is read from
# `project.requires-python`. Widen `include` when more of the tree is ty-clean.
[tool.ty.src]
include = ["tests/typing"]


[tool.pylint]
ignore-paths = [".*/_compat.py", ".*/_version.py"]
messages_control.disable = [
  "cyclic-import",              # TODO: resolve
  "design",
  "fixme",
  "abstract-method",
  "function-redefined",         # plum-dispatch
  "invalid-name",               # handled by ruff
  "line-too-long",
  "missing-function-docstring", # TODO: resolve
  "missing-kwoa",               # plum-dispatch
  "missing-module-docstring",
  "no-value-for-parameter",     # plum-dispatch
  "not-callable",               # handled by mypy
  "property-with-parameters",   # handled by ruff
  "protected-access",           # handled by ruff
  "redefined-builtin",          # handled by ruff
  "too-many-function-args",     # plum-dispatch
  "unexpected-keyword-arg",     # plum-dispatch
  "unused-argument",            # handled by ruff
  "unused-import",              # handled by ruff
  "unused-wildcard-import",     # handled by ruff
  "wildcard-import",            # handled by ruff
  "wrong-import-order",         # handled by ruff
  "wrong-import-position",
  "W0221",                      # Arguments in function call differ from overridden method
]
py-version = "3.12"
reports.output-format = "colorized"
similarities.ignore-imports = "yes"

[tool.pylint."FORMAT"]
max-module-lines = 2000


[tool.pytest.ini_options]
addopts = [
  "--arraydiff",
  "--showlocals",
  "--strict-config",
  "--strict-markers",
  # importlib import mode: the monorepo has same-named test files across
  # packages (e.g. test_public_api.py) with no __init__.py, and namespace
  # packages whose leaf dir shadows a real library under prepend mode.
  "--import-mode=importlib",
  "-p no:doctest",           # using sybil
  "-ra",
]
filterwarnings = [
  "error",
  "ignore:Attribute s is deprecated and will be removed in Python 3\\.14:DeprecationWarning", # from Sybil
  "ignore:ast\\.Str is deprecated and will be removed in Python 3\\.14:DeprecationWarning",   # from Sybil
  # pytest
  "ignore:The hookimpl.*uses old-style configuration options:pytest.PytestDeprecationWarning",
  # jax
  "ignore:jax\\.core\\.pp_eqn_rules is deprecated:DeprecationWarning",
  "ignore:jax\\.core\\.Primitive is deprecated:DeprecationWarning",
  "ignore:jax\\.interpreters\\.batching\\.NotMapped is deprecated:DeprecationWarning",
  # Additional potential JAX deprecations for older versions
  "ignore:The numpy\\.array_function protocol:DeprecationWarning",
  "ignore:numpy\\.ndarray size changed:RuntimeWarning",
  # matplotlib (using module pattern to avoid import requirement)
  "ignore::DeprecationWarning:matplotlib",
  # numpy (platform-specific longdouble probe warning during import)
  "ignore:Signature .* for <class 'numpy\\.longdouble'> does not match any known type:UserWarning:numpy\\._core\\.getlimits",
  # pillow
  "ignore:'mode' parameter is deprecated and will be removed in Pillow 13 \\(2026-10-15\\):DeprecationWarning",
  # pyparsing <- matplotlib
  "ignore:'parseAll' argument is deprecated, use 'parse_all':DeprecationWarning",
  # astropy: pytest-xdist workers race to create ~/.astropy/{config,cache} on
  # first import; whichever worker loses the race gets this warning. Category
  # is UserWarning (AstropyUserWarning's base), not the astropy class itself:
  # resolving that name would import astropy, which can re-trigger this same
  # warning before the ignore rule is installed.
  "ignore:XDG_(CONFIG|CACHE)_HOME is set to .*, but the default location, .*, already exists, and takes precedence:UserWarning",
]
log_level = "INFO"
minversion = "8.3"
norecursedirs = [
  ".*",          # ignores .hypothesis, .git, etc.
  "__pycache__",
  "docs/_build",
]
testpaths = [
  # Main package
  "README.md",
  "docs",
  "src/",
  "tests/",
  # unxt-api (a runtime dependency of unxt, so always installed)
  "packages/unxt-api/README.md",
  "packages/unxt-api/src/",
  "packages/unxt-api/tests/",
  # NOTE: unxt-hypothesis is a deprecated shim that is not installed by default
  # (it is no longer in the `workspace` extra), so it is covered only by its own
  # per-package CI job, not by this shared sweep.
]
xfail_strict = true


[tool.pytest_env]
UNXT_ENABLE_RUNTIME_TYPECHECKING = "beartype.beartype"
# Force matplotlib's non-interactive backend so the interop tests never load a
# GUI toolkit (e.g. Tk). The Windows hosted-runner Pythons (3.13/3.14) ship a
# broken Tcl, so an auto-selected TkAgg backend raised `_tkinter.TclError` at
# figure creation; Agg is also what `pytest-mpl` renders with.
MPLBACKEND = "Agg"


[tool.repo-review]
ignore = ["PC140", "PC901", "PC902", "PC903"]


[tool.ruff]
namespace-packages = [
  "packages/unxts.api/src/unxts",
  "packages/unxts.hypothesis/src/unxts",
  "packages/unxts.interop.gala/src/unxts",
  "packages/unxts.interop.gala/src/unxts/interop",
  "packages/unxts.interop.matplotlib/src/unxts",
  "packages/unxts.interop.matplotlib/src/unxts/interop",
  "packages/unxts.interop.xarray/src/unxts",
  "packages/unxts.interop.xarray/src/unxts/interop",
  "packages/unxts.linalg/src/unxts",
  "packages/unxts.parametric/src/unxts",
]

[tool.ruff.lint]
extend-select = ["ALL"]
ignore = [
  "A002",    # Argument is shadowing a Python builtin
  "ANN401",  # Dynamically typed expressions (typing.Any) are disallowed
  "ARG001",  # Unused function argument  # TODO: resolve
  "COM812",  # <- for ruff.format
  "D103",    # Missing docstring in public function  # TODO: resolve
  "D105",    # Missing docstring in magic method
  "D107",    # Missing docstring in __init__
  "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
  "N806",    # Variable in function should be lowercase
  "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
  "TD002",   # Missing author in TODO
  "TD003",   # Missing issue link on the line following this TODO
  # PEP 695 `type X = ...` aliases become runtime `TypeAliasType` objects.
  # `beartype.door.TypeHint` has no `TypeAliasType` case (verified against the
  # beartype pinned in uv.lock and its current dev branch) and raises
  # `BeartypeDoorNonpepException`; plum's `Signature.__eq__` calls it unguarded,
  # so converting a *dispatch-key* alias hard-crashes the beartype-enabled
  # import. A *recursive/parametric* alias is
  # worse: used as a beartype-checked annotation it raises
  # `BeartypeDecorHintForwardRefException` on its own forward reference. unxt's
  # aliases are dispatch keys and runtime-checked annotations, so they must stay
  # `X: TypeAlias = ...` until the upstream gap is closed (beartype.door or plum
  # unwrapping `TypeAliasType.__value__`, which already resolves correctly). (The
  # `>=3.12` floor is what makes ruff start suggesting the incompatible form.)
  "UP040", # Type alias uses `TypeAlias` instead of the `type` keyword
]

[tool.ruff.lint.per-file-ignores]
"**docs/**"  = ["A001", "INP001"]
"**tests/**" = ["ANN", "D401", "E731", "INP001", "S101", "SLF001", "T20"]
# `Qcls` is a class-valued fixture parametrized over the quantity classes; the
# capitalized name (and using it as a constructor) is intentional.
"**packages/unxts.parametric/tests/unit/test_interchangeability.py" = [
  "N802",
  "N803",
  "N806",
  "PLC0415",
]
# `unxts.linalg` ports dense, doctest-heavy internal linear-algebra code. These
# relaxations match how the module was written (private unit-array access, JAX
# primitive registrations named `*_p_QuantityMatrix`, the `.T` transpose
# property, and long doctest-output/error-message lines).
"**packages/unxts.linalg/src/**" = [
  "E501",   # Line too long (doctest output / error messages)
  "EM101",  # Exception must not use a string literal
  "EM102",  # Exception must not use an f-string literal
  "N802",   # Function name should be lowercase (`.T`, `*_p_QuantityMatrix`)
  "SLF001", # Private member access (`UnitsMatrix._units`, by design)
  "TRY003", # Avoid specifying long messages outside the exception class
  "TRY004", # Prefer `TypeError` (intentional `ValueError` for ragged/units)
]
"**packages/unxts.linalg/tests/**" = [
  "D102",   # Missing docstring in public method
  "N802",   # Test names embed `QuantityMatrix`/`1D`/`2D`
  "RUF002", # Docstring contains ambiguous `×` (math notation)
  "RUF003", # Comment contains ambiguous character
]
"__init__.py" = ["F403"]
"noxfile.py" = ["T20"]

[tool.ruff.lint.flake8-import-conventions.aliases]
equinox                 = "eqx"
"hypothesis.strategies" = "st"
unxt                    = "u"
unxt_api                = "uapi"
unxt_hypothesis         = "ust"

[tool.ruff.lint.isort]
combine-as-imports = true
extra-standard-library = ["typing_extensions"]
known-first-party = [
  "dataclassish",
  "is_annotated",
  "optional_dependencies",
  "quaxed",
  "zeroth",                # used by the unxts.interop.matplotlib subpackage
]
known-local-folder = ["unxt", "unxt_api", "unxt_hypothesis"]

[tool.ruff.format]
docstring-code-format = true


[tool.uv]
constraint-dependencies = ["matplotlib>=3.10.8; python_version>='3.14'"]
# Require that `unxt[<jax-extras>]` requirements are resolved in different forks
# so that they cannot conflict with one another.
conflicts = [
  [
    { extra = "cpu" },
    { extra = "cuda" },
    { extra = "cuda12" },
    { extra = "cuda12_local" },
    { extra = "k8s" },
  ],
]

[tool.uv.sources]
unxt-api                   = { workspace = true }
unxt-hypothesis            = { workspace = true }
"unxts.api"                = { workspace = true }
"unxts.hypothesis"         = { workspace = true }
"unxts.interop.gala"       = { workspace = true }
"unxts.interop.matplotlib" = { workspace = true }
"unxts.interop.xarray"     = { workspace = true }
"unxts.linalg"             = { workspace = true }
"unxts.parametric"         = { workspace = true }

[tool.uv.workspace]
members = ["packages/*"]