pyproject.toml

[project]
authors = [{ name = "xarray Developers", email = "xarray@googlegroups.com" }]
classifiers = [
  "Development Status :: 5 - Production/Stable",
  "Operating System :: OS Independent",
  "Intended Audience :: Science/Research",
  "Programming Language :: Python",
  "Programming Language :: Python :: 3",
  "Programming Language :: Python :: 3.12",
  "Programming Language :: Python :: 3.13",
  "Programming Language :: Python :: 3.14",
  "Topic :: Scientific/Engineering",
]
description = "N-D labeled arrays and datasets in Python"
dynamic = ["version"]
license = "Apache-2.0"
name = "xarray"
readme = "README.md"
requires-python = ">=3.12"

dependencies = ["numpy>=2.2", "packaging>=25.0", "pandas>=2.3"]

# We don't encode minimum requirements here (though if we can write a script to
# generate the text from `min_deps_check.py`, that's welcome...). We do add
# `numba>=0.54` here because of https://github.com/astral-sh/uv/issues/7881;
# note that it's not a direct dependency of xarray.

[project.optional-dependencies]
accel = [
  "scipy>=1.16",
  "bottleneck",
  "numbagg>=0.9,!=0.9.5", # 0.9.5 breaks dask.array.nanmedian
  "numba>=0.62",          # numba 0.62 added support for numpy 2.3
  "flox>=0.10",
  "opt_einsum",
]
complete = ["xarray[accel,etc,io,parallel,viz]"]
io = [
  "netCDF4>=1.7.0",
  # h5netcdf 1.8.0 introduced a few compatibility features with netcdf4
  # https://github.com/pydata/xarray/issues/10657#issuecomment-3711095986
  "h5netcdf[h5py]>=1.8.0",
  "pydap",
  "scipy>=1.16",
  "zarr>=3.1",
  "fsspec",
  "cftime",
  "pooch",
]
arrow = ["pyarrow"]
etc = ["sparse>=0.17"]
parallel = ["dask[complete]"]
viz = ["cartopy>=0.25", "matplotlib>=3.10", "nc-time-axis", "seaborn"]
types = [
  "pandas-stubs",
  "scipy-stubs",
  "types-colorama",
  "types-decorator",
  "types-defusedxml",
  "types-docutils",
  "types-gevent",
  "types-networkx",
  "types-openpyxl",
  "types-pexpect",
  "types-psutil",
  "types-pycurl",
  "types-Pygments",
  "types-pysocks",
  "types-python-dateutil",
  "types-pytz",
  "types-PyYAML",
  "types-requests",
  "types-setuptools",
  "types-xlrd",
]

[dependency-groups]
dev = [
  "hypothesis",
  "jinja2",
  "mypy==2.4.0",
  "pre-commit",
  "pytest",
  "pytest-cov",
  "pytest-env",
  "pytest-mypy-plugins>=4.0.0",
  "pytest-timeout",
  "pytest-xdist",
  "pytest-asyncio",
  "pytz",
  "ruff>=0.15.0",
  "sphinx",
  "sphinx_autosummary_accessors",
  "xarray[complete,types]",
]

[project.urls]
Documentation = "https://docs.xarray.dev"
SciPy2015-talk = "https://www.youtube.com/watch?v=X0pAhJgySxk"
homepage = "https://xarray.dev/"
issue-tracker = "https://github.com/pydata/xarray/issues"
source-code = "https://github.com/pydata/xarray"

[project.entry-points."xarray.chunkmanagers"]
dask = "xarray.namedarray.daskmanager:DaskManager"

[build-system]
build-backend = "setuptools.build_meta"
requires = ["setuptools>=80", "setuptools-scm>=10", "vcs_versioning"]

[tool.setuptools.packages.find]
include = ["xarray*"]

[tool.vcs-versioning]
fallback_version = "9999"

[tool.coverage.run]
omit = [
  "*/xarray/tests/*",
  "*/xarray/compat/dask_array_compat.py",
  "*/xarray/compat/pdcompat.py",
  "*/xarray/namedarray/pycompat.py",
  "*/xarray/core/types.py",
  "*/xarray/util/generate_*.py",
]
source = ["xarray"]

