Test and documentation utilities

genno.testing.add_dantzig(c: Computer)

Add contents analogous to the ixmp Dantzig scenario.

genno.testing.add_large_data(c: Computer, num_params, N_dims=6, N_data=0)

Add nodes to c that return large-ish data.

The result is a matrix wherein the Cartesian product of all the keys is very large— about 2e17 elements for N_dim = 6—but the contents are very sparse. This can be handled by SparseDataArray, but not by xarray.DataArray backed by numpy.ndarray.

genno.testing.add_test_data(c: Computer)

add_test_data() operating on a Computer, not an ixmp.Scenario.

genno.testing.assert_logs(caplog, message_or_messages=None, at_level=None)

Assert that message_or_messages appear in logs.

Use assert_logs as a context manager for a statement that is expected to trigger certain log messages. assert_logs checks that these messages are generated.

Derived from ixmp.testing.assert_logs().

Example

>>> def test_foo(caplog):
...     with assert_logs(caplog, 'a message'):
...         logging.getLogger(__name__).info('this is a message!')

Parameters:

• caplog (object) – The pytest caplog fixture.

• message_or_messages (str or list of str) – String(s) that must appear in log messages.

• at_level (int, optional) – Messages must appear on ‘genno’ or a sub-logger with at least this level.

genno.testing.assert_qty_allclose(a, b, check_type: bool = True, check_attrs: bool = True, ignore_extra_coords: bool = False, **kwargs)

Assert that objects a and b have numerically close values.

Parameters:

• check_type (bool, optional) – Assert that a and b are both Quantity instances. If False, the arguments are converted to Quantity.

• check_attrs (bool, optional) – Also assert that check that attributes are identical.

• ignore_extra_coords (bool, optional) – Ignore extra coords that are not dimensions. Only meaningful when Quantity is SparseDataArray.

genno.testing.assert_qty_equal(a, b, check_type: bool = True, check_attrs: bool = True, ignore_extra_coords: bool = False, **kwargs)

Assert that objects a and b are equal.

Parameters:

• check_type (bool, optional) – Assert that a and b are both Quantity instances. If False, the arguments are converted to Quantity.

• check_attrs (bool, optional) – Also assert that check that attributes are identical.

• ignore_extra_coords (bool, optional) – Ignore extra coords that are not dimensions. Only meaningful when Quantity is SparseDataArray.

genno.testing.assert_units(qty: AnyQuantity, exp: str) → None

Assert that qty has units exp.

genno.testing.get_test_quantity(key: Key) → AnyQuantity

Computation that returns test data.

genno.testing.parametrize_copy_on_write(monkeypatch, request)

Fixture to run tests with pandas copy-on-write either enabled or disabled.

genno.testing.parametrize_quantity_class(request)

Fixture to run tests twice, for both Quantity implementations.

genno.testing.pytest_runtest_makereport(item, call)

Pytest hook to unwrap genno.ComputationError.

This allows to “xfail” tests more precisely on the underlying exception, rather than the ComputationError which wraps it.

genno.testing.pytest_sessionstart(session)

Quiet some loggers.

genno.testing.raises_or_warns(value, *args, **kwargs) → ContextManager

Context manager for tests that pytest.raises() or pytest.warns().

If value is a context manager—such as returned by pytest.raises(), it is used directly.

Examples

@pytest.mark.parametrize(
    "input, output", (("FOO", 1), ("BAR", pytest.raises(ValueError)))
)
def test_myfunc0(input, expected):
    with raises_or_warns(expected, DeprecationWarning, match="FOO"):
        assert expected == myfunc(input)

In this example:

• myfunc("FOO") is expected to emit DeprecationWarning and return 1.

• myfunc("BAR") is expected to raise ValueError and issue no warning.

@pytest.mark.parametrize(
    "input, output", (("FOO", 1), ("BAR", pytest.raises(ValueError)))
)
def test_myfunc1(input, expected):
    with raises_or_warns(expected, None):
        assert expected == myfunc(input)

In this example, no warnings are expected from myfunc("FOO").

genno.testing.random_qty(shape: dict[str, int], **kwargs) → AnyQuantity

Return a Quantity with shape and random contents.

Parameters:

• shape (dict) – Mapping from dimension names (str) to lengths along each dimension (int).

• **kwargs – Other keyword arguments to Quantity.

Returns:

Random data with one dimension for each key in shape, and coords along those dimensions like “foo1”, “foo2”, with total length matching the value from shape. If shape is empty, a scalar (0-dimensional) Quantity.

Return type:

Quantity

genno.testing.test_data_path()

Path to the directory containing test data.

genno.testing.ureg()

Application-wide units registry.

Testing Juypter notebooks.

Copied 2023-04-27 from the corresponding module in ixmp.

genno.testing.jupyter.get_cell_output(nb, name_or_index, kind='data')

Retrieve a cell from nb according to its metadata name_or_index:

The Jupyter notebook format allows specifying a document-wide unique ‘name’ metadata attribute for each cell:

https://nbformat.readthedocs.io/en/latest/format_description.html #cell-metadata

Return the cell matching name_or_index if str; or the cell at the int index; or raise ValueError.

Parameters:

kind (str, optional) – Kind of cell output to retrieve. For ‘data’, the data in format ‘text/plain’ is run through eval(). To retrieve an exception message, use ‘evalue’.

genno.testing.jupyter.run_notebook(nb_path, tmp_path, env=None, **kwargs)

Execute a Jupyter notebook via nbclient and collect output.

Parameters:

• nb_path (os.PathLike) – The notebook file to execute.

• tmp_path (os.PathLike) – A directory in which to create temporary output.

• env (collections.abc.Mapping, optional) – Execution environment for nbclient. Default: os.environ.

• kwargs –

  Keyword arguments for nbclient.NotebookClient. Defaults are set for:

  ”allow_errors”

  Default False. If True, the execution always succeeds, and cell output contains exception information rather than code outputs.

  ”kernel_version”

  Jupyter kernel to use. Default: either “python2” or “python3”, matching the current Python major version.

  Warning

  Any existing configuration for this kernel on the local system— such as an IPython start-up file—will be executed when the kernel starts. Code that enables GUI features can interfere with run_notebook().

  ”timeout”

  in seconds; default 10.

Returns:

• nb (nbformat.NotebookNode) – Parsed and executed notebook.

• errors (list) – Any execution errors.

class genno.compat.sphinx.autodoc_operator.OperatorDocumenter(directive: DocumenterBridge, name: str, indent: str = '')

classmethod can_document_member(member, membername, isattr, parent) → bool

Called to see if a member can be documented by this Documenter.

genno.compat.sphinx.autodoc_operator.setup(app: sphinx.application.Sphinx)

Configure sphinx.ext.autodoc to handle Operator as functions.

Resolve missing references using aliased target names, domains, and/or types.

Expanded from and with thanks for https://stackoverflow.com/a/62301461.

genno.compat.sphinx.rewrite_refs.apply_alias(config: Mapping[str, str], node) → bool

Apply config to node.

genno.compat.sphinx.rewrite_refs.resolve_internal_aliases(app: sphinx.application.Sphinx, doctree)

Handler for ‘doctree-read’ events.

genno.compat.sphinx.rewrite_refs.resolve_intersphinx_aliases(app, env, node, contnode)

Handler for ‘missing-reference’ (intersphinx) events.

genno.compat.sphinx.rewrite_refs.setup(app: sphinx.application.Sphinx)

Connect rewrite_refs event handlers.