pyproject.toml

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

[project]
name = "scanpy"
description = "Single-Cell Analysis in Python."
readme = "README.md"
license = "BSD-3-clause"
maintainers = [
    { name = "Ilan Gold", email = "ilan.gold@helmholtz-munich.de" },
    { name = "Philipp Angerer", email = "phil.angerer@helmholtz-munich.de" },
    { name = "Severin Dicks", email = "severin.dicks@scverse.org" },
]
authors = [
    { name = "Adam Gayoso" },
    { name = "Alex Wolf" },
    { name = "Andrés R. Muñoz-Rojas" },
    { name = "Davide Cittaro" },
    { name = "Fidel Ramirez" },
    { name = "Giovanni Palla" },
    { name = "Gokcen Eraslan" },
    { name = "Ilan Gold" },
    { name = "Isaac Virshup" },
    { name = "Lukas Heumos" },
    { name = "Malte Luecken" },
    { name = "Marius Lange" },
    { name = "Philipp Angerer" },
    { name = "Sergei Rybakov" },
    { name = "Tobias Callies" },
    { name = "Tom White" },
]
requires-python = ">=3.12"
classifiers = [
    "Development Status :: 5 - Production/Stable",
    "Environment :: Console",
    "Framework :: Jupyter",
    "Intended Audience :: Developers",
    "Intended Audience :: Science/Research",
    "License :: OSI Approved :: BSD License",
    "Natural Language :: English",
    "Operating System :: MacOS :: MacOS X",
    "Operating System :: Microsoft :: Windows",
    "Operating System :: POSIX :: Linux",
    "Programming Language :: Python :: 3 :: Only",
    "Programming Language :: Python :: 3.12",
    "Programming Language :: Python :: 3.13",
    "Programming Language :: Python :: 3.14",
    "Topic :: Scientific/Engineering :: Bio-Informatics",
    "Topic :: Scientific/Engineering :: Visualization",
]
dynamic = [ "version" ]
dependencies = [
    "anndata>=0.10.8",
    "certifi",
    "fast-array-utils[accel,sparse]>=1.4",
    "h5py>=3.11",
    "joblib",
    "matplotlib>=3.9",
    "natsort",
    "networkx>=2.8.8",
    "numba>=0.60",
    "numpy>=2",
    "packaging>=25",
    "pandas>=2.3",
    "patsy",
    "pynndescent>=0.5.13",
    "scikit-learn>=1.6",
    "scipy>=1.13",
    "seaborn>=0.13.2",
    "session-info2",
    "statsmodels>=0.14.5",
    "tqdm",
    "typing-extensions; python_version<'3.13'",
    "umap-learn>=0.5.12",
]
urls.Bluesky = "https://bsky.app/profile/scverse.bsky.social"
urls.Discourse = "https://discourse.scverse.org/c/help/scanpy/37"
urls.Documentation = "https://scanpy.readthedocs.io/"
urls.Homepage = "https://scanpy.org"
urls.Source = "https://github.com/scverse/scanpy"
urls.Twitter = "https://x.com/scverse_team"
scripts.scanpy = "scanpy.cli:console_main"

[project.optional-dependencies]
bbknn = [ "bbknn" ]
dask = [ "anndata[dask]", "dask[array]>=2024.5.1" ]
# PCA acceleration
dask-ml = [ "dask-ml", "scanpy[dask]" ]
harmony = [ "harmonypy" ]
leiden = [ "igraph>=0.10.8", "leidenalg>=0.10.1" ]
louvain = [ "igraph", "louvain>=0.8.2", "setuptools" ]
magic = [ "magic-impute>=2.0.4" ]
paga = [ "igraph" ]
plotting = [ "colour-science" ]
scanorama = [ "scanorama" ]
scrublet = [ "scikit-image>=0.23.1" ]
# highly_variable_genes method 'seurat_v3'
skmisc = [ "scikit-misc>=0.5.1" ]
scanpy2 = [ "igraph>=0.10.8", "scikit-misc>=0.5.1" ]

[dependency-groups]
dev = [
    "scipy-stubs", # static typing and IDE support
    "towncrier",   # release note management
]
test = [
    "scanpy[dask-ml]",
    "scanpy[dask]",
    "scanpy[leiden]",
    "scanpy[plotting]",
    "scanpy[scrublet]",
    "scanpy[skmisc]",
    "zarr>=2.18.7",
    { include-group = "test-min" },
]
doc = [
    "ipython>=7.20",                        # for nbsphinx code highlighting
    "myst-nb>=1",
    "myst-parser>=2",
    "nbsphinx>=0.9",
    "numpy>=2.4",                           # type aliases
    "sam-algorithm",
    # TODO: remove necessity for being able to import doc-linked classes
    "scanpy[dask-ml,leiden,paga,plotting]",
    "scanpydoc>=0.16.1",
    "sphinx>=9.1",
    "sphinx-autodoc-typehints>=1.25.2",
    "sphinx-book-theme>=1.1",
    "sphinx-copybutton",
    "sphinx-design",
    "sphinx-issues>=5.0.1",
    "sphinxcontrib-bibtex",
    "sphinxcontrib-katex",
    "sphinxext-opengraph",                  # for nice cards when sharing on social
]
test-min = [
    "dependency-groups",    # for CI scripts doctests
    "pytest",
    "pytest-cov",           # only for use from VS Code
    "pytest-mock",
    "pytest-randomly",
    "pytest-rerunfailures",
    "pytest-xdist[psutil]",
    "tuna",
]

