Merge branch 'main' into fix-coord-transform-indexing

* main:
  Document limitations of cftime arithmetic (pydata#10653)
  Remove RTD htmlzip output format (pydata#10977)
  Support decoding unsigned integers to timedelta (pydata#10972)
  Use `._data` in `Variable._replace` (pydata#10969)
  small changes to the pixi env definitions (pydata#10976)
  Add GitHub Codespaces config for Pixi (pydata#10929)
  Fix workflow name to embed `matrix.pytest-addopts` (pydata#10970)

Author: dcherian

.devcontainer/Dockerfile

@@ -0,0 +1,13 @@
+FROM mcr.microsoft.com/devcontainers/base:jammy
+
+ARG PIXI_VERSION=v0.59.0
+
+RUN curl -L -o /usr/local/bin/pixi -fsSL --compressed "https://github.com/prefix-dev/pixi/releases/download/${PIXI_VERSION}/pixi-$(uname -m)-unknown-linux-musl" \
+    && chmod +x /usr/local/bin/pixi \
+    && pixi info
+
+# set some user and workdir settings to work nicely with vscode
+USER vscode
+WORKDIR /home/vscode
+
+RUN echo 'eval "$(pixi completion -s bash)"' >> /home/vscode/.bashrc

.devcontainer/devcontainer.json

@@ -0,0 +1,24 @@
+{
+  "name": "my-workspace",
+  "build": {
+    "dockerfile": "Dockerfile",
+    "context": ".."
+  },
+  "hostRequirements": {
+    "cpus": 4,
+    "memory": "16gb"
+  },
+  "customizations": {
+    "vscode": {
+      "settings": {},
+      "extensions": ["ms-python.python", "charliermarsh.ruff", "GitHub.copilot"]
+    }
+  },
+  "features": {
+    "ghcr.io/devcontainers/features/docker-in-docker:2": {}
+  },
+  "mounts": [
+    "source=${localWorkspaceFolderBasename}-pixi,target=${containerWorkspaceFolder}/.pixi,type=volume"
+  ],
+  "postCreateCommand": "sudo chown vscode .pixi && pixi install"
+}

.github/workflows/ci-additional.yaml

@@ -48,7 +48,7 @@ jobs:
       run:
         shell: bash -l {0}
     env:
-      PIXI_ENV: test
+      PIXI_ENV: "test-py313"
     steps:
       - uses: actions/checkout@v6
         with:
@@ -75,7 +75,7 @@ jobs:
 
       - name: Version info
         run: |
-          pixi run -e ${{env.PIXI_ENV}} python xarray/util/print_versions.py
+          pixi run -e ${{env.PIXI_ENV}} -- python xarray/util/print_versions.py
       - name: Run doctests
         run: |
           # Raise an error if there are warnings in the doctests, with `-Werror`.
@@ -84,7 +84,7 @@ jobs:
           #
           # If dependencies emit warnings we can't do anything about, add ignores to
           # `xarray/tests/__init__.py`.
-          pixi run -e ${{env.PIXI_ENV}} python -m pytest --doctest-modules xarray --ignore xarray/tests -Werror
+          pixi run -e ${{env.PIXI_ENV}} -- python -m pytest --doctest-modules xarray --ignore xarray/tests -Werror
 
   mypy:
     name: Mypy
@@ -94,7 +94,7 @@ jobs:
       run:
         shell: bash -l {0}
     env:
-      PIXI_ENV: test-with-typing
+      PIXI_ENV: test-py313-with-typing
 
     steps:
       - uses: actions/checkout@v6
@@ -117,14 +117,14 @@ jobs:
       - name: set environment variables
         run: |
           echo "TODAY=$(date +'%Y-%m-%d')" >> $GITHUB_ENV
-          echo "PYTHON_VERSION=$(pixi run -e ${{env.PIXI_ENV}} python --version | cut -d' ' -f2 | cut -d. -f1,2)" >> $GITHUB_ENV
+          echo "PYTHON_VERSION=$(pixi run -e ${{env.PIXI_ENV}} -- python --version | cut -d' ' -f2 | cut -d. -f1,2)" >> $GITHUB_ENV
       - name: Version info
         run: |
-          pixi run -e ${{env.PIXI_ENV}} python xarray/util/print_versions.py
+          pixi run -e ${{env.PIXI_ENV}} -- python xarray/util/print_versions.py
 
       - name: Run mypy
         run: |
-          pixi run -e ${{env.PIXI_ENV}} python -m mypy --install-types --non-interactive --cobertura-xml-report mypy_report
+          pixi run -e ${{env.PIXI_ENV}} -- python -m mypy --install-types --non-interactive --cobertura-xml-report mypy_report
 
       - name: Upload mypy coverage to Codecov
         uses: codecov/[email protected]
@@ -166,14 +166,14 @@ jobs:
       - name: set environment variables
         run: |
           echo "TODAY=$(date +'%Y-%m-%d')" >> $GITHUB_ENV
-          echo "PYTHON_VERSION=$(pixi run -e ${{env.PIXI_ENV}} python --version | cut -d' ' -f2 | cut -d. -f1,2)" >> $GITHUB_ENV
+          echo "PYTHON_VERSION=$(pixi run -e ${{env.PIXI_ENV}} -- python --version | cut -d' ' -f2 | cut -d. -f1,2)" >> $GITHUB_ENV
       - name: Version info
         run: |
-          pixi run -e ${{env.PIXI_ENV}} python xarray/util/print_versions.py
+          pixi run -e ${{env.PIXI_ENV}} -- python xarray/util/print_versions.py
 
       - name: Run mypy
         run: |
-          pixi run -e ${{env.PIXI_ENV}} python -m mypy --install-types --non-interactive --cobertura-xml-report mypy_report
+          pixi run -e ${{env.PIXI_ENV}} -- python -m mypy --install-types --non-interactive --cobertura-xml-report mypy_report
 
       - name: Upload mypy coverage to Codecov
         uses: codecov/[email protected]
@@ -191,7 +191,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        pixi-env: ["test-with-typing", "test-py311-with-typing"]
+        pixi-env: ["test-py313-with-typing", "test-py311-with-typing"]
     if: |
       always()
       && (
@@ -223,14 +223,14 @@ jobs:
       - name: set environment variables
         run: |
           echo "TODAY=$(date +'%Y-%m-%d')" >> $GITHUB_ENV
-          echo "PYTHON_VERSION=$(pixi run -e ${{ matrix.pixi-env }} python --version | cut -d' ' -f2 | cut -d. -f1,2)" >> $GITHUB_ENV
+          echo "PYTHON_VERSION=$(pixi run -e ${{ matrix.pixi-env }} -- python --version | cut -d' ' -f2 | cut -d. -f1,2)" >> $GITHUB_ENV
       - name: Version info
         run: |
-          pixi run -e ${{ matrix.pixi-env }} python xarray/util/print_versions.py
+          pixi run -e ${{ matrix.pixi-env }} -- python xarray/util/print_versions.py
 
       - name: Run pyright
         run: |
-          pixi run -e ${{ matrix.pixi-env }} python -m pyright xarray/
+          pixi run -e ${{ matrix.pixi-env }} -- python -m pyright xarray/
 
       - name: Upload pyright coverage to Codecov
         uses: codecov/[email protected]

.github/workflows/ci.yaml

@@ -40,7 +40,7 @@ jobs:
     with:
       pixi-version: "v0.58.0" # keep in sync with env var above
   test:
-    name: "${{ matrix.os }} | ${{ matrix.pixi-env }}"
+    name: "${{ matrix.os }} | ${{ matrix.pixi-env }}${{ matrix.pytest-addopts && format(' ({0})', matrix.pytest-addopts) || '' }}"
     runs-on: ${{ matrix.os }}
     needs: [detect-ci-trigger, cache-pixi-lock]
     if: needs.detect-ci-trigger.outputs.triggered == 'false'
@@ -52,22 +52,22 @@ jobs:
       matrix:
         os: ["ubuntu-latest", "macos-latest", "windows-latest"]
         # Bookend python versions
-        pixi-env: ["test-py311", "test"]
+        pixi-env: ["test-py311", "test-py313"]
         pytest-addopts: [""]
         include:
           # Minimum python version:
-          - pixi-env: "test-bare-minimum"
+          - pixi-env: "test-py311-bare-minimum"
             os: ubuntu-latest
-          - pixi-env: "test-bare-min-and-scipy"
+          - pixi-env: "test-py311-bare-min-and-scipy"
             os: ubuntu-latest
-          - pixi-env: "test-min-versions"
+          - pixi-env: "test-py311-min-versions"
             os: ubuntu-latest
           # Latest python version:
-          - pixi-env: "test-no-numba"
+          - pixi-env: "test-py313-no-numba"
             os: ubuntu-latest
-          - pixi-env: "test-no-dask"
+          - pixi-env: "test-py313-no-dask"
             os: ubuntu-latest
-          - pixi-env: "test"
+          - pixi-env: "test-py313"
             pytest-addopts: "flaky"
             os: ubuntu-latest
           # The mypy tests must be executed using only 1 process in order to guarantee
@@ -76,7 +76,7 @@ jobs:
             pytest-addopts: "mypy"
             numprocesses: 1
             os: ubuntu-latest
-          - pixi-env: "test-with-typing"
+          - pixi-env: "test-py313-with-typing"
             numprocesses: 1
             os: ubuntu-latest
     steps:
@@ -101,7 +101,7 @@ jobs:
       - name: Set environment variables
         run: |
           echo "TODAY=$(date +'%Y-%m-%d')" >> $GITHUB_ENV
-          echo "PYTHON_VERSION=$(pixi run -e ${{env.PIXI_ENV}} python --version | cut -d' ' -f2 | cut -d. -f1,2)" >> $GITHUB_ENV
+          echo "PYTHON_VERSION=$(pixi run -e ${{ matrix.pixi-env }} -- python --version | cut -d' ' -f2 | cut -d. -f1,2)" >> $GITHUB_ENV
 
           if [[ "${{ matrix.pytest-addopts }}" != "" ]] ;
           then
@@ -128,11 +128,11 @@ jobs:
 
       - name: Version info
         run: |
-          pixi run -e ${{ matrix.pixi-env }} python xarray/util/print_versions.py
+          pixi run -e ${{ matrix.pixi-env }} -- python xarray/util/print_versions.py
 
       - name: Import xarray
         run: |
-          pixi run -e ${{ matrix.pixi-env }} python -c "import xarray"
+          pixi run -e ${{ matrix.pixi-env }} -- python -c "import xarray"
 
       - name: Restore cached hypothesis directory
         uses: actions/cache@v4
@@ -143,12 +143,12 @@ jobs:
           save-always: true
 
       - name: Run tests
-        run:
-          pixi run -e ${{ matrix.pixi-env }} python -m pytest -n ${{ matrix.numprocesses || 4 }}
-          --timeout 180
-          --cov=xarray
-          --cov-report=xml
-          --junitxml=pytest.xml
+        run: |
+          pixi run -e ${{ matrix.pixi-env }} -- python -m pytest -n ${{ matrix.numprocesses || 4 }} \
+            --timeout 180 \
+            --cov=xarray \
+            --cov-report=xml \
+            --junitxml=pytest.xml
 
       - name: Upload test results
         if: always()

.github/workflows/hypothesis.yaml

@@ -55,7 +55,7 @@ jobs:
         shell: bash -l {0}
 
     env:
-      PIXI_ENV: test
+      PIXI_ENV: "test-py313"
 
     steps:
       - uses: actions/checkout@v6

.github/workflows/upstream-dev-ci.yaml

@@ -79,15 +79,15 @@ jobs:
           cache-write: ${{ github.event_name == 'push' && github.ref_name == 'main' }}
       - name: Version info
         run: |
-          pixi run -e ${{matrix.pixi-env}} python xarray/util/print_versions.py
+          pixi run -e ${{matrix.pixi-env}} -- python xarray/util/print_versions.py
       - name: Import xarray
         run: |
-          pixi run -e ${{matrix.pixi-env}} python -c 'import xarray'
+          pixi run -e ${{matrix.pixi-env}} -- python -c 'import xarray'
       - name: Run Tests
         if: success()
         id: status
         run: |
-          pixi run -e ${{matrix.pixi-env}} python -m pytest --timeout=60 -rf -nauto \
+          pixi run -e ${{matrix.pixi-env}} -- python -m pytest --timeout=60 -rf -nauto \
             --report-log output-${{ matrix.pixi-env }}-log.jsonl
       - name: Generate and publish the report
         if: |
@@ -138,13 +138,13 @@ jobs:
       - name: set environment variables
         run: |
           echo "TODAY=$(date +'%Y-%m-%d')" >> $GITHUB_ENV
-          echo "PYTHON_VERSION=$(pixi run -e ${{matrix.pixi-env}} python --version | cut -d' ' -f2 | cut -d. -f1,2)" >> $GITHUB_ENV
+          echo "PYTHON_VERSION=$(pixi run -e ${{matrix.pixi-env}} -- python --version | cut -d' ' -f2 | cut -d. -f1,2)" >> $GITHUB_ENV
       - name: Version info
         run: |
-          pixi run -e ${{matrix.pixi-env}} python xarray/util/print_versions.py
+          pixi run -e ${{matrix.pixi-env}} -- python xarray/util/print_versions.py
       - name: Run mypy
         run: |
-          pixi run -e ${{matrix.pixi-env}} python -m mypy --install-types --non-interactive --cobertura-xml-report mypy_report
+          pixi run -e ${{matrix.pixi-env}} -- python -m mypy --install-types --non-interactive --cobertura-xml-report mypy_report
       - name: Upload mypy coverage to Codecov
         uses: codecov/[email protected]
         with:

.pre-commit-config.yaml

@@ -35,7 +35,7 @@ repos:
       - id: blackdoc
         exclude: "generate_aggregations.py"
         # make sure this is the most recent version of black
-        additional_dependencies: ["black==25.9.0"]
+        additional_dependencies: ["black==25.11.0"]
   - repo: https://github.com/rbubley/mirrors-prettier
     rev: v3.7.3
     hooks:

.readthedocs.yaml

@@ -24,6 +24,3 @@ build:
     build:
       html:
         - pixi run doc BUILDDIR=$READTHEDOCS_OUTPUT
-
-formats:
-  - htmlzip

doc/user-guide/weather-climate.rst

@@ -279,3 +279,90 @@ For data indexed by a :py:class:`~xarray.CFTimeIndex` xarray currently supports:
 .. _precision range: https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#timestamp-limitations
 .. _ISO 8601 standard: https://en.wikipedia.org/wiki/ISO_8601
 .. _partial datetime string indexing: https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#partial-string-indexing
+
+.. _cftime_arithmetic_limitations:
+
+Arithmetic limitations with ``cftime`` objects
+----------------------------------------------
+
+A current limitation when working with non-standard calendars and :py:class:`cftime.datetime`
+objects is that they support arithmetic with :py:class:`datetime.timedelta`, but **not** with :py:class:`numpy.timedelta64`.
+
+This means that certain xarray operations (such as :py:meth:`~xarray.DataArray.diff`)
+may produce ``timedelta64`` results that cannot be directly combined with ``cftime`` coordinates.
+
+For example, let's define a time axis using ``cftime`` objects:
+
+.. jupyter-execute::
+
+    import xarray as xr
+    import numpy as np
+    import pandas as pd
+    import cftime
+
+    time = xr.DataArray(
+        xr.date_range("2000", periods=3, freq="MS", use_cftime=True),
+        dims="time",
+    )
+
+If you want to compute, e.g., midpoints in the time intervals, this will not work:
+
+.. code-block:: python
+
+    # Attempt to compute midpoints
+    time[:-1] + 0.5 * time.diff("time")
+
+and result in an error like this:
+
+.. code-block:: none
+
+   UFuncTypeError: ufunc 'add' cannot use operands with types dtype('O') and dtype('<m8[ns]')
+
+This is because :py:meth:`~xarray.DataArray.diff` returns ``timedelta64``, which is not
+compatible with ``cftime.datetime``. These limitations stem from the ``cftime`` library itself;
+arithmetic between ``cftime.datetime`` and ``numpy.timedelta64`` is not implemented.
+
+**Workarounds**
+
+One possible workaround is to use :py:meth:`numpy.diff` on the underlying values,
+which returns ``datetime.timedelta`` objects that are compatible:
+
+.. jupyter-execute::
+
+    time[:-1] + 0.5 * np.diff(time.values)
+
+or you can convert ``timedelta64`` values to Python ``timedelta`` objects explicitly,
+for example via :py:meth:`pandas.to_timedelta`:
+
+.. jupyter-execute::
+
+    td = pd.to_timedelta(time.diff("time").values).to_pytimedelta()
+    time[:-1] + 0.5 * td
+
+You could also consider a more verbose, but also more robust, workaround that adds the two
+DataArrays via :py:meth:`~xarray.apply_ufunc`:
+
+.. jupyter-execute::
+
+    def add_cftime_and_timedelta64(cftime_da, timedelta64_da, join="inner"):
+        def func(cftime_array, timedelta64_array):
+            shape = cftime_array.shape
+            cftime_array = cftime_array.ravel()
+            timedelta64_array = timedelta64_array.ravel()
+            timedelta_array = pd.to_timedelta(timedelta64_array).to_pytimedelta()
+            return (cftime_array + timedelta_array).reshape(shape)
+
+        return xr.apply_ufunc(
+            func,
+            cftime_da,
+            timedelta64_da,
+            dask="parallelized",
+            output_dtypes=[cftime_da.dtype],
+            join=join
+        )
+
+
+    add_cftime_and_timedelta64(time, 0.5 * time.diff("time"))
+
+This function has the advantage that it preserves the coordinate alignment, as well as multi-dimensional
+and dask compatibility features of xarray.

doc/whats-new.rst

@@ -46,10 +46,15 @@ Bug Fixes
   By `Justus Magin <https://github.com/keewis>`_.
 - Avoid casting custom indexes in ``Dataset.drop_attrs`` (:pull:`10961`)
   By `Justus Magin <https://github.com/keewis>`_.
+- Support decoding unsigned integers to ``np.timedelta64``.
+  By `Deepak Cherian <https://github.com/dcherian>`_.
+
 
 Documentation
 ~~~~~~~~~~~~~
 
+- Added section on the `limitations of cftime arithmetic <https://docs.xarray.dev/en/stable/user-guide/weather-climate.html#arithmetic-limitations-with-non-standard-calendars>`_ (:pull:`10653`).
+  By `Lars Buntemeyer <https://github.com/larsbuntemeyer>`_
 
 Internal Changes
 ~~~~~~~~~~~~~~~~