[tool.coverage.report]
exclude_lines = ["pragma: no cover", "if TYPE_CHECKING"]

[tool.mypy]
enable_error_code = ["ignore-without-code", "redundant-self", "redundant-expr"]
exclude = ['build', 'xarray/util/generate_.*\.py']
files = "xarray"
show_error_context = true
warn_redundant_casts = true
warn_unused_ignores = true

# Much of the numerical computing stack doesn't have type annotations yet.
[[tool.mypy.overrides]]
ignore_missing_imports = true
module = [
  "bottleneck.*",
  "cartopy.*",
  "cf_units.*",
  "cfgrib.*",
  "cftime.*",
  "cloudpickle.*",
  "cubed.*",
  "cupy.*",
  "fsspec.*",
  "h5netcdf.*",
  "h5py.*",
  "iris.*",
  "mpl_toolkits.*",
  "nc_time_axis.*",
  "netCDF4.*",
  "numcodecs.*",
  "opt_einsum.*",
  "pint.*",
  "pooch.*",
  "polars.*",
  "pyarrow.*",
  "pydap.*",
  "seaborn.*",
  "setuptools",
  "sparse.*",
  "toolz.*",
  "zarr.*",
  "numpy.exceptions.*", # remove once support for `numpy<2.0` has been dropped
  "array_api_strict.*",
]

# pint>=0.26's annotations send mypy into infinite recursion (segfault / RecursionError)
# when optype is installed, so don't analyse pint at all.
# Fixed upstream in https://github.com/python/mypy/pull/22036; remove this override
# once we require mypy > 2.3.1.
[[tool.mypy.overrides]]
follow_imports = "skip"
module = ["pint.*"]

# Gradually we want to add more modules to this list, ratcheting up our total
# coverage. Once a module is here, functions are checked by mypy regardless of
# whether they have type annotations. It would be especially useful to have test
# files listed here, because without them being checked, we don't have a great
# way of testing our annotations.
[[tool.mypy.overrides]]
check_untyped_defs = true
module = [
  "xarray.backends.scipy_",
  "xarray.core.accessor_dt",
  "xarray.core.accessor_str",
  "xarray.structure.alignment",
  "xarray.computation.*",
  "xarray.indexes.*",
  "xarray.tests.*",
]

# Use strict = true whenever namedarray has become standalone. In the meantime
# don't forget to add all new files related to namedarray here:
# ref: https://mypy.readthedocs.io/en/stable/existing_code.html#introduce-stricter-options
[[tool.mypy.overrides]]
# Start off with these
warn_unused_ignores = true

# Getting these passing should be easy
strict_concatenate = true
strict_equality = true

# Strongly recommend enabling this one as soon as you can
check_untyped_defs = true

# These shouldn't be too much additional work, but may be tricky to
# get passing if you use a lot of untyped libraries
disallow_any_generics = true
disallow_subclassing_any = true
disallow_untyped_decorators = true

# These next few are various gradations of forcing use of type annotations
disallow_incomplete_defs = true
disallow_untyped_calls = true
disallow_untyped_defs = true

# This one isn't too hard to get passing, but return on investment is lower
no_implicit_reexport = true

# This one can be tricky to get passing if you use a lot of untyped libraries
warn_return_any = true

module = ["xarray.namedarray.*", "xarray.tests.test_namedarray"]

# We disable pyright here for now, since including it means that all errors show
# up in devs' VS Code, which then makes it more difficult to work with actual
# errors. It overrides local VS Code settings so isn't escapable.

# [tool.pyright]
# defineConstant = {DEBUG = true}
# # Enabling this means that developers who have disabled the warning locally —
# # because not all dependencies are installable — are overridden
# # reportMissingImports = true
# reportMissingTypeStubs = false

[tool.ruff]
extend-exclude = ["doc", "_typed_ops.pyi"]