[tool.hatch]
build.targets.wheel.packages = [ "src/testing", "src/scanpy" ]
version.source = "vcs"
version.raw-options.version_scheme = "release-branch-semver"

[tool.ruff]
src = [ "src" ]
format.preview = true
format.docstring-code-format = true
lint.select = [
    "B",      # Likely bugs and design issues
    "BLE",    # Blind exception raised
    "C4",     # Comprehensions
    "D",      # Documentation style
    "E",      # Error detected by Pycodestyle
    "EM",     # Traceback-friendly error messages
    "F",      # Errors detected by Pyflakes
    "FBT",    # No positional boolean parameters
    "I",      # Import sorting
    "ICN",    # Follow import conventions
    "ISC",    # Implicit string concatenation
    "N",      # Naming conventions
    "PD",     # Pandas
    "PERF",   # Performance
    "PIE",    # Syntax simplifications
    "PL",     # Pylint
    "PT",     # Pytest style
    "PTH",    # Pathlib instead of os.path
    "PYI",    # Typing
    "RUF",    # Miscellaneous Ruff-only lints
    "SIM",    # Simplify control flow
    "TC",     # Manage type checking blocks
    "TID251", # Banned imports
    "UP",     # Update legacy syntax
    "W",      # Warning detected by Pycodestyle
]
lint.ignore = [
    "C408",    # dict() syntax is preferrable when creating dicts for kwargs
    "D203",    # We ban blank lines before docstrings instead of the opposite
    "D213",    # We want multiline summaries to start on the first line, not the second
    "D417",    # TODO: replace our current param docs reuse with this and remove it here:
    "E262",    # E266 too many leading '#' for block comment -> Scanpy allows them for comments into sections
    "E402",    # module level import not at top of file -> required to circumvent circular imports for Scanpys API
    "E501",    # line too long -> we accept long comment lines; black gets rid of long code lines
    "E741",    # allow I, O, l as variable names -> I is the identity matrix, i, j, k, l is reasonable indexing notation
    "PLC0415", # Imports in functions are pretty important for us
    "PLR2004", # Numbers like “2” aren’t that “magic”.
    "PYI051",  # `Literal["..."] | str` is useful for autocompletion
]
# No need for docstrings for all benchmarks
lint.per-file-ignores."benchmarks/**/*.py" = [ "D102", "D103" ]
# Do not assign a lambda expression, use a def
lint.per-file-ignores."src/scanpy/tools/_rank_genes_groups.py" = [ "E731" ]
# Old and unmaintained
lint.per-file-ignores."src/scanpy/tools/_sim.py" = [ "N" ]
# D*: No need for docstrings for all test modules and test functions
# PLR0913: Test may use many fixtures
lint.per-file-ignores."tests/**/*.py" = [ "D100", "D101", "D103", "PLR0913" ]
lint.allowed-confusables = [ "×", "–", "‘", "’", "α" ]
lint.external = [ "PLR0917" ]
lint.flake8-bugbear.extend-immutable-calls = [ "scanpy._settings.Default" ]
lint.flake8-type-checking.exempt-modules = []
lint.flake8-type-checking.strict = true
lint.isort.known-first-party = [ "scanpy", "testing.scanpy" ]
lint.isort.required-imports = [ "from __future__ import annotations" ]
lint.pydocstyle.convention = "numpy"
lint.pylint.max-args = 10
lint.pylint.max-positional-args = 5

