cellwatch 0.1.0__tar.gz

cellwatch-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.ipynb_checkpoints/
+dist/
+build/
+*.egg-info/
+.venv/

cellwatch-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,69 @@
+# Working on cellwatch as a team
+
+## Who uploads what
+
+The package is built from five modules. Each module depends only on the ones
+above it in this table, so push them **in this order**.
+
+| Order | Person | Files to push |
+|---|---|---|
+| 0 | Repository owner | `pyproject.toml`, `README.md`, `CONTRIBUTING.md`, `LICENSE`, `.gitignore`, `src/cellwatch/__init__.py` |
+| 1 | Member 1 | `src/cellwatch/snapshot.py`, `tests/test_snapshot.py` |
+| 2 | Member 2 | `src/cellwatch/compare.py`, `tests/test_compare.py` |
+| 3 | Member 3 | `src/cellwatch/report.py`, `tests/test_report.py` |
+| 4 | Member 4 | `src/cellwatch/history.py`, `tests/test_history.py` |
+| 5 | Member 5 | `src/cellwatch/magic.py`, `tests/test_magic.py` |
+
+The repository owner is also one of the five members. The `%%cellwatch`
+command works once all five modules are in.
+
+## One-time setup (every member)
+
+```bash
+git clone https://github.com/Geoeoeo217/cellwatch
+cd cellwatch
+pip install -e ".[dev]"
+```
+
+`git clone` downloads the repository. `pip install -e .` is an "editable"
+install: Python uses the files in this folder directly, so your edits take
+effect without reinstalling.
+
+## Pushing your module
+
+```bash
+git pull                     # get your teammates' latest work first
+# copy your two files into src/cellwatch/ and tests/
+pytest                       # every test must pass
+git add src/cellwatch/YOURFILE.py tests/test_YOURFILE.py
+git commit -m "Add YOURFILE module: one line on what it does"
+git push
+```
+
+If `git push` is rejected, a teammate pushed before you: run `git pull` and
+then `git push` again.
+
+## After the first five pushes
+
+One commit each is a start, not a "regular commit history". Each member
+should own their module from here on and keep improving it:
+
+- **snapshot.py** – option to ignore chosen variable names; faster handling
+  of very large values.
+- **compare.py** – for lists and dictionaries, say which items were added or
+  removed instead of only before/after.
+- **report.py** – coloured HTML table for notebooks (green created, yellow
+  changed, red deleted).
+- **history.py** – limit the history size; export the history as a list of
+  dictionaries.
+- **magic.py** – `%cellwatch ignore NAME`; a demo notebook in `examples/`
+  that doubles as the 1-minute presentation script.
+
+Small, frequent commits with clear messages are better than one big one.
+
+## Publishing to PyPI
+
+1. Fill in the author names in `pyproject.toml`.
+2. Raise `version` in `pyproject.toml` and in `src/cellwatch/__init__.py`.
+3. `python -m build` creates the files to upload in `dist/`.
+4. `twine upload dist/*` uploads them; it asks for a PyPI API token.

cellwatch-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The cellwatch team
+
+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.

