From a2bf4de47d4fdba6c7c7e5570d464756f5b94f00 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kai=20M=C3=BChlbauer?= Date: Thu, 31 Oct 2024 10:13:48 +0100 Subject: [PATCH 1/2] mention attribute peculiarities in docs/docstrings --- doc/getting-started-guide/faq.rst | 3 +++ doc/user-guide/data-structures.rst | 3 ++- xarray/core/dataarray.py | 1 + xarray/core/dataset.py | 1 + xarray/core/variable.py | 1 + 5 files changed, 8 insertions(+), 1 deletion(-) diff --git a/doc/getting-started-guide/faq.rst b/doc/getting-started-guide/faq.rst index 58d5448cdf5..49d7f5e4873 100644 --- a/doc/getting-started-guide/faq.rst +++ b/doc/getting-started-guide/faq.rst @@ -146,6 +146,9 @@ for conflicts between ``attrs`` when combining arrays and datasets, unless explicitly requested with the option ``compat='identical'``. The guiding principle is that metadata should not be allowed to get in the way. +In general xarray uses the capabilities of the backends for reading and writing +attributes. That has some implications on roundtripping. One example for such inconsistency is that size-1 lists will roundtrip as single element (for netcdf4 backends). + What other netCDF related Python libraries should I know about? --------------------------------------------------------------- diff --git a/doc/user-guide/data-structures.rst b/doc/user-guide/data-structures.rst index e5e89b0fbbd..9a2f26ec7b5 100644 --- a/doc/user-guide/data-structures.rst +++ b/doc/user-guide/data-structures.rst @@ -40,7 +40,8 @@ alignment, building on the functionality of the ``index`` found on a pandas DataArray objects also can have a ``name`` and can hold arbitrary metadata in the form of their ``attrs`` property. Names and attributes are strictly for users and user-written code: xarray makes no attempt to interpret them, and -propagates them only in unambiguous cases +propagates them only in unambiguous cases. For reading and writing attributes +xarray relies on the capabilities of the supported backends. (see FAQ, :ref:`approach to metadata`). .. _creating a dataarray: diff --git a/xarray/core/dataarray.py b/xarray/core/dataarray.py index db7824d8c90..0a4d8575183 100644 --- a/xarray/core/dataarray.py +++ b/xarray/core/dataarray.py @@ -347,6 +347,7 @@ class DataArray( attrs : dict_like or None, optional Attributes to assign to the new instance. By default, an empty attribute dictionary is initialized. + (see FAQ, :ref:`approach to metadata`) indexes : py:class:`~xarray.Indexes` or dict-like, optional For internal use only. For passing indexes objects to the new DataArray, use the ``coords`` argument instead with a diff --git a/xarray/core/dataset.py b/xarray/core/dataset.py index 66ceea17b91..1b999b45496 100644 --- a/xarray/core/dataset.py +++ b/xarray/core/dataset.py @@ -597,6 +597,7 @@ class Dataset( attrs : dict-like, optional Global attributes to save on this dataset. + (see FAQ, :ref:`approach to metadata`) Examples -------- diff --git a/xarray/core/variable.py b/xarray/core/variable.py index 13053faff58..16e292796a7 100644 --- a/xarray/core/variable.py +++ b/xarray/core/variable.py @@ -401,6 +401,7 @@ def __init__( attrs : dict_like or None, optional Attributes to assign to the new variable. If None (default), an empty attribute dictionary is initialized. + (see FAQ, :ref:`approach to metadata`) encoding : dict_like or None, optional Dictionary specifying how to encode this array's data into a serialized format like netCDF4. Currently used keys (for netCDF) From 47dac7897b4fd36062862f8ed1df845e4a2bf26a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kai=20M=C3=BChlbauer?= Date: Thu, 31 Oct 2024 10:17:44 +0100 Subject: [PATCH 2/2] add whats-new.rst --- doc/whats-new.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/whats-new.rst b/doc/whats-new.rst index 135358b08e8..a7e3991e87e 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -40,6 +40,9 @@ Bug fixes Documentation ~~~~~~~~~~~~~ +- Mention attribute peculiarities in docs/docstrings (:issue:`4798`, :pull:`9700`). + By `Kai Mühlbauer `_. + Internal Changes ~~~~~~~~~~~~~~~~