[tool.ruff.lint.flake8-tidy-imports.banned-api]
"numba.jit".msg = "Use `fast_array_utils.numba.njit` instead"
"numba.njit".msg = "Use `fast_array_utils.numba.njit` instead"
"numpy.bool_".msg = "Use `np.bool` instead"
"pandas.api.types.is_categorical_dtype".msg = "Use isinstance(s.dtype, CategoricalDtype) instead"
"pandas.value_counts".msg = "Use pd.Series(a).value_counts() instead"
"pytest.importorskip".msg = "Use the “@needs” decorator/mark instead"
"scipy.sparse.csc_array".msg = "Use _compat.CSCBase or _compat.CSBase for typing/type checks and add `# noqa: TID251` when constructing"
"scipy.sparse.csc_matrix".msg = "Use _compat.CSCBase or _compat.CSBase for typing/type checks and add `# noqa: TID251` when constructing"
"scipy.sparse.csr_array".msg = "Use _compat.CSRBase or _compat.CSBase for typing/type checks and add `# noqa: TID251` when constructing"
"scipy.sparse.csr_matrix".msg = "Use _compat.CSRBase or _compat.CSBase for typing/type checks and add `# noqa: TID251` when constructing"
"scipy.sparse.issparse".msg = "Use isinstance(_, _compat.CSBase) or isinstance(_, _compat.SpBase) instead"
"scipy.sparse.sparray".msg = "Use _compat.SpBase instead"
"scipy.sparse.spmatrix".msg = "Use _compat.SpBase instead"
"warnings.warn".msg = "Use `scanpy._compat.warn` instead"

[tool.pyproject-fmt]
indent = 4
table_format = "short"
expand_tables = [
    "project.optional-dependencies",
    "tool.ruff.lint.flake8-tidy-imports.banned-api",
]

[tool.pytest]
strict = true
addopts = [
    "--import-mode=importlib",
    "--strict-markers",
    "--doctest-modules",
    "-ptesting.scanpy._pytest",
    "--pyargs",
]
testpaths = [ "./tests", "./ci", "scanpy" ]
norecursedirs = [ "tests/_images" ]
junit_family = "xunit1"
markers = [
    "internet: tests which rely on internet resources (enable with `--internet-tests`)",
    "gpu: tests that use a GPU (unused, required by anndata.tests.helpers)",
    "array_api: tests that use array_api (unused, required by anndata.tests.helpers)",
]
filterwarnings = [
    "error",
    # Umap warns when tensorflow isn’t installed.
    "ignore::ImportWarning:umap",
    # seaborn≤0.13.2 causes some matplotlib warnings
    "ignore::PendingDeprecationWarning:seaborn",
    # matplotlib<3.10.4 causes a Pillow warning
    "ignore:.*Pillow:DeprecationWarning",
    # networkx 2.x warns about scipy.sparse changes
    "ignore:\\n*.*scipy\\.sparse array:DeprecationWarning:networkx",
    # h5py <3.9 uses deprecated np.product
    "ignore:.*product.*deprecated.*NumPy:DeprecationWarning",
    # old anndata versions have this
    "ignore:is_categorical_dtype is deprecated:FutureWarning",
    # Ignore numba PEP 456 warning specific to ARM machines
    "ignore:FNV hashing is not implemented in Numba.*:UserWarning",
    # we want to see and eventually fix these
    "default::numba.core.errors.NumbaPerformanceWarning",
    "default:.*TSNE.*random.*to.*pca:FutureWarning",                       # we should set init=obsm["X_pca"] or so
    # matplotlib <3.11 uses old pyparsing APIs
    "ignore::pyparsing.warnings.PyparsingDeprecationWarning",
    # igraph vs leidenalg warning
    "ignore:The `igraph` implementation of leiden clustering:UserWarning",
    # everybody uses this zarr 3 feature, including us, XArray, lots of data out there …
    "ignore:Consolidated metadata is currently not part:UserWarning",
    # joblib fallback to serial mode in restricted multiprocessing environments
    "ignore:.*joblib will operate in serial mode:UserWarning",
]

[tool.coverage]
run.concurrency = [ "multiprocessing" ]
run.data_file = "test-data/raw-coverage"
run.omit = [ "src/testing/*", "tests/*" ]
run.patch = [ "subprocess" ]
run.source_pkgs = [ "scanpy" ]
paths.source = [ "src", "**/site-packages" ]
report.exclude_also = [
    # https://github.com/numba/numba/issues/4268
    "@([\\w.]+.)?njit.*",
    "@deprecated.*",
    "if __name__ == .__main__.:",
    "if TYPE_CHECKING:",
]
xml.output = "test-data/coverage.xml"

[tool.towncrier]
name = "scanpy"
package = "scanpy"
directory = "docs/release-notes"
filename = "docs/release-notes/{version}.md"
single_file = false
package_dir = "src"
issue_format = "{{pr}}`{issue}`"
title_format = "(v{version})=\n### {version} {{small}}`{project_date}`"
# Valid fragments should be a subset of conventional commit types (except for `breaking`):
# https://github.com/commitizen/conventional-commit-types/blob/master/index.json
# style, refactor, test, build, ci: should not go into changelog
fragment.feat.name = "Features"
fragment.fix.name = "Bug fixes"
fragment.docs.name = "Documentation"
fragment.perf.name = "Performance"
fragment.chore.name = "Miscellaneous changes"
fragment.revert.name = "Revert"
fragment.breaking.name = "Breaking changes"  # add `!` to commit type (e.g. “feature!:”)