More improvements.

Author: pp-mo

docs/changelog_fragments/68.feat.rst

@@ -3,4 +3,4 @@ The :class:`ncdata.NcData` objects can be indexed with the ``[]`` operation, or
 specifed dimensions with the :meth:`~ncdata.NcData.slicer` method.
 This is based on the new :meth:`~ncdata.utils.index_by_dimensions()` utility method
 and :class:`~ncdata.utils.Slicer` class.
-See: :ref:`indexing_overview`
+See: :ref:`utils_indexing`

docs/details/developer_notes.rst

@@ -46,7 +46,7 @@ For a full docs-build:
 
 .. note::
 
-    * the above is just for *local testing*, when required.
+    * the above is just for **local testing**, when required.
     * For PRs (and releases), we also provide *automatic* builds on GitHub,
       via ReadTheDocs_.
 
@@ -56,9 +56,9 @@ Release actions
 
 #. Update the :ref:`change-log page <change_log>` in the details section
 
-    #. ensure all major changes + PRs are referenced in the :ref:`change_notes` section.
+    #. start with ``$ towncrier build``
 
-       * The starting point for this is now just : ``$ towncrier build``.
+    #. ensure all major changes + PRs are referenced in the :ref:`change_notes` section.
 
     #. update the "latest version" stated in the :ref:`development_status` section
 

docs/userdocs/user_guide/common_operations.rst

@@ -55,6 +55,17 @@ Example :
 
     >>> dataset.variables["x"].avals["units"] = "m s-1"
 
+
+There is also an :meth:`~ncdata.NameMap.addall` method, which adds multiple content
+objects in one operation.
+
+.. doctest:: python
+
+    >>> vars = [NcVariable(name) for name in ("a", "b", "c")]
+    >>> dataset.variables.addall(vars)
+    >>> list(dataset.variables)
+    ['x', 'a', 'b', 'c']
+
 .. _operations_rename:
 
 Rename
@@ -69,6 +80,18 @@ Example :
 
     >>> dataset.variables.rename("x", "y")
 
+result:
+
+.. doctest:: python
+
+    >>> print(dataset.variables.get("x"))
+    None
+    >>> print(dataset.variables.get("y"))
+    <NcVariable(<no-dtype>): y()
+        y:units = 'm s-1'
+    >
+
+
 .. warning::
     Renaming a dimension will not rename references to it (i.e. in variables), which
     obviously may cause problems.
@@ -125,17 +148,29 @@ Equality Testing
 ----------------
 We implement equality operations ``==`` / ``!=`` for all the core data objects.
 
+.. doctest::
+
+    >>> vA = dataset.variables["a"]
+    >>> vB = dataset.variables["b"]
+    >>> vA == vB
+    False
+
+.. doctest::
+
+    >>> dataset == dataset.copy()
+    True
+
 .. warning::
-    The equality testing actually calls the :func:`ncdata.utils.dataset_differences` and
-    :func:`ncdata.utils.variable_differences` utility functions.
+    Equality testing for :class:`~ncdata.NcData` and :class:`~ncdata.NcVariable` actually
+    calls the :func:`ncdata.utils.dataset_differences` and
+    :func:`ncdata.utils.variable_differences` utilities.
 
     This can be very costly if it needs to compare large data arrays.
 
-If you need to avoid comparing large (and possibly lazy) arrays then you should use the
+If you need to avoid comparing large (and possibly lazy) arrays then you can use the
 :func:`ncdata.utils.dataset_differences` and
-:func:`ncdata.utils.variable_differences` utility functions directly.
-These enable you to use the provided tolerance options, such as ignoring differences in
-data content, or accepting that attributes are present in a different order.
+:func:`ncdata.utils.variable_differences` utility functions directly instead.
+These provide a ``check_var_data=False`` option, to ignore differences in data content.
 
 See: :ref:`utils_equality`
 

docs/userdocs/user_guide/data_objects.rst

@@ -186,7 +186,9 @@ However, for most operations on attributes, it is much easier to use the ``.aval
 property instead.  This accesses *the same attributes*, but in the form of a simple
 "name: value" dictionary.
 
-Thus for example, to fetch an attribute you would usually write just :
+Get attribute value
+^^^^^^^^^^^^^^^^^^^
+For example, to fetch an attribute you would usually write just :
 
 .. testsetup::
 
@@ -205,23 +207,15 @@ and **not** :
 
 .. doctest:: python
 
-    >>> # WRONG: this reads an NcAttribute, not its value
+    >>> # WRONG: this get the NcAttribute object, not its value
     >>> unit = dataset.variables["x"].attributes["units"]
 
