pyproject.toml

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

[project]
name = "spatialdata"
description = "Spatial data format."
readme = "README.md"
license = { file = "LICENSE" }
maintainers = [
  { name = "Luca Marconato", email = "luca.marconato@scverse.org" },
  { name = "Wouter Vierdag", email = "michiel.vierdag@scverse.org" },
  { name = "Tomaz Vieira", email = "tomaz.vieira@embl.de" },
  { name = "Ajayrama Kumaraswamy", email = "ajayrama.kumaraswamy@embl.de" },
]
authors = [
  { name = "scverse" },
]
requires-python = ">=3.12"
classifiers = [
  "Programming Language :: Python :: 3 :: Only",
  "Programming Language :: Python :: 3.12",
  "Programming Language :: Python :: 3.13",
  "Programming Language :: Python :: 3.14",
  "Typing :: Typed",
]
dynamic = [ "version" ]
dependencies = [
  "anndata>=0.9.1",
  "annsel>=0.1.2",
  "click",
  "dask>=2026.3",
  "dask-image",
  "datashader",
  "distributed>=2026.3",
  "fsspec[http,s3]",
  "geopandas>=0.14",
  "multiscale-spatial-image==2.0.3",
  "networkx",
  "numba>=0.55",
  "numpy",
  "ome-zarr>=0.16",
  "pandas",
  "pooch",
  "pyarrow",
  "rich",
  "scikit-image",
  "scipy!=1.17",
  "scverse-misc[datasets]>=0.1",
  "shapely>=2.0.1",
  "spatial-image>=1.2.3",
  "typing-extensions>=4.8",
  "universal-pathlib>=0.2.6",
  "xarray>=2024.10",
  "xarray-spatial>=0.3.5",
  "zarr>=3",
]
optional-dependencies.extra = [
  "napari-spatialdata[all]",
  "spatialdata-io",
  "spatialdata-plot",
]
optional-dependencies.torch = [
  "torch",
]
urls.Documentation = "https://spatialdata.scverse.org/en/latest"
urls.Homepage = "https://github.com/scverse/spatialdata"
urls.Source = "https://github.com/scverse/spatialdata"

[dependency-groups]
dev = [
  "twine>=4.0.2",
]
test = [
  "coverage>=7.10",
  "pytest",
  "pytest-cov",     # For VS Code’s coverage functionality
  "pytest-mock",
  "pytest-xdist",
  "torch",
]
benchmark = [
  "asv",
  "memray",
  "profimp",
]
doc = [
  "ipykernel",
  "ipython>=8.6",
  "myst-nb>=1.1",
  "pandas",
  "scanpydoc",
  "scverse-misc[sphinx]>=0.1.2",
  "sphinx>=8.1",
  "sphinx-autobuild",
  "sphinx-autodoc-typehints",
  "sphinx-book-theme>=1",
  "sphinx-copybutton",
  "sphinx-design",
  "sphinx-pytest",
  "sphinxcontrib-bibtex>=1",
  "sphinxcontrib-katex",
  "sphinxext-opengraph",
]
typecheck = [
  "mypy",
  "pandas-stubs",
  "scipy-stubs",
  "types-geopandas",
  "types-networkx",
  "types-requests",
  "types-shapely",
]

