pydata · kmuehlbauer · Jan 30, 2025 · Oct 24, 2024 · Oct 24, 2024 · Nov 8, 2024
diff --git a/doc/api.rst b/doc/api.rst
@@ -10,7 +10,7 @@ This page provides an auto-generated summary of xarray's API. For more details
 and examples, refer to the relevant chapters in the main part of the
 documentation.
 
-See also: :ref:`public api`
+See also: :ref:`public-api` and :ref:`api-stability`.
 
 Top-level functions
 ===================

diff --git a/doc/getting-started-guide/faq.rst b/doc/getting-started-guide/faq.rst
@@ -416,7 +416,19 @@ would certainly appreciate it. We recommend two citations.
                  url    = {https://doi.org/10.5281/zenodo.59499}
                 }
 
-.. _public api:
+.. _api-stability:
+
+How stable is Xarray's API?
+---------------------------
+
+Xarray tries very hard to maintain backwards compatibility in our :ref:`api` between released versions.
+Whilst we do occasionally make breaking changes in order to improve the library,
+we `signpost changes <https://docs.xarray.dev/en/stable/contributing.html#backwards-compatibility>`_ with ``DeprecationWarnings`` for many releases in advance.
+(An exception is bugs - whose behaviour we try to fix as soon as we notice them.)
+Our `test-driven development practices <https://docs.xarray.dev/en/stable/contributing.html#test-driven-development-code-writing>`_ helps to ensure any accidental regressions are caught.
+This philosophy applies to everything in the `public API <https://docs.xarray.dev/en/stable/getting-started-guide/faq.html#what-parts-of-xarray-are-considered-public-api>`_.
+
+.. _public-api:
 
 What parts of xarray are considered public API?
 -----------------------------------------------

diff --git a/doc/whats-new.rst b/doc/whats-new.rst
@@ -113,6 +113,8 @@ Documentation
 ~~~~~~~~~~~~~
 - A chapter on :ref:`internals.timecoding` is added to the internal section (:pull:`9618`).
   By `Kai Mühlbauer <https://github.com/kmuehlbauer>`_.
+- Clarified xarray's policy on API stability in the FAQ. (:issue:`9854`, :pull:`9855`)
+  By `Tom Nicholas <https://github.com/TomNicholas>`_.
 
 Internal Changes
 ~~~~~~~~~~~~~~~~

diff --git a/xarray/namedarray/core.py b/xarray/namedarray/core.py
        attrs: _AttrsLike = None,
    ):
        self._data = data
        self._dims = self._parse_dimensions(dims)
        self._attrs = dict(attrs) if attrs else None

    def __init_subclass__(cls, **kwargs: Any) -> None:
diff --git a/xarray/core/duck_array_ops.py b/xarray/core/duck_array_ops.py
        xp = get_array_namespace(data)
        if xp == np:
            # numpy currently doesn't have a astype:
            return data.astype(dtype, **kwargs)
        return xp.astype(data, dtype, **kwargs)
    return data.astype(dtype, **kwargs)

diff --git a/xarray/coding/variables.py b/xarray/coding/variables.py
            # otherwise numpy unsigned ints will silently cast to the signed counterpart
            fill_value = fill_value.item()
        # passes if provided fill value fits in encoded on-disk type
        new_fill = encoded_dtype.type(fill_value)
    except OverflowError:
        encoded_kind_str = "signed" if encoded_dtype.kind == "i" else "unsigned"
        warnings.warn(
	attrs: _AttrsLike = None,
	):
	self._data = data
	self._dims = self._parse_dimensions(dims)
Check warning on line 264 in xarray/namedarray/core.py GitHub Actions / ubuntu-latest py3.10 bare-minimum Duplicate dimension names present: dimensions {'x'} appear more than once in dims=('x', 'x'). We do not yet support duplicate dimension names, but we do allow initial construction of the object. We recommend you rename the dims immediately to become distinct, as most xarray functionality is likely to fail silently if you do not. To rename the dimensions you will need to set the ``.dims`` attribute of each variable, ``e.g. var.dims=('x0', 'x1')``. Check warning on line 264 in xarray/namedarray/core.py GitHub Actions / ubuntu-latest py3.10 bare-minimum Duplicate dimension names present: dimensions {'x'} appear more than once in dims=('x', 'x'). We do not yet support duplicate dimension names, but we do allow initial construction of the object. We recommend you rename the dims immediately to become distinct, as most xarray functionality is likely to fail silently if you do not. To rename the dimensions you will need to set the ``.dims`` attribute of each variable, ``e.g. var.dims=('x0', 'x1')``.
	self._attrs = dict(attrs) if attrs else None

	def __init_subclass__(cls, **kwargs: Any) -> None:
	xp = get_array_namespace(data)
	if xp == np:
	# numpy currently doesn't have a astype:
	return data.astype(dtype, **kwargs)
