diff --git a/doc/user-guide/indexing.rst b/doc/user-guide/indexing.rst index 90b7cbaf2a9..4882403342f 100644 --- a/doc/user-guide/indexing.rst +++ b/doc/user-guide/indexing.rst @@ -747,7 +747,7 @@ Whether array indexing returns a view or a copy of the underlying data depends on the nature of the labels. For positional (integer) -indexing, xarray follows the same rules as NumPy: +indexing, xarray follows the same `rules`_ as NumPy: * Positional indexing with only integers and slices returns a view. * Positional indexing with arrays or lists returns a copy. @@ -764,8 +764,10 @@ Whether data is a copy or a view is more predictable in xarray than in pandas, s unlike pandas, xarray does not produce `SettingWithCopy warnings`_. However, you should still avoid assignment with chained indexing. -.. _SettingWithCopy warnings: https://pandas.pydata.org/pandas-docs/stable/indexing.html#returning-a-view-versus-a-copy +Note that other operations (such as :py:meth:`~xarray.DataArray.values`) may also return views rather than copies. +.. _SettingWithCopy warnings: https://pandas.pydata.org/pandas-docs/stable/indexing.html#returning-a-view-versus-a-copy +.. _rules: https://numpy.org/doc/stable/user/basics.copies.html .. _multi-level indexing: diff --git a/xarray/core/dataarray.py b/xarray/core/dataarray.py index 7a0bdbc4d4c..64f02fa3b44 100644 --- a/xarray/core/dataarray.py +++ b/xarray/core/dataarray.py @@ -761,11 +761,15 @@ def data(self, value: Any) -> None: @property def values(self) -> np.ndarray: """ - The array's data as a numpy.ndarray. + The array's data converted to numpy.ndarray. - If the array's data is not a numpy.ndarray this will attempt to convert - it naively using np.array(), which will raise an error if the array - type does not support coercion like this (e.g. cupy). + This will attempt to convert the array naively using np.array(), + which will raise an error if the array type does not support + coercion like this (e.g. cupy). + + Note that this array is not copied; operations on it follow + numpy's rules of what generates a view vs. a copy, and changes + to this array may be reflected in the DataArray as well. """ return self.variable.values