pypad-notebook 0.1.0__tar.gz

pypad_notebook-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pughlu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pypad_notebook-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include LICENSE README.md
+include tests/vectors.json

pypad_notebook-0.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: pypad-notebook
+Version: 0.1.0
+Summary: Read, write and convert PyPad notebooks (.pypad.py) and Jupyter notebooks (.ipynb).
+Author: Philip Lewis
+License: MIT
+Project-URL: Homepage, https://pypad.dev
+Project-URL: Repository, https://github.com/pypad-dev/pypad
+Keywords: notebook,jupyter,ipynb,pypad,moodle,education
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Education
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# pypad-notebook
+
+Read, write and convert [PyPad](https://pypad.dev) notebooks (`.pypad.py`) and Jupyter notebooks (`.ipynb`). Standard library
+only; Python 3.9+.
+
+PyPad is a small in-browser Python notebook for teaching: it runs entirely in the learner's browser, fits in a Moodle quiz question, can be
+shared as a link, and its files are plain, readable Python. This package is the file-format side of it, so a notebook is never trapped.
+
+```bash
+pip install pypad-notebook
+```
+
+## Command line
+
+```bash
+pypad convert lesson.pypad.py            # -> lesson.ipynb
+pypad convert lesson.ipynb                # -> lesson.pypad.py
+pypad convert lesson.ipynb --outputs text
+pypad check lesson.pypad.py              # ok / changed / absent: is it still what PyPad wrote?  (exit 1 if changed)
+pypad embed lesson.pypad.py > question.html     # the HTML block for a Moodle question or web page
+pypad answers responses.csv --out answers/       # split a Moodle quiz "Responses" download into one file per student
+pypad verify template.pypad.py answers/*.pypad.py   # re-check them against the template (exit 1 if any are not clean)
+pypad embed lesson.pypad.py --answer-format base64 --loader https://pypad.dev/v1/pypad-mdl-quiz.js
+```
+
+`convert` never overwrites without `--force`. `check`, `convert` and `embed` also accept an HTML page that holds a notebook (an embed, or a
+PyPad "web page" export).
+
+## Marking
+
+An assessment that matters should be checked where the student cannot touch it. The widget stops mistakes in the student's browser, but the browser is
+the student's. `pypad verify` applies, on your side, the same rules the widget applies when it opens an answer (the template's `policy`, its locked cells,
+its answer cells and sections), and tells you for each answer what the student changed, added or removed, and what the rules would have put back:
+
+```
+answers/Student_Sam.pypad.py: clean (check value ok) - changed a1
+answers/Other_Oz.pypad.py: NOT CLEAN (check value ok) - changed a1
+    cell "i1" cannot be edited, and its text was put back
+```
+
+`pypad answers` turns a Moodle quiz **Responses** download (CSV) into those files, decoding stored answers.
+
+## In Python
+
+```python
+import pypad
+
+result = pypad.parse(open("lesson.pypad.py", encoding="utf-8").read())
+result.integrity            # 'ok', 'changed' or 'absent'
+result.warnings             # problems found while reading; a damaged file still opens
+nb = result.notebook        # nb.config, nb.cells[i].id / .type / .source / .settings / .outputs
+
+text = pypad.dumps(nb)                          # .pypad.py text, with its check value
+ipynb = pypad.to_ipynb_text(nb, save_outputs="text")
+nb2 = pypad.from_ipynb_text(open("lesson.ipynb", encoding="utf-8").read())
+html = pypad.build_embed(text, answer_format="plain")
+
+report = pypad.verify_answer(template_nb, answer_nb, integrity)   # report.clean, .changed_cells, .violations, ...
+```
+
+## It matches the JavaScript implementation
+
+This is a port of the reference implementation (`packages/notebook` in the PyPad repository). The same text produces the same notebook, the
+same file, the same Jupyter notebook and the same check value, including for emoji and odd characters. That is tested against a file of vectors
+that the JavaScript implementation generates (`tests/vectors.json`), so the two cannot drift apart unnoticed.
+
+## The format, in one screen
+
+```python
+# %% [pypad-start] v1 sha=3f9a1c0d7b2e4a65
+
+# %% [config] {"policy":"fixed","kernel":"skulpt"}
+
+# %% [markdown] {"id":"k3j9a0xq","editable":false}
+"""
+Print the sum of 1 and 2.
+"""
+
+# %% [code] {"id":"p8w2m1zc"}
+print(1 + 2)
+
+# %% [pypad-end]
+```
+
+Code is code and everything else sits in triple-quoted strings, so the file is (nearly) valid Python and readable anywhere. The `sha` is a check
+value of the notebook's content: it notices an editor or a hand edit changing something, and ignores indentation and line endings. It is not a
+security measure. Reading is forgiving (Jupytext-style comment blocks, indented text, Windows line endings); writing has one form.
+
+MIT licensed.