[tool.hatch]
version.source = "vcs"
metadata.allow-direct-references = true
build.hooks.vcs.version-file = "_version.py"
build.targets.wheel.packages = [ "src/spatialdata" ]
envs.default.installer = "uv"
envs.default.dependency-groups = [ "dev" ]
envs.docs.features = [ "torch" ]
envs.docs.scripts.build = "sphinx-build -M html docs docs/_build -W {args}"
envs.docs.scripts.clean = "git clean -fdX -- {args:docs}"
envs.docs.scripts.open = "python -m webbrowser -t docs/_build/html/index.html"
envs.docs.dependency-groups = [ "doc" ]
envs.hatch-test.matrix = [
  # Test the lowest and highest supported Python versions with normal deps
  { deps = [ "stable" ], python = [ "3.12", "3.14" ] },
  # Test the lowest supported versions of the dependencies we pin a floor for
  { deps = [ "min" ], python = [ "3.12" ] },
  # Test the newest supported Python version also with pre-release deps
  { deps = [ "pre" ], python = [ "3.14" ] },
]
# If the matrix variable `deps` is set to "pre", set the environment variable `UV_PRERELEASE` to "allow".
envs.hatch-test.overrides.matrix.deps.env-vars = [
  { value = "allow", key = "UV_PRERELEASE", if = [ "pre" ] },
]
# If the matrix variable `deps` is set to "min", pin the dependencies to their declared floor.
envs.hatch-test.overrides.matrix.deps.extra-dependencies = [
  { value = "dask==2026.3.0", if = [ "min" ] },
  { value = "distributed==2026.3.0", if = [ "min" ] },
]
envs.hatch-test.dependency-groups = [ "dev", "test" ]
envs.hatch-check-fmt.dependencies = [ "prek" ]
envs.hatch-check-fmt.scripts.format-check = "echo 'try `hatch check fmt --fix`'; false"
envs.hatch-check-fmt.scripts.format-fix = "prek run -a --group=format --no-group=typecheck"
envs.hatch-check-code.dependencies = [ "prek" ]
envs.hatch-check-code.scripts.lint-check = "echo 'try `hatch check code --fix`'; false"
envs.hatch-check-code.scripts.lint-fix = "prek run -a --no-group=format --no-group=typecheck"
envs.hatch-check-types.scripts.check = [ "mypy" ]
envs.hatch-check-types.dependency-groups = [ "typecheck", "test" ]
# Not part of the CI matrix; run locally with `hatch run test-anndata-pandas:test`.
envs.test-anndata-pandas.extra-dependencies = [ "zarr>=3" ]
envs.test-anndata-pandas.scripts.test = [ "pip list|grep anndata && pip list|grep pandas && pytest {args}" ]
envs.test-anndata-pandas.scripts.test-all = [ "pip list|grep anndata && pip list|grep pandas && pytest ." ]
envs.test-anndata-pandas.scripts.test-readwrite = [
  "pip list|grep anndata && pip list|grep pandas && pytest tests/io/test_readwrite.py"
]
envs.test-anndata-pandas.matrix = [
  { anndata-pandas = [
    "0.13-2",
    "0.13-3",
    "0.12-2",
    # no "0.12-3": support for pandas>=3 is available only in anndata>=0.13
  ] },
]
# every option where the if-condition is True gets included
envs.test-anndata-pandas.overrides.matrix.anndata-pandas.extra-dependencies = [
  # anndata 0.13
  { value = "anndata~=0.13", if = [ "0.13-2", "0.13-3" ] },
  # anndata 0.12
  { value = "anndata>=0.12,<0.13", if = [ "0.12-2" ] },
  # pandas 2
  { value = "pandas>=2.3,<3", if = [ "0.13-2", "0.12-2" ] },
  # pandas 3
  { value = "pandas~=3.0", if = [ "0.13-3" ] },
]
envs.test-anndata-pandas.dependency-groups = [ "dev", "test" ]

[tool.pixi]
workspace.channels = [ "conda-forge" ]
workspace.platforms = [ "linux-64", "osx-arm64" ]
dependencies.proj = "*"
tasks.pre-commit = "prek run"
tasks.pre-commit-all = "prek run --all-files"
tasks.test = "pytest"
tasks.test-parallel = "pytest -n auto --dist worksteal"
feature.profiling.dependencies.py-spy = "*"
feature.profiling.pypi-dependencies.memray = "*"
feature.profiling.pypi-dependencies.profimp = "*"
feature.profiling.pypi-dependencies.spatialdata = { path = ".", editable = true }
# Usage: pixi run -e profiling memray-flame memray-script.py.<pid>.bin
feature.profiling.tasks.memray-flame = "memray flamegraph --temporal"
# Usage: pixi run -e profiling memray-run script.py
feature.profiling.tasks.memray-run = "memray run"
# Usage: pixi run -e profiling pyspy script.py  (prefix with sudo on macOS)
feature.profiling.tasks.pyspy = "py-spy record --gil -o profile.speedscope.json --format speedscope -- python"
# Usage: pixi run -e profiling speedscope
feature.profiling.tasks.speedscope = "npx --yes speedscope profile.speedscope.json"
environments.profiling = { features = [ "profiling" ], solve-group = "default" }

[tool.ruff]
line-length = 120
src = [ "src" ]
extend-include = [ "*.ipynb" ]
format.docstring-code-format = true
lint.select = [
  "B",      # flake8-bugbear
  "BLE",    # flake8-blind-except
  "C4",     # flake8-comprehensions
  "D",      # pydocstyle
  "E",      # Error detected by Pycodestyle
  "F",      # Errors detected by Pyflakes
  "I",      # isort
  "NPY",    # NumPy-specific rules
  "PGH",    # pygrep-hooks
  "PT",     # flake8-pytest-style
  "Q",      # flake8-quotes
  "RET",    # flake8-return
  "RUF100", # Report unused noqa directives
  "SIM",    # flake8-simplify
  "T20",    # flake8-print
  "TID",    # flake8-tidy-imports
  "UP",     # pyupgrade
  "W",      # Warning detected by Pycodestyle
]
lint.ignore = [
  "B008", # Errors from function calls in argument defaults. These are fine when the result is immutable.
  "D100", # Missing docstring in public module
  "D104", # Missing docstring in public package
  "D105", # __magic__ methods are often self-explanatory, allow missing docstrings
  "D107", # Missing docstring in __init__
  # Disable one in each pair of mutually incompatible rules
  "D203", # We don’t want a blank line before a class docstring
  "D213", # <> We want docstrings to start immediately after the opening triple quote
  "D400", # first line should end with a period [Bug: doesn’t work with single-line docstrings]
  "D401", # First line should be in imperative mood; try rephrasing
  "E501", # line too long -> we accept long comment lines; formatter gets rid of long code lines
  "E731", # Do not assign a lambda expression, use a def -> lambda expression assignments are convenient
  "E741", # allow I, O, l as variable names -> I is the identity matrix
]
lint.per-file-ignores."*/__init__.py" = [ "D104", "D107", "E402", "F401" ]
lint.per-file-ignores."benchmarks/*" = [ "ALL" ]
lint.per-file-ignores."docs/*" = [ "A", "B", "D", "E", "I" ]
lint.per-file-ignores."src/spatialdata/dataloader/datasets.py" = [ "D101" ]
lint.per-file-ignores."src/spatialdata/models/models.py" = [ "B026", "D101" ]
lint.per-file-ignores."src/spatialdata/transformations/*" = [ "D", "RET", "UP006", "UP007" ]
lint.per-file-ignores."src/spatialdata/transformations/ngff/*.py" = [
  "D101",
  "D102",
  "D106",
  "RET504",
  "RET505",
  "RET506",
  "UP006",
  "UP007"
]
lint.per-file-ignores."src/spatialdata/transformations/operations.py" = [
  "B024",
  "D101",
  "D102",
  "D106",
  "RET504",
  "RET505",
  "RET506",
  "T201",
  "UP006",
  "UP007"
]
lint.per-file-ignores."src/spatialdata/transformations/transformations.py" = [
  "B024",
  "D101",
  "D102",
  "D106",
  "RET504",
  "T201",
  "UP006",
  "UP007"
]
lint.per-file-ignores."tests/*" = [ "B024", "D", "PT" ]
lint.per-file-ignores."tests/conftest.py" = [ "E402" ]
lint.per-file-ignores."tests/test_models/test_models.py" = [ "NPY002" ]
lint.unfixable = [ "B", "BLE", "C4", "RET", "T20", "UP" ]
lint.isort.required-imports = [ "from __future__ import annotations" ]
lint.pydocstyle.convention = "numpy"

[tool.mypy]
# TODO: extend to "tests" once the test suite carries type annotations.
files = [ "src" ]
python_version = "3.12"
disallow_any_generics = true
disallow_untyped_calls = false
disallow_untyped_defs = true
disallow_incomplete_defs = true
check_untyped_defs = true
strict_optional = true
warn_redundant_casts = true
warn_unused_ignores = false
warn_return_any = true
warn_unreachable = false
ignore_errors = false
strict_equality = true
show_column_numbers = true
error_summary = true
warn_unused_configs = true
# because of docrep
allow_untyped_decorators = true
no_implicit_optional = true
no_implicit_reexport = true
no_warn_no_return = true
show_error_codes = true

# Installed, but shipping no `py.typed` marker.
# Infer types from their source instead of falling back to `Any`.
[[tool.mypy.overrides]]
module = [
  "annsel.*",
  "dask_image.*",
  "datashader.*",
  "multiscale_spatial_image.*",
  "numcodecs.*",
  "ome_zarr.*",
  "pooch.*",
  "pyarrow.*",
  "spatial_image.*",
  "xrspatial.*",
]
follow_untyped_imports = true
# `no_implicit_reexport` is meant to discipline our own public API.
# Third-party packages re-export freely, so applying it to them only produces false positives.
implicit_reexport = true

# Optional dependencies that are not installed when the type check runs.
[[tool.mypy.overrides]]
module = [
  "matplotlib.*",
  "spatialdata_io.*",
]
ignore_missing_imports = true

[tool.pytest]
addopts = [
  "--import-mode=importlib", # allow using test files with same name
  "-s",                      # print output from tests
  # napari registers a pytest plugin via its entry point; disable it here since spatialdata tests don't need it
  "-p no:napari",
]
# info on how to use this https://stackoverflow.com/questions/57925071/how-do-i-avoid-getting-deprecationwarning-from-inside-dependencies-with-pytest
filterwarnings = [
  # "error",  # if 3rd party libs raise DeprecationWarnings, TODO: filter them individually below
  # "ignore:.*U.*mode is deprecated:DeprecationWarning",
]
# These are all markers coming from xarray, dask or anndata. Added here to silence warnings.
markers = [
  "slow: marks tests as slow (deselect with '-m \"not slow\"')",
  "network: marks tests that require network access; skipped by default, run with '--run-network'",
  "gpu: run test on GPU using CuPY.",
  "array_api: used by anndata.tests.helpers, not us",
  "skip_with_pyarrow_strings: skipwhen pyarrow string conversion is turned on",
]
strict = true
testpaths = [ "tests" ]

[tool.coverage]
run.source = [ "spatialdata" ]
run.omit = [
  "**/test_*.py",
]
run.patch = [ "subprocess" ]

[tool.cruft]
skip = [
  ".git",
  "tests",
  "src/**/__init__.py",
  "src/**/basic.py",
  "docs/api.md",
  "docs/changelog.md",
  "docs/references.bib",
  "docs/references.md",
  "docs/notebooks/example.ipynb",
]

[tool.jupytext]
formats = "ipynb,md"