Parse (#1)

Author: MusicalNinjaDad

.github/workflows/check-python.yml

@@ -40,10 +40,23 @@ jobs:
         
   lint:
     runs-on: ubuntu-latest
+    env:
+      ruff_args: ""
+      python-version: '3.13'
     steps:
     - uses: actions/checkout@v4
-    - name: Ruff
-      uses: chartboost/ruff-action@v1
+    - name: Set stricter linting rules for PR / `main`
+      run: |
+        if [[ "${{ github.event_name }}" == "pull_request" || ( "${{ github.event_name }}" == "push" && "${{ github.ref }}" == "refs/heads/main" ) ]]; then
+          echo "ruff_args=--config ruff-main.toml" >> $GITHUB_ENV
+        fi
+    - name: Install uv
+      uses: astral-sh/setup-uv@v5
+      with:
+        python-version: ${{ env.python-version }}
+    - name: lint with ruff ${{ env.ruff_args }}
+      run: |
+        uv run --no-default-groups --group lint ruff check . ${{ env.ruff_args }}
 
   type-check:
     env:

.github/workflows/publish-python.yml

@@ -35,7 +35,7 @@ jobs:
   publish:
     environment: 
       name: pypi
-      url: https://pypi.org/p/ttrpg-dice
+      url: https://pypi.org/p/pytest-ipynb2
     permissions:
       id-token: write
     needs: [python-checks, build]

CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+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).
+
+## [Unreleased]
+
+## [0.0.1] - 2025-02-12
+
+### Added
+
+- Initial release of `pytest-ipynb2`.
+- Added support for running tests in Jupyter Notebooks.
+- Implemented `Notebook` class for parsing notebooks and extracting code and test cells.
+- Added GitHub Actions workflows for CI/CD, including linting, testing, type-checking, and publishing.
+- Added `justfile` for common development tasks.
+- Configured `pyproject.toml` with project metadata, dependencies, and tool configurations.

README.md