pypad_notebook-0.1.0/README.md

@@ -0,0 +1,89 @@
+# pypad-notebook
+
+Read, write and convert [PyPad](https://pypad.dev) notebooks (`.pypad.py`) and Jupyter notebooks (`.ipynb`). Standard library
+only; Python 3.9+.
+
+PyPad is a small in-browser Python notebook for teaching: it runs entirely in the learner's browser, fits in a Moodle quiz question, can be
+shared as a link, and its files are plain, readable Python. This package is the file-format side of it, so a notebook is never trapped.
+
+```bash
+pip install pypad-notebook
+```
+
+## Command line
+
+```bash
+pypad convert lesson.pypad.py            # -> lesson.ipynb
+pypad convert lesson.ipynb                # -> lesson.pypad.py
+pypad convert lesson.ipynb --outputs text
+pypad check lesson.pypad.py              # ok / changed / absent: is it still what PyPad wrote?  (exit 1 if changed)
+pypad embed lesson.pypad.py > question.html     # the HTML block for a Moodle question or web page
+pypad answers responses.csv --out answers/       # split a Moodle quiz "Responses" download into one file per student
+pypad verify template.pypad.py answers/*.pypad.py   # re-check them against the template (exit 1 if any are not clean)
+pypad embed lesson.pypad.py --answer-format base64 --loader https://pypad.dev/v1/pypad-mdl-quiz.js
+```
+
+`convert` never overwrites without `--force`. `check`, `convert` and `embed` also accept an HTML page that holds a notebook (an embed, or a
+PyPad "web page" export).
+
+## Marking
+
+An assessment that matters should be checked where the student cannot touch it. The widget stops mistakes in the student's browser, but the browser is
+the student's. `pypad verify` applies, on your side, the same rules the widget applies when it opens an answer (the template's `policy`, its locked cells,
+its answer cells and sections), and tells you for each answer what the student changed, added or removed, and what the rules would have put back:
+
+```
+answers/Student_Sam.pypad.py: clean (check value ok) - changed a1
+answers/Other_Oz.pypad.py: NOT CLEAN (check value ok) - changed a1
+    cell "i1" cannot be edited, and its text was put back
+```
+
+`pypad answers` turns a Moodle quiz **Responses** download (CSV) into those files, decoding stored answers.
+
+## In Python
+
+```python
+import pypad
+
+result = pypad.parse(open("lesson.pypad.py", encoding="utf-8").read())
+result.integrity            # 'ok', 'changed' or 'absent'
+result.warnings             # problems found while reading; a damaged file still opens
+nb = result.notebook        # nb.config, nb.cells[i].id / .type / .source / .settings / .outputs
+
+text = pypad.dumps(nb)                          # .pypad.py text, with its check value
+ipynb = pypad.to_ipynb_text(nb, save_outputs="text")
+nb2 = pypad.from_ipynb_text(open("lesson.ipynb", encoding="utf-8").read())
+html = pypad.build_embed(text, answer_format="plain")
+
+report = pypad.verify_answer(template_nb, answer_nb, integrity)   # report.clean, .changed_cells, .violations, ...
+```
+
+## It matches the JavaScript implementation
+
+This is a port of the reference implementation (`packages/notebook` in the PyPad repository). The same text produces the same notebook, the
+same file, the same Jupyter notebook and the same check value, including for emoji and odd characters. That is tested against a file of vectors
+that the JavaScript implementation generates (`tests/vectors.json`), so the two cannot drift apart unnoticed.
+
+## The format, in one screen
+
+```python
+# %% [pypad-start] v1 sha=3f9a1c0d7b2e4a65
+
+# %% [config] {"policy":"fixed","kernel":"skulpt"}
+
+# %% [markdown] {"id":"k3j9a0xq","editable":false}
+"""
+Print the sum of 1 and 2.
+"""
+
+# %% [code] {"id":"p8w2m1zc"}
+print(1 + 2)
+
+# %% [pypad-end]
+```
+
+Code is code and everything else sits in triple-quoted strings, so the file is (nearly) valid Python and readable anywhere. The `sha` is a check
+value of the notebook's content: it notices an editor or a hand edit changing something, and ignores indentation and line endings. It is not a
+security measure. Reading is forgiving (Jupytext-style comment blocks, indented text, Windows line endings); writing has one form.
+
+MIT licensed.

