Merge pull request #135 from khaeru/enh/2024-W11

Miscellaneous enhancements for 2024-W11

.github/workflows/pytest.yaml

@@ -32,7 +32,7 @@ jobs:
         - {version: "3.10", extras: ",sparse"}
         - {version: "3.11", extras: ",sparse"}
         # Latest release / latest supported by genno / testable on GHA
-        - {version: "3.12", extras: ""}
+        - {version: "3.12", extras: ",sparse"}
 
         # For fresh releases and development versions of Python, compiled binary
         # wheels are not available for some dependencies, e.g. numpy, pandas.

.pre-commit-config.yaml

@@ -11,6 +11,7 @@ repos:
     - pytest
     - sdmx1
     - Sphinx
+    - types-docutils
     - types-PyYAML
     - types-pytz
     - types-python-dateutil

README.rst

@@ -1,34 +1,35 @@
 genno: efficient, transparent calculation on N-D data
 *****************************************************
-
-.. image:: https://img.shields.io/pypi/v/genno.svg
-   :target: https://pypi.python.org/pypi/genno/
-   :alt: PyPI version
-
-.. image:: https://readthedocs.org/projects/genno/badge/?version=latest
-   :target: https://genno.readthedocs.io/en/latest/?badge=latest
-   :alt: Documentation build
-
-.. image:: https://github.com/khaeru/genno/actions/workflows/pytest.yaml/badge.svg
-   :target: https://github.com/khaeru/genno/actions/workflows/pytest.yaml
-   :alt: Build status
-
-.. image:: https://codecov.io/gh/khaeru/genno/branch/main/graph/badge.svg
-   :target: https://codecov.io/gh/khaeru/genno
-   :alt: Test coverage
+|pypi| |rtd| |gha| |codecov|
 
 **genno** is a Python package for describing and executing complex calculations on labelled, multi-dimensional data.
-It aims to make these calculations efficient, transparent, and easily validated as part of scientific research.
+It aims to make these calculations efficient, transparent, modular, and easily validated as part of scientific research.
 
-genno is built on high-quality Python data packages including ``dask``, ``xarray``, and ``pint``; and provides (current or planned) compatibility with packages including ``pandas``, ``matplotlib``, ``plotnine``, ``ixmp``, ``sdmx1``, and ``pyam``.
+genno is built on high-quality Python data packages including ``dask``, ``xarray``, ``pandas``, and ``pint``; and provides (current or planned) compatibility with packages including  ``plotnine``, ``matplotlib``,  ``sdmx1``, ``ixmp``, and ``pyam``.
 
 A 玄能 (*genno* or *gennoh*) is a type of hammer used in Japanese woodworking.
 The package name is warning, by reference, to the adage “When you hold a hammer, every problem looks like a nail”: you shouldn't hit everything with ``genno``, but it is still a useful and versatile tool.
 
-
 License
 =======
 
 Copyright © 2018–2024 genno contributors.
 
 Licensed under the GNU General Public License, version 3.0.
+
+
+.. |pypi| image:: https://img.shields.io/pypi/v/genno.svg
+   :target: https://pypi.python.org/pypi/genno/
+   :alt: PyPI version
+
+.. |rtd| image:: https://readthedocs.org/projects/genno/badge/?version=latest
+   :target: https://genno.readthedocs.io/en/latest/?badge=latest
+   :alt: Documentation build
+
+.. |gha| image:: https://github.com/khaeru/genno/actions/workflows/pytest.yaml/badge.svg
+   :target: https://github.com/khaeru/genno/actions/workflows/pytest.yaml
+   :alt: Build status
+
+.. |codecov| image:: https://codecov.io/gh/khaeru/genno/branch/main/graph/badge.svg
+   :target: https://codecov.io/gh/khaeru/genno
+   :alt: Test coverage

doc/api-operator.rst

@@ -0,0 +1,62 @@
+Operators
+*********
+
+.. automodule:: genno.operator
+   :members:
+
+   Unless otherwise specified, these functions accept and return :class:`.Quantity` objects for data arguments/return values.
+   The names and signatures of many operators match the corresponding methods on the :class:`.Quantity` class, and thus also the :class:`.xarray.DataArray` methods of the same names.
+
+   Genno's :ref:`compatibility modules <compat>` each provide additional operators.
+
+   Numerical operators:
+
+   .. autosummary::
+      add
+      aggregate
+      broadcast_map
+      clip
+      combine
+      disaggregate_shares
+      div
+      group_sum
+      index_to
+      interpolate
+      mul
+      pow
+      product
+      ratio
+      round
+      sub
+      sum
+      add_sum
+      where
+
+   Data manipulation and transformation:
+
+   .. autosummary::
+      apply_units
+      as_quantity
+      assign_units
+      concat
+      convert_units
+      drop_vars
+      relabel
+      rename
+      rename_dims
+      select
+      unique_units_from_dim
+
+   Input and output:
+
+   .. autosummary::
+      load_file
+      add_load_file
+      write_report
+
+Helper functions for adding tasks to Computers
+----------------------------------------------
+
+.. autofunction:: add_binop
+.. autofunction:: add_load_file
+.. autofunction:: add_sum

doc/api-quantity.rst

@@ -0,0 +1,37 @@
+Quantity classes
+****************
+
+.. currentmodule:: genno.core.attrseries
+
+.. autoclass:: AttrSeries
+   :members:
+
+   .. py:attribute:: name
+
+      The name of this Quantity.
+
+      Like :attr:`.xarray.DataArray.name`.
+
+.. automodule:: genno.core.attrseries
+   :members:
+   :exclude-members: AttrSeries
+
+.. currentmodule:: genno.core.sparsedataarray
+
+.. automodule:: genno.core.sparsedataarray
+   :members: SparseDataArray, SparseAccessor
+
+.. currentmodule:: genno.core.base
+
+.. automodule:: genno.core.base
+   :members:
+
+.. currentmodule:: genno.core.quantity
+
+.. automodule:: genno.core.quantity
+   :members:
+   :exclude-members: assert_quantity, get_class, set_class
+
+.. currentmodule:: genno.compat.xarray
+
+.. autoclass:: DataArrayLike

doc/api-testing.rst

@@ -0,0 +1,8 @@
+Test utilities and fixtures
+***************************
+
+.. automodule:: genno.testing
+   :members:
+
+.. automodule:: genno.testing.jupyter
+   :members:

doc/api-util.rst

@@ -0,0 +1,27 @@
+Utilities and compatibility
+***************************
+
+.. automodule:: genno.compat.graphviz
+   :members:
+
+.. automodule:: genno.compat.pandas
+   :members:
+
+.. automodule:: genno.core.describe
+   :members:
+
+.. automodule:: genno.core.graph
+   :members:
+
+.. automodule:: genno.core.key
+   :members: KeyLike, iter_keys, single_key
+
+.. automodule:: genno.core.operator
+   :members:
+   :exclude-members: Operator
+
+.. automodule:: genno.types
+   :members:
+
+.. automodule:: genno.util
+   :members: