cellwatch 0.1.0__py3-none-any.whl

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/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/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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+cellwatch/__init__.py,sha256=dC3SMFsp8ft4JcQP7k9wcU0Tp_fGLq9sFcruIpbXzps,1203
+cellwatch/compare.py,sha256=yJwM5BCe3ej_ndGwPPqdhxRQcbxDUQefvM6fP5vrin0,1827
+cellwatch/history.py,sha256=5kpx2JVElDaRpF-FfVryrGNit7HLDnmgbiarIu9vWxw,1502
+cellwatch/magic.py,sha256=Cf-0u4HdeLaij4F8FkU0BV38VzzHf2CBVvaJ3ETIF_w,3901
+cellwatch/report.py,sha256=dqNHKXt3tPhnl8sgHfwmOzTH_rPqp3K0CwTMf_2l_ak,1629
+cellwatch/snapshot.py,sha256=JeB3MWxoSCoEtGsQP9jhyDg9KkIJLI0WjnuOFeJvEe4,1599
+cellwatch-0.1.0.dist-info/METADATA,sha256=S-hCYCame8jQ9zFYjDTqIUEJZI4M_3IPZtMMIVpV8_I,5125
+cellwatch-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+cellwatch-0.1.0.dist-info/licenses/LICENSE,sha256=etqyFJRjLt4mer4j8ZcWZHFF8ovQhX1S1gzUcsgO_f0,1075
+cellwatch-0.1.0.dist-info/RECORD,,

cellwatch-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

cellwatch-0.1.0.dist-info/licenses/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.