pypad_notebook-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pypad-notebook"
+version = "0.1.0"
+description = "Read, write and convert PyPad notebooks (.pypad.py) and Jupyter notebooks (.ipynb)."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Philip Lewis" }]
+keywords = ["notebook", "jupyter", "ipynb", "pypad", "moodle", "education"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Education",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Education",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[project.scripts]
+pypad = "pypad.cli:main"
+
+[project.urls]
+Homepage = "https://pypad.dev"
+Repository = "https://github.com/pypad-dev/pypad"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+pypad = ["py.typed", "_schema.json"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

pypad_notebook-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pypad_notebook-0.1.0/src/pypad/__init__.py

@@ -0,0 +1,59 @@
+"""pypad: read, write and convert PyPad notebooks (``.pypad.py`` and ``.pypad.py`` files) and Jupyter notebooks (``.ipynb``).
+
+    >>> import pypad
+    >>> result = pypad.parse(open("lesson.pypad.py").read())
+    >>> result.integrity            # 'ok', 'changed' or 'absent': is it still what PyPad wrote?
+    'ok'
+    >>> nb = pypad.from_ipynb_text(open("lesson.ipynb").read())
+    >>> open("lesson.pypad.py", "w").write(pypad.dumps(nb))
+
+A faithful port of the PyPad reference implementation (https://github.com/pypad-dev/pypad, ``packages/notebook``): the same text and
+the same check value come out of Python as out of JavaScript. Standard library only.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Callable, Optional
+
+from .embed import build_embed, from_script_block, to_script_block
+from .format import FORMAT_VERSION, ParseResult, dedent, dumps, parse
+from .ipynb import from_ipynb, to_ipynb
+from .jsutil import js_json
+from .merge import MergeResult, merge_answer
+from .rules import EffectiveCell, resolve_cell, resolve_config
+from .verify import AnswerReport, verify_answer
+from .model import (
+    Cell,
+    Notebook,
+    SavedOutputs,
+    hash_document,
+    hash_source,
+    is_output_stale,
+    new_cell_id,
+    positional_ids,
+)
+from .outputs import select_outputs
+
+__version__ = "0.1.0"
+
+#: File extensions that hold a PyPad notebook. Reading does not depend on the name: any text with the markers opens.
+NOTEBOOK_EXTENSIONS = (".pypad.py",)
+
+
+def to_ipynb_text(notebook: Notebook, save_outputs: str = "none", max_saved_output_chars: float = 5000) -> str:
+    """A Jupyter notebook as text, written the way Jupyter writes it (one space of indent, sorted keys, final newline)."""
+    return json.dumps(to_ipynb(notebook, save_outputs, max_saved_output_chars), indent=1, sort_keys=True, ensure_ascii=False) + "\n"
+
+
+def from_ipynb_text(text: str, make_id: Optional[Callable[[], str]] = None) -> Notebook:
+    """A notebook from the text of an ``.ipynb`` file. Problems are dropped quietly; use :func:`from_ipynb` to see the warnings."""
+    return from_ipynb(json.loads(text), make_id)[0]
+
+
+__all__ = [
+    "AnswerReport", "EffectiveCell", "MergeResult", "merge_answer", "resolve_cell", "resolve_config", "verify_answer",
+    "Cell", "FORMAT_VERSION", "NOTEBOOK_EXTENSIONS", "Notebook", "ParseResult", "SavedOutputs",
+    "build_embed", "dedent", "dumps", "from_ipynb", "from_ipynb_text", "from_script_block", "hash_document", "hash_source",
+    "is_output_stale", "js_json", "new_cell_id", "parse", "positional_ids", "select_outputs", "to_ipynb", "to_ipynb_text", "to_script_block",
+]

pypad_notebook-0.1.0/src/pypad/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())