fixes #2

Author: jph00

DEV.md

@@ -18,7 +18,7 @@ src/
   bin/exhash.rs   CLI editor (atomic in-place edit, dry-run, stdin mode)
   bin/lnhashview.rs  CLI viewer
 python/exhash/
-  __init__.py     Python wrapper (EditResult class, exhash function)
+  __init__.py     Python wrapper functions with typed/docstring API (+ exhash_result helper)
 python/exhash.data/scripts/
   exhash          native binary (built, not checked in)
   lnhashview      native binary (built, not checked in)

README.md

@@ -65,7 +65,7 @@ In `--stdin` mode, multiline `a/i/c` text blocks are not available.
 ## Python API
 
 ```py
-from exhash import exhash, lnhash, lnhashview, line_hash
+from exhash import exhash, exhash_result, lnhash, lnhashview, line_hash
 ```
 
 ### Viewing
@@ -82,8 +82,8 @@ view = lnhashview(text)  # ["1|a1b2|  foo", "2|c3d4|  bar"]
 ```py
 addr = lnhash(1, "foo")  # "1|a1b2|"
 res = exhash(text, [f"{addr}s/foo/baz/"])
-print(res.text())      # "baz\nbar"
-print(res.modified)    # [1]
+print(res["lines"])    # ["baz", "bar"]
+print(res["modified"]) # [1]
 
 # Multiple commands
 a1, a2 = lnhash(1, "foo"), lnhash(2, "bar")
@@ -93,15 +93,14 @@ res = exhash(text, [f"{a1}s/foo/FOO/", f"{a2}s/bar/BAR/"])
 res = exhash(text, [f"{addr}a\nnew line 1\nnew line 2"])
 ```
 
-### EditResult
+### Result dict
 
-- `.lines` — list of output lines
-- `.hashes` — lnhash for each output line
-- `.modified` — 1-based line numbers of modified/added lines
-- `.deleted` — 1-based line numbers of removed lines (in original)
-- `.text()` — joined output
-- `.view()` — output in lnhash format
-- `repr()` — shows only modified lines in lnhash format
+- `lines` — list of output lines
+- `hashes` — lnhash for each output line
+- `modified` — 1-based line numbers of modified/added lines
+- `deleted` — 1-based line numbers of removed lines (in original)
+
+`exhash_result([res1, res2, ...])` renders modified lines in lnhash format, matching the old `repr(EditResult)` style.
 
 ## Tests
 

python/exhash/__init__.py

@@ -1,13 +1,35 @@
-from .exhash import line_hash, lnhash, lnhashview, exhash as _exhash
+from .exhash import line_hash as _line_hash, lnhash as _lnhash, lnhashview as _lnhashview, exhash as _exhash
 
-class EditResult:
-    def __init__(self, r): self.lines, self.hashes, self.modified, self.deleted = r.lines, r.hashes, r.modified, r.deleted
-    def text(self): return '\n'.join(self.lines)
-    def view(self): return '\n'.join(f"{h}  {l}" for h, l in zip(self.hashes, self.lines))
-    def __repr__(self): return '\n'.join(f"{self.hashes[i-1]}  {self.lines[i-1]}" for i in self.modified if i-1 < len(self.hashes))
+def line_hash(line:str) -> str:
+    'Return a 4-char lowercase hex hash for a single line of text.'
+    return _line_hash(line)
 
-def exhash(text:str, cmds:list[str]):
-    """Verified line-addressed editor. Apply commands to `text`, return `EditResult`.
+
+def lnhash(lineno:int, line:str) -> str:
+    'Return an lnhash address ``lineno|hash|`` for ``line`` at 1-based ``lineno``.'
+    return _lnhash(lineno, line)
+
+
+def lnhashview(text:str) -> list[str]:
+    'Return lines formatted as ``lineno|hash|  content`` for each line in ``text``.'
+    return _lnhashview(text)
+
+
+def exhash_result(results:list[dict]) -> str:
+    """Format modified lines from exhash result dicts in lnhash view format."""
+    if not isinstance(results, list): raise TypeError("results must be a list[dict]")
+    out = []
+    for r in results:
+        if not isinstance(r, dict): raise TypeError("results must be a list[dict]")
+        lines, hashes, modified = r.get("lines"), r.get("hashes"), r.get("modified")
+        if not isinstance(lines, list) or not isinstance(hashes, list) or not isinstance(modified, list):
+            raise TypeError("each result must include list fields: lines, hashes, modified")
+        out += [f"{hashes[i-1]}  {lines[i-1]}" for i in modified if isinstance(i, int) and 0 < i <= len(hashes)]
+    return '\n'.join(out)
+
+
+def exhash(text:str, cmds:list[str]) -> dict:
+    """Verified line-addressed editor. Apply commands to `text`, return a result dict.
 
     Commands use lnhash addresses: ``lineno|hash|cmd`` where hash is a 4-char
     hex content hash. Use ``lnhashview(text)`` or ``lnhash(lineno, line)`` to