[tool.ruff.lint]
extend-select = [
  "YTT",  # flake8-2020
  "B",    # flake8-bugbear
  "C4",   # flake8-comprehensions
  "ISC",  # flake8-implicit-str-concat
  "PIE",  # flake8-pie
  "TID",  # flake8-tidy-imports (absolute imports)
  "PYI",  # flake8-pyi
  "SIM",  # flake8-simplify
  "FLY",  # flynt
  "I",    # isort
  "PERF", # Perflint
  "W",    # pycodestyle warnings
  "PGH",  # pygrep-hooks
  "PLC",  # Pylint Convention
  "PLE",  # Pylint Errors
  "PLR",  # Pylint Refactor
  "PLW",  # Pylint Warnings
  "UP",   # pyupgrade
  "FURB", # refurb
  "RUF",
]
extend-safe-fixes = [
  "TID252", # absolute imports
]
ignore = [
  "C40",     # unnecessary generator, comprehension, or literal
  "PIE790",  # unnecessary pass statement
  "PYI019",  # use `Self` instead of custom TypeVar
  "PYI041",  # use `float` instead of `int | float`
  "SIM102",  # use a single `if` statement instead of nested `if` statements
  "SIM108",  # use ternary operator instead of `if`-`else`-block
  "SIM117",  # use a single `with` statement instead of nested `with` statements
  "SIM118",  # use `key in dict` instead of `key in dict.keys()`
  "SIM300",  # yoda condition detected
  "PERF203", # try-except within a loop incurs performance overhead
  "E402",    # module level import not at top of file
  "E731",    # do not assign a lambda expression, use a def
  "PLC0415", # `import` should be at the top-level of a file
  "PLC0206", # extracting value from dictionary without calling `.items()`
  "PLR091",  # too many arguments / branches / statements
  "PLR2004", # magic value used in comparison
  "PLW0603", # using the global statement to update is discouraged
  "PLW0642", # reassigned `self` variable in instance method
  "PLW1641", # object does not implement `__hash__` method
  "PLW2901", # `for` loop variable overwritten by assignment target
  "UP007",   # use X | Y for type annotations
  "FURB105", # unnecessary empty string passed to `print`
  "RUF001",  # string contains ambiguous unicode character
  "RUF002",  # docstring contains ambiguous acute accent unicode character
  "RUF003",  # comment contains ambiguous no-break space unicode character
  "RUF005",  # consider unpacking operator instead of concatenation
  "RUF012",  # mutable class attributes
  # rules added to the default set in ruff 0.16
  "BLE001", # blind `except Exception`: used on purpose, e.g. in print_versions
  "DTZ001", # `datetime()` without `tzinfo`: xarray works with naive datetimes
  "N999",   # invalid module name: `netCDF4_`
  "S110",   # `try`-`except`-`pass`
  "TRY002", # raising vanilla `Exception`
  "TRY004", # prefer `TypeError`: switching would change the raised exceptions
]

[tool.ruff.lint.per-file-ignores]
# don't enforce absolute imports
"asv_bench/**" = ["TID252"]
# comparison with itself in tests
"xarray/tests/**" = ["PLR0124"]
# looks like ruff bugs
"xarray/core/_typed_ops.py" = ["PYI034"]
"xarray/namedarray/_typing.py" = ["PYI018", "PYI046"]

[tool.ruff.lint.isort]
known-first-party = ["xarray"]

[tool.ruff.lint.flake8-tidy-imports]
# Disallow all relative imports.
ban-relative-imports = "all"
[tool.ruff.lint.flake8-tidy-imports.banned-api]
"pandas.api.types.is_extension_array_dtype".msg = "Use xarray.core.utils.is_allowed_extension_array{_dtype} instead.  Only use the banend API if the incoming data has already been sanitized by xarray"

[tool.pytest.ini_options]
asyncio_default_fixture_loop_scope = "function"
addopts = [
  "--strict-config",
  "--strict-markers",
  "--mypy-pyproject-toml-file=pyproject.toml",
]