cellwatch-0.1.0/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.5
+Name: cellwatch
+Version: 0.1.0
+Summary: See exactly which variables a Jupyter cell created, changed or deleted.
+Project-URL: Homepage, https://github.com/Geoeoeo217/cellwatch
+Project-URL: Documentation, https://github.com/Geoeoeo217/cellwatch#readme
+Project-URL: Issues, https://github.com/Geoeoeo217/cellwatch/issues
+Author: NATHANAEL George Steindhart, SETIAWAN Matthew Henson, LATHIF Muhammad Akmal, HANDAYA Clement Steward, KWAN Kendrick Matthew
+License: MIT
+License-File: LICENSE
+Keywords: diff,education,ipython,jupyter,notebook,variables
+Classifier: Framework :: IPython
+Classifier: Framework :: Jupyter
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Requires-Dist: ipython>=7.0
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# cellwatch
+
+See exactly which variables a Jupyter cell **created**, **changed** or **deleted**.
+
+```text
+%%cellwatch
+scores.sort()
+total = sum(scores)
+del draft
+```
+
+```text
+cellwatch: 1 created, 1 changed, 1 deleted
+  + total = 6  (int)
+  ~ scores: [3, 1, 2] -> [1, 2, 3]  (modified in place)
+  - draft  (was 'old text')
+```
+
+## Motivation
+
+In a notebook, variables live on after a cell finishes, and any later cell can
+quietly change them. Beginners often get stuck because a cell changed something
+they did not expect: a list was sorted in place, a name was reused, or a
+variable was overwritten by a cell that was run twice. Jupyter can list the
+variables that exist right now (`%whos`), but it cannot tell you what a cell
+just did to them.
+
+## What is new
+
+- **A per-cell diff of variables.** `cellwatch` records the variables before a
+  cell runs, records them again afterwards, and reports only the differences.
+- **It spots in-place changes.** `scores.sort()` does not assign anything, so
+  it is easy to miss. `cellwatch` labels it `modified in place`.
+- **A timeline per variable.** `%cellwatch history x` lists every recorded
+  change to `x` and the cell that made it.
+- **It complements existing tools.** `%whos` lists variables but shows no
+  changes. [Kishu](https://github.com/illinoisdata/kishu) can undo a cell but
+  does not explain what the cell changed. `cellwatch` is the explaining part,
+  with one small dependency (IPython, which Jupyter already includes).
+
+## Install
+
+```bash
+pip install cellwatch
+```
+
+## Usage
+
+Load the extension once per notebook:
+
+```python
+%load_ext cellwatch
+```
+
+**Report on one cell** by putting `%%cellwatch` on its first line:
+
+```python
+%%cellwatch
+x = 10
+```
+
+**Report after every cell** until you switch it off:
+
+```python
+%cellwatch on
+...
+%cellwatch off
+```
+
+**See the timeline of a variable** across all watched cells (the number in
+brackets is the cell's execution number):
+
+```python
+%cellwatch history scores
+```
+
+```text
+cellwatch history for 'scores':
+  [1] + scores = [3, 1, 2]  (list)
+  [2] ~ scores: [3, 1, 2] -> [1, 2, 3]  (modified in place)
+```
+
+`%cellwatch history` without a name lists every change, and `%cellwatch clear`
+empties the history.
+
+How to read a report:
+
+| Symbol | Meaning |
+|---|---|
+| `+` | the variable was created |
+| `~` | the variable's value changed (`before -> after`) |
+| `-` | the variable was deleted |
+
+Imported modules and names starting with `_` are not reported.
+
+**Use it from plain Python** (no notebook needed):
+
+```python
+from cellwatch import snapshot, diff, format_changes
+
+before = snapshot(globals())
+data = [1, 2, 3]
+print(format_changes(diff(before, snapshot(globals()))))
+```
+
+## Example use cases
+
+- **Debugging a surprise.** A result is wrong and you suspect an earlier cell.
+  Turn on `%cellwatch on`, rerun the cells, and read what each one touched.
+- **Learning mutation vs. reassignment.** Compare `b = a` then `b.append(4)`
+  with `b = a + [4]`: the report shows that the first also changes `a`.
+- **Teaching and demos.** An instructor can show the effect of each cell
+  without adding `print` statements everywhere.
+- **Checking a notebook before submission.** Confirm that a cell does not
+  overwrite a variable another cell depends on.
+
+## Limitations
+
+- Changes are detected by comparing the printed form (`repr`) of each value,
+  so an object whose printed form stays the same is reported as unchanged.
+- Very large values can make each report slower, because they are printed
+  twice per cell.
+
+## Development
+
+```bash
+git clone https://github.com/Geoeoeo217/cellwatch
+cd cellwatch
+pip install -e ".[dev]"
+pytest
+```
+
+How the code is organised:
+
+| File | Job |
+|---|---|
+| `snapshot.py` | Record every user variable at one moment |
+| `compare.py` | Compare two snapshots and list the differences |
+| `report.py` | Turn the differences into a text report |
+| `history.py` | Remember the changes made by every watched cell |
+| `magic.py` | The `%%cellwatch` and `%cellwatch` notebook commands |
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for how the team works and what is left
+to build.
+
+## License
+
+MIT

cellwatch-0.1.0/README.md

@@ -0,0 +1,148 @@
+# cellwatch
+
+See exactly which variables a Jupyter cell **created**, **changed** or **deleted**.
+
+```text
+%%cellwatch
+scores.sort()
+total = sum(scores)
+del draft
+```
+
+```text
+cellwatch: 1 created, 1 changed, 1 deleted
+  + total = 6  (int)
+  ~ scores: [3, 1, 2] -> [1, 2, 3]  (modified in place)
+  - draft  (was 'old text')
+```
+
+## Motivation
+
+In a notebook, variables live on after a cell finishes, and any later cell can
+quietly change them. Beginners often get stuck because a cell changed something
+they did not expect: a list was sorted in place, a name was reused, or a
+variable was overwritten by a cell that was run twice. Jupyter can list the
+variables that exist right now (`%whos`), but it cannot tell you what a cell
+just did to them.
+
+## What is new
+
+- **A per-cell diff of variables.** `cellwatch` records the variables before a
+  cell runs, records them again afterwards, and reports only the differences.
+- **It spots in-place changes.** `scores.sort()` does not assign anything, so
+  it is easy to miss. `cellwatch` labels it `modified in place`.
+- **A timeline per variable.** `%cellwatch history x` lists every recorded
+  change to `x` and the cell that made it.
+- **It complements existing tools.** `%whos` lists variables but shows no
+  changes. [Kishu](https://github.com/illinoisdata/kishu) can undo a cell but
+  does not explain what the cell changed. `cellwatch` is the explaining part,
+  with one small dependency (IPython, which Jupyter already includes).
+
+## Install
+
+```bash
+pip install cellwatch
+```
+
+## Usage
+
+Load the extension once per notebook:
+
+```python
+%load_ext cellwatch
+```
+
+**Report on one cell** by putting `%%cellwatch` on its first line:
+
+```python
+%%cellwatch
+x = 10
+```
+
+**Report after every cell** until you switch it off:
+
+```python
+%cellwatch on
+...
+%cellwatch off
+```
+
+**See the timeline of a variable** across all watched cells (the number in
+brackets is the cell's execution number):
+
+```python
+%cellwatch history scores
+```
+
+```text
+cellwatch history for 'scores':
+  [1] + scores = [3, 1, 2]  (list)
+  [2] ~ scores: [3, 1, 2] -> [1, 2, 3]  (modified in place)
+```
+
+`%cellwatch history` without a name lists every change, and `%cellwatch clear`
+empties the history.
+
+How to read a report:
+
+| Symbol | Meaning |
+|---|---|
+| `+` | the variable was created |
+| `~` | the variable's value changed (`before -> after`) |
+| `-` | the variable was deleted |
+
+Imported modules and names starting with `_` are not reported.
+
+**Use it from plain Python** (no notebook needed):
+
+```python
+from cellwatch import snapshot, diff, format_changes
+
+before = snapshot(globals())
+data = [1, 2, 3]
+print(format_changes(diff(before, snapshot(globals()))))
+```
+
+## Example use cases
+
+- **Debugging a surprise.** A result is wrong and you suspect an earlier cell.
+  Turn on `%cellwatch on`, rerun the cells, and read what each one touched.
+- **Learning mutation vs. reassignment.** Compare `b = a` then `b.append(4)`
+  with `b = a + [4]`: the report shows that the first also changes `a`.
+- **Teaching and demos.** An instructor can show the effect of each cell
+  without adding `print` statements everywhere.
+- **Checking a notebook before submission.** Confirm that a cell does not
+  overwrite a variable another cell depends on.
+
+## Limitations
+
+- Changes are detected by comparing the printed form (`repr`) of each value,
+  so an object whose printed form stays the same is reported as unchanged.
+- Very large values can make each report slower, because they are printed
+  twice per cell.
+
+## Development
+
+```bash
+git clone https://github.com/Geoeoeo217/cellwatch
+cd cellwatch
+pip install -e ".[dev]"
+pytest
+```
+
+How the code is organised:
+
+| File | Job |
+|---|---|
+| `snapshot.py` | Record every user variable at one moment |
+| `compare.py` | Compare two snapshots and list the differences |
+| `report.py` | Turn the differences into a text report |
+| `history.py` | Remember the changes made by every watched cell |
+| `magic.py` | The `%%cellwatch` and `%cellwatch` notebook commands |
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for how the team works and what is left
+to build.
+
+## License
+
+MIT

cellwatch-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cellwatch"
+version = "0.1.0"
+description = "See exactly which variables a Jupyter cell created, changed or deleted."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+    { name = "NATHANAEL George Steindhart" },
+    { name = "SETIAWAN Matthew Henson" },
+    { name = "LATHIF Muhammad Akmal" },
+    { name = "HANDAYA Clement Steward" },
+    { name = "KWAN Kendrick Matthew" },
+]
+keywords = ["jupyter", "ipython", "notebook", "variables", "diff", "education"]
+classifiers = [
+    "Framework :: IPython",
+    "Framework :: Jupyter",
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Intended Audience :: Education",
+]
+dependencies = ["ipython>=7.0"]
+
+[project.optional-dependencies]
+dev = ["pytest", "build", "twine"]
+
+[project.urls]
+Homepage = "https://github.com/Geoeoeo217/cellwatch"
+Documentation = "https://github.com/Geoeoeo217/cellwatch#readme"
+Issues = "https://github.com/Geoeoeo217/cellwatch/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cellwatch"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

cellwatch-0.1.0/src/cellwatch/__init__.py

@@ -0,0 +1,44 @@
+"""cellwatch: see which variables a Jupyter cell created, changed or deleted."""
+
+__version__ = "0.1.0"
+
+# Public names and the module each one lives in.
+_PUBLIC = {
+    "Record": "snapshot",
+    "snapshot": "snapshot",
+    "Change": "compare",
+    "diff": "compare",
+    "format_changes": "report",
+    "History": "history",
+    "format_history": "history",
+}
+
+__all__ = sorted(_PUBLIC) + ["load_ipython_extension", "unload_ipython_extension"]
+
+
+def __getattr__(name):
+    """Import a public name the first time someone asks for it.
+
+    Python calls this special function when ``cellwatch.<name>`` is not found
+    the normal way. Loading modules only when needed keeps each module usable
+    on its own.
+    """
+    if name in _PUBLIC:
+        from importlib import import_module
+
+        return getattr(import_module(f".{_PUBLIC[name]}", __name__), name)
+    raise AttributeError(f"module 'cellwatch' has no attribute {name!r}")
+
+
+def load_ipython_extension(ipython):
+    """Called by ``%load_ext cellwatch``."""
+    from .magic import load
+
+    load(ipython)
+
+
+def unload_ipython_extension(ipython):
+    """Called by ``%unload_ext cellwatch``."""
+    from .magic import unload
+
+    unload(ipython)

cellwatch-0.1.0/src/cellwatch/compare.py

@@ -0,0 +1,52 @@
+"""Step 2: compare two snapshots and list the differences."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .snapshot import Record
+
+KINDS = ("created", "changed", "deleted")
+
+
+@dataclass(frozen=True)
+class Change:
+    """One difference between two snapshots."""
+
+    name: str
+    kind: str  # one of KINDS
+    before: Record | None  # None when the variable was created
+    after: Record | None  # None when the variable was deleted
+
+    @property
+    def in_place(self) -> bool:
+        """True if the same object was modified, e.g. by ``list.sort()``."""
+        return (
+            self.kind == "changed"
+            and self.before.identity == self.after.identity
+            and self.before.type_name == self.after.type_name
+        )
+
+
+def diff(before: dict[str, Record], after: dict[str, Record]) -> list[Change]:
+    """List what was created, changed or deleted between two snapshots."""
+    changes = []
+    # "after.keys() - before.keys()" is the set of names only found in after.
+    for name in sorted(after.keys() - before.keys()):
+        changes.append(Change(name, "created", None, after[name]))
+    # "&" keeps the names found in both snapshots.
+    for name in sorted(after.keys() & before.keys()):
+        old, new = before[name], after[name]
+        if old.text != new.text or old.type_name != new.type_name:
+            changes.append(Change(name, "changed", old, new))
+    for name in sorted(before.keys() - after.keys()):
+        changes.append(Change(name, "deleted", before[name], None))
+    return changes
+
+
+def count_by_kind(changes: list[Change]) -> dict[str, int]:
+    """Count the changes of each kind, e.g. {"created": 1, "changed": 2}."""
+    counts = {}
+    for change in changes:
+        counts[change.kind] = counts.get(change.kind, 0) + 1
+    return counts

cellwatch-0.1.0/src/cellwatch/history.py

@@ -0,0 +1,42 @@
+"""Step 4: remember the changes made by every watched cell."""
+
+from __future__ import annotations
+
+from .compare import Change
+from .report import describe
+
+
+class History:
+    """A running log of changes, grouped by the cell that made them."""
+
+    def __init__(self):
+        self._entries = []  # list of (cell_number, Change) pairs
+
+    def record(self, cell_number: int, changes: list[Change]) -> None:
+        """Add the changes made by one cell."""
+        for change in changes:
+            self._entries.append((cell_number, change))
+
+    def entries(self, name: str | None = None) -> list[tuple[int, Change]]:
+        """All entries, or only those for the variable called ``name``."""
+        if name is None:
+            return list(self._entries)
+        return [entry for entry in self._entries if entry[1].name == name]
+
+    def clear(self) -> None:
+        """Forget everything recorded so far."""
+        self._entries.clear()
+
+    def __len__(self) -> int:
+        return len(self._entries)
+
+
+def format_history(history: History, name: str | None = None) -> str:
+    """A text timeline, one line per change, labelled with its cell number."""
+    entries = history.entries(name)
+    subject = f"'{name}'" if name else "all variables"
+    if not entries:
+        return f"cellwatch: no recorded changes for {subject}"
+    lines = [f"cellwatch history for {subject}:"]
+    lines += [f"  [{cell_number}] {describe(change)}" for cell_number, change in entries]
+    return "\n".join(lines)

cellwatch-0.1.0/src/cellwatch/magic.py

@@ -0,0 +1,114 @@
+"""Step 5: the Jupyter commands %%cellwatch and %cellwatch."""
+
+from __future__ import annotations
+
+from IPython.core.magic import Magics, line_cell_magic, magics_class
+
+from .compare import diff
+from .history import History, format_history
+from .report import format_changes
+from .snapshot import snapshot
+
+USAGE = """Usage:
+  %%cellwatch              report on this cell (first line of the cell)
+  %cellwatch on | off      report after every cell / stop
+  %cellwatch history       list every recorded change
+  %cellwatch history NAME  list the changes made to one variable
+  %cellwatch clear         forget the recorded history"""
+
+
+@magics_class
+class CellWatchMagics(Magics):
+    """Adds the ``cellwatch`` magic command to a notebook."""
+
+    def __init__(self, shell):
+        super().__init__(shell)
+        self.history = History()
+        self._auto = False
+        self._before = None
+
+    @line_cell_magic
+    def cellwatch(self, line, cell=None):
+        """Report which variables a cell created, changed or deleted."""
+        if cell is not None:
+            self._run_and_report(cell)
+            return
+        words = line.split()
+        command = words[0].lower() if words else ""
+        if command == "on":
+            self._set_auto(True)
+            print("cellwatch: reporting after every cell (%cellwatch off to stop)")
+        elif command == "off":
+            self._set_auto(False)
+            print("cellwatch: automatic reporting stopped")
+        elif command == "history":
+            print(format_history(self.history, words[1] if len(words) > 1 else None))
+        elif command == "clear":
+            self.history.clear()
+            print("cellwatch: history cleared")
+        else:
+            print(USAGE)
+
+    def _run_and_report(self, cell):
+        was_auto = self._auto
+        self._auto = False  # avoid a second report from automatic mode
+        cell_number = self._cell_number()
+        before = snapshot(self.shell.user_ns)
+        try:
+            self.shell.run_cell(cell)
+        finally:
+            self._auto = was_auto
+        changes = diff(before, snapshot(self.shell.user_ns))
+        self.history.record(cell_number, changes)
+        print(format_changes(changes))
+
+    def _cell_number(self):
+        """The number shown as ``In [n]`` beside the cell that is running.
+
+        IPython keeps every cell's code in a list called ``In``; the running
+        cell is its last item, so its number is the last index of that list.
+        """
+        inputs = self.shell.user_ns.get("In", [])
+        return max(len(inputs) - 1, 0)
+
+    def _set_auto(self, enabled):
+        if enabled == self._auto:
+            return
+        events = self.shell.events
+        if enabled:
+            events.register("pre_run_cell", self._pre_run_cell)
+            events.register("post_run_cell", self._post_run_cell)
+        else:
+            events.unregister("pre_run_cell", self._pre_run_cell)
+            events.unregister("post_run_cell", self._post_run_cell)
+        self._auto = enabled
+        self._before = None
+
+    def _pre_run_cell(self, info):
+        self._before = snapshot(self.shell.user_ns)
+
+    def _post_run_cell(self, result):
+        if self._before is None or not self._auto:
+            return
+        changes = diff(self._before, snapshot(self.shell.user_ns))
+        self._before = None
+        if changes:
+            self.history.record(self._cell_number(), changes)
+            print(format_changes(changes))
+
+
+_instances = {}
+
+
+def load(ipython):
+    """Register the magic command with a running IPython/Jupyter session."""
+    magics = CellWatchMagics(ipython)
+    _instances[id(ipython)] = magics
+    ipython.register_magics(magics)
+
+
+def unload(ipython):
+    """Stop automatic reporting when the extension is unloaded."""
+    magics = _instances.pop(id(ipython), None)
+    if magics is not None:
+        magics._set_auto(False)

cellwatch-0.1.0/src/cellwatch/report.py

@@ -0,0 +1,42 @@
+"""Step 3: turn a list of changes into a short, readable text report."""
+
+from __future__ import annotations
+
+from .compare import KINDS, Change, count_by_kind
+
+MAX_WIDTH = 60  # longest value text shown in a report
+
+
+def shorten(text: str, width: int = MAX_WIDTH) -> str:
+    """Put ``text`` on one line and cut it to ``width`` characters."""
+    text = " ".join(text.split())
+    return text if len(text) <= width else text[: width - 3] + "..."
+
+
+def describe(change: Change) -> str:
+    """One report line: ``+`` created, ``~`` changed, ``-`` deleted."""
+    if change.kind == "created":
+        return f"+ {change.name} = {shorten(change.after.text)}  ({change.after.type_name})"
+    if change.kind == "deleted":
+        return f"- {change.name}  (was {shorten(change.before.text)})"
+    line = f"~ {change.name}: {shorten(change.before.text)} -> {shorten(change.after.text)}"
+    if change.before.type_name != change.after.type_name:
+        line += f"  (type {change.before.type_name} -> {change.after.type_name})"
+    elif change.in_place:
+        line += "  (modified in place)"
+    return line
+
+
+def summarize(changes: list[Change]) -> str:
+    """A one-line count such as ``1 created, 2 changed``."""
+    counts = count_by_kind(changes)
+    return ", ".join(f"{counts[kind]} {kind}" for kind in KINDS if kind in counts)
+
+
+def format_changes(changes: list[Change]) -> str:
+    """The full report for one cell."""
+    if not changes:
+        return "cellwatch: no variables changed"
+    lines = ["cellwatch: " + summarize(changes)]
+    lines += ["  " + describe(change) for change in changes]
+    return "\n".join(lines)

cellwatch-0.1.0/src/cellwatch/snapshot.py

@@ -0,0 +1,50 @@
+"""Step 1: take a snapshot (a record of every user variable at one moment)."""
+
+from __future__ import annotations
+
+import types
+from dataclasses import dataclass
+
+# Names that IPython itself puts in the notebook; not the user's variables.
+IPYTHON_NAMES = {"In", "Out", "exit", "quit", "get_ipython", "open"}
+
+
+@dataclass(frozen=True)
+class Record:
+    """What we remember about one variable at one moment."""
+
+    text: str  # repr() of the value, i.e. how Python prints it
+    type_name: str  # e.g. "list"
+    identity: int  # id() of the object; same id means same object
+
+
+def is_user_variable(name: str, value: object) -> bool:
+    """Return False for private names, IPython's own names and modules."""
+    if name.startswith("_"):
+        return False
+    if name in IPYTHON_NAMES:
+        return False
+    if isinstance(value, types.ModuleType):
+        return False
+    return True
+
+
+def safe_repr(value: object) -> str:
+    """Like repr(), but never raises an error."""
+    try:
+        return repr(value)
+    except Exception as error:  # a broken __repr__ must not break the report
+        return f"<unprintable {type(value).__name__}: {error}>"
+
+
+def snapshot(namespace: dict) -> dict[str, Record]:
+    """Record the current state of every user variable in ``namespace``.
+
+    ``namespace`` is a dictionary of variable names to values, for example
+    ``globals()`` or a notebook's ``user_ns``.
+    """
+    return {
+        name: Record(safe_repr(value), type(value).__name__, id(value))
+        for name, value in list(namespace.items())
+        if is_user_variable(name, value)
+    }

cellwatch-0.1.0/tests/test_compare.py

@@ -0,0 +1,35 @@
+from cellwatch.compare import count_by_kind, diff
+from cellwatch.snapshot import snapshot
+
+
+def changes_between(before_ns, after_ns):
+    return diff(snapshot(before_ns), snapshot(after_ns))
+
+
+def test_created_and_deleted():
+    [created] = changes_between({}, {"x": 1})
+    [deleted] = changes_between({"x": 1}, {})
+    assert (created.kind, deleted.kind) == ("created", "deleted")
+
+
+def test_reassigned_variable():
+    [change] = changes_between({"x": 1}, {"x": 2})
+    assert (change.kind, change.before.text, change.after.text) == ("changed", "1", "2")
+    assert not change.in_place
+
+
+def test_in_place_change_is_detected():
+    scores = [3, 1, 2]
+    before = snapshot({"scores": scores})
+    scores.sort()
+    [change] = diff(before, snapshot({"scores": scores}))
+    assert change.kind == "changed" and change.in_place
+
+
+def test_unchanged_variable_is_not_reported():
+    assert changes_between({"x": 1}, {"x": 1}) == []
+
+
+def test_count_by_kind():
+    changes = changes_between({"a": 1, "b": 1}, {"a": 2, "c": 3})
+    assert count_by_kind(changes) == {"created": 1, "changed": 1, "deleted": 1}

cellwatch-0.1.0/tests/test_history.py

@@ -0,0 +1,30 @@
+from cellwatch.compare import diff
+from cellwatch.history import History, format_history
+from cellwatch.snapshot import snapshot
+
+
+def make_history():
+    history = History()
+    history.record(1, diff(snapshot({}), snapshot({"x": 1, "y": 5})))
+    history.record(2, diff(snapshot({"x": 1}), snapshot({"x": 2})))
+    return history
+
+
+def test_entries_can_be_filtered_by_name():
+    history = make_history()
+    assert len(history) == 3
+    assert [cell for cell, _ in history.entries("x")] == [1, 2]
+
+
+def test_format_history_for_one_variable():
+    assert format_history(make_history(), "x").splitlines() == [
+        "cellwatch history for 'x':",
+        "  [1] + x = 1  (int)",
+        "  [2] ~ x: 1 -> 2",
+    ]
+
+
+def test_empty_and_cleared_history():
+    history = make_history()
+    history.clear()
+    assert format_history(history) == "cellwatch: no recorded changes for all variables"

cellwatch-0.1.0/tests/test_magic.py

@@ -0,0 +1,52 @@
+import pytest
+
+IPython = pytest.importorskip("IPython")
+from IPython.testing.globalipapp import start_ipython
+
+
+@pytest.fixture(scope="module")
+def ip():
+    shell = start_ipython() or IPython.get_ipython()
+    shell.run_line_magic("load_ext", "cellwatch")
+    return shell
+
+
+def test_cell_magic_reports_changes(ip, capsys):
+    ip.run_cell("scores = [3, 1, 2]")
+    capsys.readouterr()
+    ip.run_cell_magic("cellwatch", "", "scores.sort()\ntotal = sum(scores)")
+    out = capsys.readouterr().out
+    assert "1 created, 1 changed" in out
+    assert "+ total = 6" in out
+    assert "~ scores: [3, 1, 2] -> [1, 2, 3]  (modified in place)" in out
+
+
+def test_auto_mode_on_and_off(ip, capsys):
+    ip.run_line_magic("cellwatch", "on")
+    ip.run_cell("auto_value = 42")
+    assert "+ auto_value = 42" in capsys.readouterr().out
+    ip.run_line_magic("cellwatch", "off")
+    capsys.readouterr()
+    ip.run_cell("another_value = 1")
+    assert "another_value" not in capsys.readouterr().out
+
+
+def test_history_command(ip, capsys):
+    ip.run_line_magic("cellwatch", "history total")
+    out = capsys.readouterr().out
+    assert "cellwatch history for 'total':" in out and "+ total = 6" in out
+    ip.run_line_magic("cellwatch", "clear")
+    ip.run_line_magic("cellwatch", "history")
+    assert "no recorded changes" in capsys.readouterr().out
+
+
+def test_public_names_are_importable():
+    from cellwatch import History, diff, format_changes, snapshot  # noqa: F401
+
+
+def test_history_uses_the_cell_number(ip, capsys):
+    ip.run_line_magic("cellwatch", "clear")
+    result = ip.run_cell("%%cellwatch\nnumbered = 1", store_history=True)
+    capsys.readouterr()
+    ip.run_line_magic("cellwatch", "history numbered")
+    assert f"[{result.execution_count}] + numbered = 1" in capsys.readouterr().out

cellwatch-0.1.0/tests/test_report.py

@@ -0,0 +1,30 @@
+from cellwatch.compare import diff
+from cellwatch.report import format_changes, shorten
+from cellwatch.snapshot import snapshot
+
+
+def report(before_ns, after_ns):
+    return format_changes(diff(snapshot(before_ns), snapshot(after_ns)))
+
+
+def test_no_changes():
+    assert report({"x": 1}, {"x": 1}) == "cellwatch: no variables changed"
+
+
+def test_full_report():
+    text = report({"a": 1, "b": "old"}, {"a": 2, "c": [1]})
+    assert text.splitlines() == [
+        "cellwatch: 1 created, 1 changed, 1 deleted",
+        "  + c = [1]  (list)",
+        "  ~ a: 1 -> 2",
+        "  - b  (was 'old')",
+    ]
+
+
+def test_type_change_is_mentioned():
+    assert "(type int -> str)" in report({"x": 1}, {"x": "1"})
+
+
+def test_long_values_are_shortened():
+    assert len(shorten("x" * 500)) == 60
+    assert all(len(line) < 100 for line in report({}, {"big": list(range(1000))}).splitlines())

cellwatch-0.1.0/tests/test_snapshot.py

@@ -0,0 +1,21 @@
+import math
+
+from cellwatch.snapshot import safe_repr, snapshot
+
+
+def test_records_text_type_and_identity():
+    scores = [1, 2]
+    record = snapshot({"scores": scores})["scores"]
+    assert (record.text, record.type_name, record.identity) == ("[1, 2]", "list", id(scores))
+
+
+def test_private_names_ipython_names_and_modules_are_skipped():
+    assert snapshot({"_hidden": 1, "math": math, "In": [], "x": 1}).keys() == {"x"}
+
+
+def test_broken_repr_does_not_crash():
+    class Broken:
+        def __repr__(self):
+            raise ValueError("oops")
+
+    assert safe_repr(Broken()).startswith("<unprintable Broken")