Tidy (#26)

Author: MusicalNinjaDad

CHANGELOG.md

@@ -5,13 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.1] - 2025-02-19
+
+### Changed
+
+- Improved documentation
+- Explicitly show test helpers are an internal concern
+- Tidied up test assets
+
 ## [0.2.0] - 2025-02-19
 
-## Added
+### Added
 
 - Test execution reporting in session log and short summary report: [#21][pr-21] & [#24][pr-24]
 
-## Changed
+### Changed
 
 - `_parser.Notebook` API changed: added `.codecells` and `.testcells`, removed `get_codecells()`, `get_testcells()`, `.contents`
 

README.md

@@ -1,5 +1,60 @@
 # pytest-ipynb2
 
-A pytest plugin to run tests in Jupyter Notebooks. Designed to integrate with [chmp/ipytest](https://github.com/chmp/ipytest).
+A pytest plugin to run tests in Jupyter Notebooks.
 
-For more details including installation, usage and known-issues: see the [docs](https://musicalninjadad.github.io/pytest-ipynb2)
+Designed to play nicely with [chmp/ipytest](https://github.com/chmp/ipytest).
+
+## Why?
+
+My use case is so that I can teach my son to code and use notebooks to do that but still have the tests show up in vscode test explorer.
+
+We also like to have all our tests run in a github workflow - and this makes that simple too.
+
+## Usage
+
+Usage is very simple:
+
+1. Install from pypi (e.g. with pip):
+
+    ```sh
+    pip install pytest-ipynb2
+    ```
+
+1. Enable by adding to the default options in `pyproject.toml` ``:
+
+    ```toml
+    [tool.pytest.ini_options]
+      addopts = [
+        "-p pytest_ipynb2.plugin",
+      ]
+    ```
+
+1. That's it! pytest will now collect and execute any tests in jupyter notebooks when run form the command line or IDE.
+
+## Test identification
+
+I'm assuming you also want to run your tests inside your notebooks ... so simply use the `%%ipytest` magic in a cell and pytest will collect any tests based on the usual naming and identification rules.
+
+> **Note:** tests will *only* be identified in cells which use the `%%ipytest` magic
+
+## Documentation
+
+For more details see the [docs](https://musicalninjadad.github.io/pytest-ipynb2)
+
+## Features
+
+- Enables pytest to collect and execute tests stored within jupyter notebooks
+- Provides meaningful test logs identifying the notebook, cell and test function
+- Handles tests with fixtures and parametrization
+- Executes *all cells above* the test cell before running the tests in that cell.
+
+    >WARNING: this means that if any previous cells have side-effects they will occur on test collection, just as they would if included in a pytest test module.
+
+## Known limitations & To-Dos
+
+This is an early version. The following things are still on my to-do list:
+
+- Handling tests grouped into classes [#22](https://github.com/MusicalNinjaDad/pytest-ipynb2/issues/22) (might work - I've not checked yet)
+- Assertion re-writing. Failed tests don't yet give the expected quality of pytest output about the failure [#20](https://github.com/MusicalNinjaDad/pytest-ipynb2/issues/20) (Workaround - re-run the test using ipytest inside the notebook)
+- v1.0.0 will include dedicated commandline options rather than requiring you to specify the plugin [#12](https://github.com/MusicalNinjaDad/pytest-ipynb2/issues/12)
+- This won't play nicely with other magics or direct calls to ipytest functions yet [#23](https://github.com/MusicalNinjaDad/pytest-ipynb2/issues/23)

__pyversion__

@@ -1 +1 @@
-0.2.0
+0.2.1

docs/index.md

@@ -0,0 +1 @@
+../README.md

docs/index.md

@@ -1,5 +1,5 @@
-# Parser (internal)
+# _parser
 
-The parser will likely be deprecated and merged into the plug-in classes in the future
+> **Warning**: The parser is currently an internal concern and changes will not necessarily be reflected in semver.
 
 ::: pytest_ipynb2._parser

docs/parser.md

@@ -1,3 +1,3 @@
-# Pytest plugin
+# Plugin - API
 
 ::: pytest_ipynb2.plugin

docs/plugin.md

@@ -1,3 +1,5 @@
 # Test helpers
 
-::: pytest_ipynb2.pytester_helpers
+> **Warning**: These helpers are currently an internal concern and changes will not necessarily be reflected in semver.
+
+::: pytest_ipynb2._pytester_helpers

docs/test_helpers.md

@@ -42,7 +42,6 @@ plugins:
     handlers:
       python:
         options:
-          members: true
           show_bases: false
           show_root_heading: true
           heading_level: 2
@@ -52,6 +51,7 @@ plugins:
           signature_crossrefs: true
           separate_signature: true
           show_signature_annotations: true
+          show_source: false
           docstring_section_style: spacy
           docstring_options:
             ignore_init_summary: true

mkdocs.yml

@@ -13,14 +13,14 @@
 
 class SourceList(list):
     """
-    A list with non-continuous indices for storing the contents of cells.
+    A `list` with non-continuous indices for storing the contents of cells.
 
-    - use slicing: sourcelist[:], not list(sourcelist) to get contents.
-    - supports .ids() analog to a mapping.keys(), yielding only cell-ids with source.
-    - use .items() analog to a mapping, rather than enumerate().
+    - use a full slice `sourcelist[:]`, not list(sourcelist) to get contents.
+    - supports `.ids()` analog to a mapping.keys(), yielding only cell-ids with source.
     """
 
     def ids(self) -> Generator[int, None, None]:
+        """Analog to mapping `.keys()`, yielding only cell-ids with source."""
         for key, source in enumerate(self):
             if source is not None:
                 yield key
@@ -32,6 +32,14 @@ def __getitem__(self, index: SupportsIndex) -> str: ...
     def __getitem__(self, index: slice) -> list[str]: ...
 
     def __getitem__(self, index):
+        """
+        Behaves as you would expect for a `list` with the following exceptions.
+
+        - If provided with a single `index`: Raises an IndexError if the element at `index` does not
+            contain any relevant source.
+        - If provided with a `slice`: Returns only those items, which contain relevant source.
+
+        """
         underlying_list = list(self)
         if isinstance(index, slice):
             return [source for source in underlying_list[index] if source is not None]
@@ -44,17 +52,19 @@ def __getitem__(self, index):
 
 class Notebook:
     """
-    An ipython Notebook.
+    The relevant bits of an ipython Notebook.
 
-    - constructor from Path
-    - methods to get various cell types
-    - a `test` cell type identified by the `%%ipytest` cell magic.
+    Attributes:
+        codecells (SourceList): The code cells *excluding* any identified as test cells.
+        testcells (SourceList): The code cells which are identified as containing tests, based
+            upon the presence of the `%%ipytest`magic.
     """
 
     def __init__(self, filepath: Path) -> None:
         contents = nbformat.read(fp=str(filepath), as_version=4)
         nbformat.validate(contents)
         cells = contents.cells
+
         for cell in cells:
             cell.source = [
                 sourceline for sourceline in cell.source.splitlines() if not sourceline.startswith("ipytest")
@@ -65,9 +75,11 @@ def __init__(self, filepath: Path) -> None:
             else None
             for cell in cells
         )
+        """The code cells *excluding* any identified as test cells"""
         self.testcells = SourceList(
             "\n".join(line for line in cell.source if not line.startswith(r"%%ipytest")).strip()
             if cell.cell_type == "code" and any(line.startswith(r"%%ipytest") for line in cell.source)
             else None
             for cell in cells
         )
+        """The code cells which are identified as containing tests, based upon the presence of the `%%ipytest`magic."""

pytest_ipynb2/_parser.py

@@ -230,3 +230,8 @@ def example_dir(request: ExampleDirRequest, pytester: pytest.Pytester) -> Collec
         dir_node=dir_node,
         items=pytester.genitems([dir_node]),
     )
+
+
+def add_ipytest_magic(source: str) -> str:
+    """Add %%ipytest magic to the source code."""
+    return f"%%ipytest\n\n{source}"

pytest_ipynb2/pytester_helpers.py renamed to pytest_ipynb2/_pytester_helpers.py

@@ -74,11 +74,11 @@ def _getobj(self) -> ModuleType:
         return dummy_module
 
     def _reportinfo(self: pytest.Item) -> tuple[str, int, str | None]:
-        """Pytest checks whether `.obj.__code__.co_filename` matches `.path`."""
+        """Override pytest which checks `.obj.__code__.co_filename` == `.path`."""
         return self.path, 0, self.getmodpath()
 
-    def collect(self) -> Generator[pytest.Function | pytest.Class, None, None]:
-        """Hacky hack overriding of reportinfo."""
+    def collect(self) -> Generator[pytest.Function, None, None]:
+        """Replace the reportinfo method on the children, if present."""
         for item in super().collect():
             if hasattr(item, "reportinfo"):  # pragma: no branch # TODO(MusicalNinjaDad): #22 Tests grouped in Class
                 item.reportinfo = self._reportinfo

pytest_ipynb2/plugin.py

@@ -1,5 +1,3 @@
-%%ipytest
-
 def test_fails():
     x = 1
     assert x == 2

tests/assets/globals_test.py

@@ -1,5 +1,3 @@
-%%ipytest
-
 import pytest
 
 @pytest.fixture

tests/assets/failing_test.py renamed to tests/assets/test_failing.py

@@ -0,0 +1,2 @@
+def test_globals():
+    assert x == 1

tests/assets/fixture_test.py renamed to tests/assets/test_fixture.py

@@ -1,5 +1,3 @@
-%%ipytest
-
 import pytest
 
 @pytest.mark.parametrize(

tests/assets/test_globals.py

@@ -1,4 +1,2 @@
-%%ipytest
-
 def test_pass():
     assert True

tests/assets/param_test.py renamed to tests/assets/test_param.py

@@ -1,6 +1,6 @@
 import pytest
 
-pytest_plugins = ["pytester", "pytest_ipynb2.pytester_helpers"]
+pytest_plugins = ["pytester", "pytest_ipynb2._pytester_helpers"]
 
 
 def pytest_collection_modifyitems(config: pytest.Config, items: list[pytest.Function]) -> None:  # noqa: ARG001

tests/assets/passing_test.py renamed to tests/assets/test_passing.py

@@ -4,7 +4,7 @@
 
 import pytest_ipynb2
 import pytest_ipynb2.plugin
-from pytest_ipynb2.pytester_helpers import CollectedDir, CollectionTree, ExampleDir
+from pytest_ipynb2._pytester_helpers import CollectedDir, CollectionTree, ExampleDir
 
 
 @pytest.fixture

tests/conftest.py

@@ -7,10 +7,10 @@
 
 import pytest
 
-from pytest_ipynb2.pytester_helpers import CollectionTree, ExampleDir
+from pytest_ipynb2._pytester_helpers import CollectionTree, ExampleDir
 
 if TYPE_CHECKING:
-    from pytest_ipynb2.pytester_helpers import CollectedDir
+    from pytest_ipynb2._pytester_helpers import CollectedDir
 
 
 @pytest.fixture

tests/test_collection.py

@@ -3,7 +3,7 @@
 import nbformat
 import pytest
 
-from pytest_ipynb2.pytester_helpers import CollectedDir, ExampleDir
+from pytest_ipynb2._pytester_helpers import CollectedDir, ExampleDir, add_ipytest_magic
 
 tests = [
     pytest.param(
@@ -32,17 +32,17 @@
     ),
     pytest.param(
         ExampleDir(
-            notebooks={"generated": [Path("tests/assets/passing_test.py").read_text()]},
+            notebooks={"generated": [add_ipytest_magic(Path("tests/assets/test_passing.py").read_text())]},
         ),
         {
             "generated.ipynb": [
-                "\n".join(  # noqa: FLY002
-                    [
-                        r"%%ipytest",
-                        "",
-                        "def test_pass():",
-                        "    assert True",
-                    ],
+                add_ipytest_magic(
+                    "\n".join(  # noqa: FLY002
+                        [
+                            "def test_pass():",
+                            "    assert True",
+                        ],
+                    ),
                 ),
             ],
         },
@@ -53,7 +53,7 @@
             notebooks={
                 "generated": [
                     Path("tests/assets/import_ipytest.py").read_text(),
-                    Path("tests/assets/passing_test.py").read_text(),
+                    add_ipytest_magic(Path("tests/assets/test_passing.py").read_text()),
                 ],
             },
         ),
@@ -66,13 +66,13 @@
                         "",
                     ],
                 ),
-                "\n".join(  # noqa: FLY002
-                    [
-                        r"%%ipytest",
-                        "",
-                        "def test_pass():",
-                        "    assert True",
-                    ],
+                add_ipytest_magic(
+                    "\n".join(  # noqa: FLY002
+                        [
+                            "def test_pass():",
+                            "    assert True",
+                        ],
+                    ),
                 ),
             ],
         },

tests/test_collectiontree.py

@@ -3,7 +3,7 @@
 
 import pytest
 
-from pytest_ipynb2.pytester_helpers import CollectedDir, ExampleDir
+from pytest_ipynb2._pytester_helpers import CollectedDir, ExampleDir
 
 if TYPE_CHECKING:
     from pytest_ipynb2.plugin import Cell