# We want to forbid warnings from within xarray in our tests — instead we should
# fix our own code, or mark the test itself as expecting a warning. So this:
# - Converts any warning from xarray into an error
# - Allows some warnings ("default") which the test suite currently raises,
#   since it wasn't practical to fix them all before merging this config. The
#   warnings are reported in CI (since it uses `default`, not `ignore`).
#
# Over time, we can remove these rules allowing warnings. A valued contribution
# is removing a line, seeing what breaks, and then fixing the library code or
# tests so that it doesn't raise warnings.
#
# There are some instance where we'll want to add to these rules:
# - While we only raise errors on warnings from within xarray, a dependency can
#   raise a warning with a stacklevel such that it's interpreted to be raised
#   from xarray and this will mistakenly convert it to an error. If that
#   happens, please feel free to add a rule switching it to `default` here, and
#   disabling the error.
# - If these settings get in the way of making progress, it's also acceptable to
#   temporarily add additional `default` rules.
# - But we should only add `ignore` rules if we're confident that we'll never
#   need to address a warning.

filterwarnings = [
  "error:::xarray.*",
  # Zarr 2 V3 implementation
  "default:Zarr-Python is not in alignment with the final V3 specification",
  # raised by zarr < 3.1 for vlen-utf8, consolidated metadata, U1 dtype
  "ignore:.* is currently not part .* the Zarr (version|format) 3 specification.:UserWarning",
  # Zarr V3 data type specifications warnings - very repetitive
  "ignore:The data type .* does not have a Zarr V3 specification",
  "ignore:Consolidated metadata is currently not part",
  # raised by `numpy` for code in `netcdf4-python`. Not scoped to a module
  # because warnings re-emitted by `pytest.warns` lose their module.
  "ignore:Setting the shape on a NumPy array has been deprecated in NumPy 2.5.:DeprecationWarning",
  # raised by `pyarrow` for `pandas` ranking arrow-backed strings
  "ignore:Specifying null_placement in RankOptions is deprecated:FutureWarning:pyarrow",
  # raised by `numpy` for `np.datetime64("NaT")` in `flox`
  "ignore:The 'generic' unit for NumPy timedelta is deprecated:DeprecationWarning:flox",
  # raised by `numpy` for code in `netcdf4-python` < 1.7 when indexing with empty arrays
  "ignore:The truth value of an empty array is ambiguous:DeprecationWarning:netCDF4",
  # TODO: remove once we know how to deal with a changed signature in protocols
  "default:::xarray.tests.test_strategies",
]

log_cli_level = "INFO"
markers = [
  "flaky: flaky tests",
  "mypy: type annotation tests",
  "network: tests requiring a network connection",
  "slow: slow tests",
  "slow_hypothesis: slow hypothesis tests",
]
minversion = "7"
python_files = ["test_*.py"]
testpaths = ["xarray/tests", "properties"]

[tool.aliases]
test = "pytest"

[tool.repo-review]
ignore = [
  "PP308", # This option creates a large amount of log lines.
]

[tool.typos]

[tool.typos.default]
extend-ignore-identifiers-re = [
  # Variable names
  "nd_.*",
  ".*_nd",
  "ba_.*",
  ".*_ba",
  "ser_.*",
  ".*_ser",
  # Function/class names
  "NDArray.*",
  ".*NDArray.*",
]

[tool.typos.default.extend-words]
# NumPy function names
arange = "arange"
ond = "ond"
aso = "aso"

# Technical terms
nd = "nd"
nin = "nin"
nclusive = "nclusive"   # part of "inclusive" in error messages
writeable = "writeable"

# Variable names
ba = "ba"
ser = "ser"
fo = "fo"
iy = "iy"
vart = "vart"
ede = "ede"
WRITEABLE = "WRITEABLE"

# Organization/Institution names
Stichting = "Stichting"
Mathematisch = "Mathematisch"

# People's names
Soler = "Soler"
Bruning = "Bruning"
Tung = "Tung"
Claus = "Claus"
Celles = "Celles"
slowy = "slowy"
Commun = "Commun"
Noice = "Noice"
Hax = "Hax"
Yau = "Yau"
whn = "whn"

# Tests
Ome = "Ome"
SUR = "SUR"
Tio = "Tio"
Ono = "Ono"
abl = "abl"

# Technical terms
splitted = "splitted"
childs = "childs"
cutted = "cutted"
LOCA = "LOCA"
SLEP = "SLEP"

[tool.typos.type.jupyter]
extend-ignore-re = ["\"id\": \".*\""]