-or:
-
-.. doctest:: python
-
-    >>> # WRONG: this gets NcAttribute.value as a character array, not a string
+    >>> # WRONG: this returns a character array, not a string
     >>> unit = dataset.variables["x"].attributes["units"].value
 
-or even (which is at least correct):
-
-.. doctest:: python
-
-    >>> unit = dataset.variables["x"].attributes["units"].as_python_value()
-
 
+Set attribute value
+^^^^^^^^^^^^^^^^^^^
 Likewise, to **set** a value, you would normally just
 
 .. doctest:: python
@@ -236,9 +230,11 @@ and **not**
     >>> dataset.variables["x"].attributes["units"].value = "K"
 
 
-Note also, that as the ``.avals`` is a dictionary, you can use standard dictionary
-methods such as ``update`` and ``get`` to perform other operations in a relatively
-natural, Pythonic way.
+``.avals`` as a dictionary
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+Note also, that as ``.avals`` is a dictionary, you can use standard dictionary
+methods such as ``pop``, ``update`` and ``get`` to perform other operations in a
+relatively natural, Pythonic way.
 
 .. doctest:: python
 
@@ -247,6 +243,12 @@ natural, Pythonic way.
 
     >>> dataset.attributes.update({"experiment": "A407", "expt_run": 704})
 
+.. note::
+    The new ``.avals`` property effectively replaces the old
+    :meth:`~ncdata.NcData.get_attrval` and :meth:`~ncdata.NcData.set_attrval` methods,
+    which are now deprecated and will eventually be removed.
+
+
 .. _data-constructors:
 
 Core Object Constructors

docs/userdocs/user_guide/utilities.rst

@@ -18,7 +18,7 @@ Dataset Equality Testing
 ------------------------
 The functions :func:`~ncdata.utils.dataset_differences` and
 :func:`~ncdata.utils.variable_differences` produce a list of messages detailing all the
-ways in which two datasets are different.
+ways in which two datasets or variables are different.
 
 For Example:
 ^^^^^^^^^^^^
@@ -51,19 +51,22 @@ For Example:
     Dataset "x" dimension has different "unlimited" status : False != True
     Dataset variable "vx" shapes differ : (5,) != (2,)
 
-.. note::
-   To compare isolated variables, the subsidiary routine
-   :func:`~ncdata.utils.variable_differences` is also provided.
+For a short-form test that two things are the same, you can just check that the
+results ``== []``.
+
+By default, these functions compare **everything** about the two arguments.
+However, they also have multiple keywords which allow certain *types* of differences to
+be ignored, E.G. ``check_dims_order=False``, ``check_var_data=False``.
 
 .. note::
     The ``==`` and ``!=`` operations on  :class:`ncdata.NcData` and
-    :class:`ncdata.NcVariable` simply call these utility functions to see if there are
-    any differences.
+    :class:`ncdata.NcVariable` use these utility functions to check for differences.
 
     .. warning::
-        As they lack a keyword interface, these operations have no tolerance options
-        and check absolutely everything.  This includes full data-array comparisons,
-        which could be very costly in time or space if data arrays are large.
+        As they lack a keyword interface, these operations provide no tolerance options,
+        so they always check absolutely everything.  Especially, they perform **full
+        data-array comparisons**, which can have very high performance costs if data
+        arrays are large.
 
 .. _utils_indexing:
 

lib/ncdata/utils/_compare_nc_datasets.py

@@ -96,6 +96,23 @@ def dataset_differences(
         A list of "error" strings, describing differences between the inputs.
         If empty, no differences were found.
 
+    Examples
+    --------
+    .. doctest::
+
+        >>> data = NcData(
+        ...    name="a",
+        ...    variables=[NcVariable("b", data=[1, 2, 3, 4])],
+        ...    attributes={"a1": 4}
+        ... )
+        >>> data2 = data.copy()
+        >>> data2.avals.update({"a1":3, "v":7})
+        >>> data2.variables["b"].data = np.array([1, 7, 3, 99])  # must be an array!
+        >>> print('\n'.join(dataset_differences(data, data2)))
+        Dataset attribute lists do not match: ['a1'] != ['a1', 'v']
+        Dataset "a1" attribute values differ : 4 != 3
+        Dataset variable "b" data contents differ, at 2 points: @INDICES[(1,), (3,)] : LHS=[2, 4], RHS=[7, 99]
+
     See Also
     --------
     :func:`~ncdata.utils.variable_differences`