Check warning on line 234 in xarray/core/duck_array_ops.py GitHub Actions / macos-latest py3.10 `invalid value encountered in cast` Check warning on line 234 in xarray/core/duck_array_ops.py GitHub Actions / macos-latest py3.10 `invalid value encountered in cast` Check warning on line 234 in xarray/core/duck_array_ops.py GitHub Actions / macos-latest py3.12 `invalid value encountered in cast` Check warning on line 234 in xarray/core/duck_array_ops.py GitHub Actions / macos-latest py3.12 `invalid value encountered in cast` Check warning on line 234 in xarray/core/duck_array_ops.py GitHub Actions / ubuntu-latest py3.10 `invalid value encountered in cast` Check warning on line 234 in xarray/core/duck_array_ops.py GitHub Actions / ubuntu-latest py3.10 `invalid value encountered in cast` Check warning on line 234 in xarray/core/duck_array_ops.py GitHub Actions / ubuntu-latest py3.12 `invalid value encountered in cast` Check warning on line 234 in xarray/core/duck_array_ops.py GitHub Actions / ubuntu-latest py3.12 `invalid value encountered in cast` Check warning on line 234 in xarray/core/duck_array_ops.py GitHub Actions / windows-latest py3.10 `invalid value encountered in cast` Check warning on line 234 in xarray/core/duck_array_ops.py GitHub Actions / windows-latest py3.10 `invalid value encountered in cast`
	return xp.astype(data, dtype, **kwargs)
	return data.astype(dtype, **kwargs)
	# otherwise numpy unsigned ints will silently cast to the signed counterpart
	fill_value = fill_value.item()
	# passes if provided fill value fits in encoded on-disk type
	new_fill = encoded_dtype.type(fill_value)
Check warning on line 348 in xarray/coding/variables.py GitHub Actions / ubuntu-latest py3.10 min-all-deps NumPy will stop allowing conversion of out-of-bound Python integers to integer arrays. The conversion of 255 to int8 will fail in the future. For the old behavior, usually: np.array(value).astype(dtype)` will give the desired result (the cast overflows). Check warning on line 348 in xarray/coding/variables.py GitHub Actions / ubuntu-latest py3.10 min-all-deps NumPy will stop allowing conversion of out-of-bound Python integers to integer arrays. The conversion of 255 to int8 will fail in the future. For the old behavior, usually: np.array(value).astype(dtype)` will give the desired result (the cast overflows). Check warning on line 348 in xarray/coding/variables.py GitHub Actions / ubuntu-latest py3.10 min-all-deps NumPy will stop allowing conversion of out-of-bound Python integers to integer arrays. The conversion of 255 to int8 will fail in the future. For the old behavior, usually: np.array(value).astype(dtype)` will give the desired result (the cast overflows). Check warning on line 348 in xarray/coding/variables.py GitHub Actions / ubuntu-latest py3.10 min-all-deps NumPy will stop allowing conversion of out-of-bound Python integers to integer arrays. The conversion of 255 to int8 will fail in the future. For the old behavior, usually: np.array(value).astype(dtype)` will give the desired result (the cast overflows). Check warning on line 348 in xarray/coding/variables.py GitHub Actions / ubuntu-latest py3.10 min-all-deps NumPy will stop allowing conversion of out-of-bound Python integers to integer arrays. The conversion of 255 to int8 will fail in the future. For the old behavior, usually: np.array(value).astype(dtype)` will give the desired result (the cast overflows). Check warning on line 348 in xarray/coding/variables.py GitHub Actions / ubuntu-latest py3.10 min-all-deps NumPy will stop allowing conversion of out-of-bound Python integers to integer arrays. The conversion of 255 to int8 will fail in the future. For the old behavior, usually: np.array(value).astype(dtype)` will give the desired result (the cast overflows).::warning file=/home/runner/work/xarray/xarray/xarray/coding/variables.py,line=348::NumPy will stop allowing conversion of out-of-bound Python integers to integer arrays. The conversion of 255 to int8 will fail in the future. For the old behavior, usually: np.array(value).astype(dtype)` will give the desired result (the cast overflows). Check warning on line 348 in xarray/coding/variables.py GitHub Actions / ubuntu-latest py3.10 min-all-deps NumPy will stop allowing conversion of out-of-bound Python integers to integer arrays. The conversion of 255 to int8 will fail in the future. For the old behavior, usually: np.array(value).astype(dtype)` will give the desired result (the cast overflows). Check warning on line 348 in xarray/coding/variables.py GitHub Actions / ubuntu-latest py3.10 min-all-deps NumPy will stop allowing conversion of out-of-bound Python integers to integer arrays. The conversion of 255 to int8 will fail in the future. For the old behavior, usually: np.array(value).astype(dtype)` will give the desired result (the cast overflows). Check warning on line 348 in xarray/coding/variables.py GitHub Actions / ubuntu-latest py3.10 min-all-deps NumPy will stop allowing conversion of out-of-bound Python integers to integer arrays. The conversion of 255 to int8 will fail in the future. For the old behavior, usually: np.array(value).astype(dtype)` will give the desired result (the cast overflows). Check warning on line 348 in xarray/coding/variables.py GitHub Actions / ubuntu-latest py3.10 min-all-deps NumPy will stop allowing conversion of out-of-bound Python integers to integer arrays. The conversion of 255 to int8 will fail in the future. For the old behavior, usually: np.array(value).astype(dtype)` will give the desired result (the cast overflows).
	except OverflowError:
	encoded_kind_str = "signed" if encoded_dtype.kind == "i" else "unsigned"
	warnings.warn(