@@ -0,0 +1,3 @@
+# pytest-ipynb2
+
+A pytest plugin to run tests in Jupyter Notebooks. Designed to integrate with [chmp/ipytest](https://github.com/chmp/ipytest).

docs/index.md

@@ -0,0 +1,3 @@
+# Overview
+
+A pytest plugin to run tests in Jupyter Notebooks. Designed to integrate with [chmp/ipytest](https://github.com/chmp/ipytest).

docs/python-api.md

@@ -0,0 +1,3 @@
+# API
+
+::: pytest_ipynb2

justfile

@@ -58,4 +58,4 @@ show-cov:
 
 # serve python docs on localhost:3000
 docs:
-  uv run jupyter book start --execute
+  uv run mkdocs serve

mkdocs.yml

@@ -0,0 +1,70 @@
+site_name: "pytest-ipynb2"
+repo_url: https://github.com/MusicalNinjaDad/pytest-ipynb2
+repo_name: MusicalNinjaDad/pytest-ipynb2
+
+watch:
+- pytest_ipynb2 # To update live preview when docstrings change
+
+theme:
+  name: "material"
+  icon:
+    logo: material/test-tube
+  palette: # Palette toggles for auto-light-dark mode
+  - media: "(prefers-color-scheme)"
+    toggle:
+      icon: material/link
+      name: Switch to light mode
+  - media: "(prefers-color-scheme: light)"
+    scheme: default 
+    toggle:
+      icon: material/toggle-switch
+      name: Switch to dark mode
+  - media: "(prefers-color-scheme: dark)"
+    scheme: slate
+    toggle:
+      icon: material/toggle-switch-off-outline
+      name: Switch to system preference
+  features:
+    - navigation.expand
+    - navigation.path
+    - toc.integrate
+    - navigation.indexes
+
+plugins:
+- search
+- mkdocstrings:
+    handlers:
+      python:
+        options:
+          members: true
+          show_bases: false
+          show_root_heading: true
+          heading_level: 2
+          show_root_full_path: false
+          show_symbol_type_toc: true
+          show_symbol_type_heading: true
+          signature_crossrefs: true
+          separate_signature: true
+          show_signature_annotations: true
+          docstring_section_style: spacy
+          docstring_options:
+            ignore_init_summary: true
+          merge_init_into_class: true
+
+markdown_extensions:
+- admonition
+- pymdownx.details
+- pymdownx.highlight
+- pymdownx.inlinehilite
+- pymdownx.snippets:
+    url_download: true
+    base_path: !relative $docs_dir
+- pymdownx.superfences
+- attr_list
+- pymdownx.emoji:
+    emoji_index: !!python/name:material.extensions.emoji.twemoji
+    emoji_generator: !!python/name:material.extensions.emoji.to_svg
+
+nav:
+  - index.md
+  - python-api.md

pyproject.toml

@@ -17,6 +17,7 @@
     dependencies = [
         "ipython",
         "ipytest",
+        "nbformat>=5.10.4",
         "pytest",
         "typing-extensions; python_version < '3.11'",
     ]
@@ -52,9 +53,7 @@
         "pytype; python_version <= '3.12'",
         "typing_extensions", # required for Python3.10 and below
     ]
-    test = [
-        "pytest-doctest-mkdocstrings",
-        ]
+    test = ["pytest-doctest-mkdocstrings"]
     cov = [
         {include-group = "test"},
         "pytest-cov",
@@ -64,14 +63,15 @@
         "mkdocs",
         "mkdocstrings[python]",
         "mkdocs-material",
+        "pymdown-extensions",
     ]
     dev = [
-        "jupyter",
         {include-group = "lint"},
         {include-group = "typing"},
         {include-group = "test"},
         {include-group = "cov"},
         {include-group = "doc"},
+        "jupyter", # python's toml decoder won't accept a text entry at the start of the array, only at the end!!
     ]
 
 [tool.pytest.ini_options]
@@ -99,7 +99,7 @@ exclude_also = [
     show_contexts = true
 
 [tool.pytype]
-inputs = ["pytest_ipynb2"]
+    inputs = ["pytest_ipynb2"]
 
 [tool.ruff]
     line-length = 120
@@ -163,5 +163,9 @@ inputs = ["pytest_ipynb2"]
     ]
 
     "**/*.ipynb" = [
-        "T201", # Allow `print` in Jupyter notebooks
+        "T201",    # Allow `print` in Jupyter notebooks
+        "ANN",     # Missing type annotations
+        "S101",    # Use of `assert`
+        "PLR2004", # Magic number comparisons
+        "D1",      # Don't REQUIRE docstrings in notebooks - but lint them if they are there
     ]

pytest_ipynb2/__init__.py

@@ -1 +1,3 @@
-"""Pytest plugin to run tests in Jupyter Notebooks."""
+"""Pytest plugin to run tests in Jupyter Notebooks."""
+
+from ._ipynb_parser import Notebook

pytest_ipynb2/_ipynb_parser.py

@@ -0,0 +1,38 @@
+"""Parse notebooks."""
+
+import json
+from pathlib import Path
+
+import nbformat
+
+
+class Notebook:
+    """
+    An ipython Notebook.
+     
+    - constructor from Path
+    - methods to get various cell types
+    - a `test` cell type identified by the `%%ipytest` cell magic.
+    """
+
+    def __init__(self, filepath: Path) -> None:
+        rawcontents = filepath.read_text()
+        contents = json.loads(rawcontents)
+        nbformat.validate(contents)
+        self.contents = contents
+
+    def getcodecells(self) -> dict[int, str]:
+        """Return parsed code cells from a notebook."""
+        return {
+            cellnr: "".join(cell["source"])
+            for cellnr, cell in enumerate(self.contents["cells"])
+            if cell["cell_type"] == "code" and not cell["source"][0].startswith(r"%%ipytest")
+        }
+
+    def gettestcells(self) -> dict[int, str]:
+        """Return parsed test cells from a notebook. Identified by cell magic `%%ipytest`."""
+        return {
+            cellnr: "".join(cell["source"][1:]).strip()
+            for cellnr, cell in enumerate(self.contents["cells"])
+            if cell["cell_type"] == "code" and cell["source"][0].startswith(r"%%ipytest")
+        }

ruff-main.toml

@@ -0,0 +1,5 @@
+# Additional linting rules applied to PRs and `main`branch
+extend = "pyproject.toml"
+lint.extend-select = [
+    "TD",  # TODOs need a description, even outside of `main`
+]

tests/assets/notebook.ipynb

@@ -0,0 +1,90 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# A notebook to test against"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# This cell sets some global variables\n",
+    "\n",
+    "x = 1\n",
+    "y = 2\n",
+    "\n",
+    "x + y\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Includes a few functions and tests ..."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Define a function\n",
+    "\n",
+    "def adder(a, b):\n",
+    "    return a+b"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%%ipytest\n",
+    "\n",
+    "def test_adder():\n",
+    "    assert adder(1,2) == 3\n",
+    "\n",
+    "def test_globals():\n",
+    "    assert x == 1"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def another_function(*args):\n",
+    "    return args"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": ".venv",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.13.1"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

tests/assets/notebook.py

@@ -0,0 +1,21 @@
+#ruff: noqa
+# This cell sets some global variables
+
+x = 1
+y = 2
+
+x + y
+
+# Define a function
+
+def adder(a, b):
+    return a+b
+
+def test_adder():
+    assert adder(1,2) == 3
+
+def test_globals():
+    assert x == 1
+
+def another_function(*args):
+    return args