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/doc/whats-new.rst b/doc/whats-new.rst index 659063f2cbf..baa57e7bb27 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -43,6 +43,9 @@ Bug fixes Documentation ~~~~~~~~~~~~~ +- Mention attribute peculiarities in docs/docstrings (:issue:`4798`, :pull:`9700`). + By `Kai Mühlbauer `_. + Internal Changes ~~~~~~~~~~~~~~~~ diff --git a/xarray/core/dataarray.py b/xarray/core/dataarray.py index c6bc082f5ed..f04cdac3a74 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 bc9360a809d..3cbeed3f7f4 100644 --- a/xarray/core/dataset.py +++ b/xarray/core/dataset.py @@ -596,6 +596,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)