Ctrl+K

Test and documentation utilities

Test and documentation utilities#

genno.testing.add_dantzig(c: Computer)[source]#

Add contents analogous to the ixmp Dantzig scenario.

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

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)[source]#

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

genno.testing.assert_logs(caplog, message_or_messages=None, at_level=None)[source]#

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)[source]#

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)[source]#

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[source]#

Assert that qty has units exp.

genno.testing.get_test_quantity(key: Key) → AnyQuantity[source]#

Computation that returns test data.

genno.testing.parametrize_copy_on_write(monkeypatch, request)[source]#

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

genno.testing.parametrize_quantity_class(request)[source]#

Fixture to run tests twice, for both Quantity implementations.

genno.testing.pytest_runtest_makereport(item, call)[source]#

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.raises_or_warns(value, *args, **kwargs) → ContextManager[source]#

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:

@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[source]#

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()[source]#

Path to the directory containing test data.

genno.testing.ureg()[source]#

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')[source]#

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)[source]#

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:

class genno.compat.sphinx.autodoc_operator.OperatorDocumenter(directive: DocumenterBridge, name: str, indent: str = '')[source]#
classmethod can_document_member(member, membername, isattr, parent) → bool[source]#

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

genno.compat.sphinx.autodoc_operator.setup(app: sphinx.application.Sphinx)[source]#

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[source]#

Apply config to node.

genno.compat.sphinx.rewrite_refs.resolve_internal_aliases(app: sphinx.application.Sphinx, doctree)[source]#

Handler for ‘doctree-read’ events.

genno.compat.sphinx.rewrite_refs.resolve_intersphinx_aliases(app, env, node, contnode)[source]#

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

genno.compat.sphinx.rewrite_refs.setup(app: sphinx.application.Sphinx)[source]#

Connect rewrite_refs event handlers.

Contents