@@ -37,14 +59,11 @@ def exhash(text:str, cmds:list[str]):
     For a/i/c, remaining lines in the command string are the text block
     (no '.' terminator needed, unlike the CLI).
 
-    Returns EditResult with:
-      .lines     list of output lines
-      .hashes    lnhash for each output line
-      .modified  1-based line numbers of modified/added lines
-      .deleted   1-based line numbers of removed lines (in original)
-      .text()    joined output
-      .view()    output in lnhash format
-      repr()     shows only modified lines in lnhash format
+    Returns a dict with:
+      lines     list of output lines
+      hashes    lnhash for each output line
+      modified  1-based line numbers of modified/added lines
+      deleted   1-based line numbers of removed lines (in original)
 
     `cmds` is a required list of command strings. For `a`/`i`/`c`, include the
     text block in the same command string after a newline.
@@ -55,8 +74,9 @@ def exhash(text:str, cmds:list[str]):
       text = "foo\\nbar\\n"
       addr = lnhash(1, "foo")           # "1|a1b2|"
       res = exhash(text, [f"{addr}s/foo/baz/"])
-      print(res)                         # "1|c2da|  baz" (modified lines only)
-      res.text()                         # "baz\\nbar"
+      print(res["lines"])                # ["baz", "bar"]
+      "\\n".join(res["lines"])           # "baz\\nbar"
       res = exhash(text, [f"{addr}a\\nnew line 1\\nnew line 2"])
     """
-    return EditResult(_exhash(text, *cmds))
+    r = _exhash(text, *cmds)
+    return dict(lines=r.lines, hashes=r.hashes, modified=r.modified, deleted=r.deleted)

tests/test_exhash.py

@@ -1,5 +1,5 @@
 import pytest
-from exhash import line_hash, lnhash, lnhashview, exhash
+from exhash import line_hash, lnhash, lnhashview, exhash, exhash_result
 
 def test_line_hash_returns_4_hex():
     h = line_hash("hello")
@@ -27,86 +27,98 @@ def test_lnhashview_empty(): assert lnhashview("") == []
 
 def test_exhash_noop():
     res = exhash("foo\nbar\n", [])
-    assert res.lines == ["foo", "bar"]
-    assert res.text() == "foo\nbar"
-    assert res.modified == []
-    assert res.deleted == []
+    assert res["lines"] == ["foo", "bar"]
+    assert '\n'.join(res["lines"]) == "foo\nbar"
+    assert res["modified"] == []
+    assert res["deleted"] == []
 
 def test_exhash_substitute():
     text = "foo\nbar\n"
     addr = lnhash(1, "foo")
     res = exhash(text, [f"{addr}s/foo/baz/"])
-    assert res.lines == ["baz", "bar"]
-    assert res.modified == [1]
-    assert len(res.hashes) == 2
+    assert res["lines"] == ["baz", "bar"]
+    assert res["modified"] == [1]
+    assert len(res["hashes"]) == 2
 
 def test_exhash_delete():
     text = "a\nb\nc\n"
     addr = lnhash(2, "b")
     res = exhash(text, [f"{addr}d"])
-    assert res.lines == ["a", "c"]
-    assert 2 in res.deleted
+    assert res["lines"] == ["a", "c"]
+    assert 2 in res["deleted"]
 
 def test_exhash_append():
     text = "a\nb\n"
     addr = lnhash(1, "a")
     res = exhash(text, [f"{addr}a\nx\ny"])
-    assert res.lines == ["a", "x", "y", "b"]
-    assert res.modified == [2, 3]
+    assert res["lines"] == ["a", "x", "y", "b"]
+    assert res["modified"] == [2, 3]
 
 def test_exhash_insert():
     text = "a\nb\n"
     addr = lnhash(2, "b")
     res = exhash(text, [f"{addr}i\nx"])
-    assert res.lines == ["a", "x", "b"]
-    assert res.modified == [2]
+    assert res["lines"] == ["a", "x", "b"]
+    assert res["modified"] == [2]
 
 def test_exhash_stale_hash_raises():
     text = "hello\nworld\n"
     addr = lnhash(1, "wrong")
     with pytest.raises(ValueError): exhash(text, [f"{addr}d"])
 
-def test_exhash_repr_shows_modified():
+def test_exhash_result_is_dict():
     text = "foo\nbar\n"
     addr = lnhash(1, "foo")
     res = exhash(text, [f"{addr}s/foo/baz/"])
-    r = repr(res)
-    assert "baz" in r
-    assert "bar" not in r
-    assert r == f"{lnhash(1, 'baz')}  baz"
+    assert isinstance(res, dict)
+    assert set(res.keys()) == {"lines", "hashes", "modified", "deleted"}
+
+
+def test_exhash_result_formats_modified():
+    text = "foo\nbar\n"
+    addr = lnhash(1, "foo")
+    res = exhash(text, [f"{addr}s/foo/baz/"])
+    assert exhash_result([res]) == f"{lnhash(1, 'baz')}  baz"
+
+
+def test_exhash_result_no_modifications_is_empty(): assert exhash_result([exhash("foo\n", [])]) == ""
+
+
+def test_exhash_result_requires_list_of_dict():
+    with pytest.raises(TypeError): exhash_result(dict(lines=[], hashes=[], modified=[]))
+    with pytest.raises(TypeError): exhash_result([1])
 
-def test_exhash_repr_noop_empty(): assert repr(exhash("foo\n", [])) == ""
 
 def test_exhash_view():
     text = "foo\nbar\n"
     res = exhash(text, [])
-    assert res.view() == f"{lnhash(1, 'foo')}  foo\n{lnhash(2, 'bar')}  bar"
+    view = '\n'.join(f"{h}  {l}" for h, l in zip(res["hashes"], res["lines"]))
+    assert view == f"{lnhash(1, 'foo')}  foo\n{lnhash(2, 'bar')}  bar"
 
 def test_exhash_result_hashes_match():
     text = "foo\nbar\n"
     res = exhash(text, [])
-    for i, (h, line) in enumerate(zip(res.hashes, res.lines)): assert h == lnhash(i + 1, line)
+    for i, (h, line) in enumerate(zip(res["hashes"], res["lines"])): assert h == lnhash(i + 1, line)
 
 def test_exhash_multiple_cmds():
     text = "a\nb\nc\n"
     a1, a3 = lnhash(1, "a"), lnhash(3, "c")
     res = exhash(text, [f"{a1}s/a/A/", f"{a3}s/c/C/"])
-    assert res.lines == ["A", "b", "C"]
-    assert res.modified == [1, 3]
+    assert res["lines"] == ["A", "b", "C"]
+    assert res["modified"] == [1, 3]
 
 def test_exhash_append_trailing_newline():
     text = "a\nb\n"
     addr = lnhash(1, "a")
     res = exhash(text, [f"{addr}a\nx\n"])
-    assert res.lines == ["a", "x", "", "b"]
+    assert res["lines"] == ["a", "x", "", "b"]
 
 def test_exhash_multiline_non_text_cmd_raises():
     text = "a\nb\n"
     addr = lnhash(1, "a")
     with pytest.raises(ValueError): exhash(text, [f"{addr}d\nextra"])
 
-def test_exhash_accepts_tuple_cmds():
+def test_exhash_requires_list_cmds():
     text = "a\nb\n"
     a1, a2 = lnhash(1, "a"), lnhash(2, "b")
-    res = exhash(text, (f"{a1}s/a/A/", f"{a2}s/b/B/"))
-    assert res.lines == ["A", "B"]
+    with pytest.raises(TypeError): exhash(text, (f"{a1}s/a/A/", f"{a2}s/b/B/"))