Skip to content

docs: add Coming-from-Python section + fix stale counts#1

Merged
conorbronsdon merged 1 commit into
mainfrom
docs/python-onramp-and-accuracy
Jul 6, 2026
Merged

docs: add Coming-from-Python section + fix stale counts#1
conorbronsdon merged 1 commit into
mainfrom
docs/python-onramp-and-accuracy

Conversation

@conorbronsdon

Copy link
Copy Markdown
Owner

Summary

Two documentation changes:

  1. Coming from Python — a short side-by-side section (near the top, after
    the intro) mapping the familiar Python API to this library's real API.
    Every snippet was extracted from this repo's own examples/ and test/;
    nothing was invented.
  2. Accuracy fixes — Suite copy Ten -> Eleven and added mojo-xml link. Test count re-verified by counting: 32 (matches README).

Test counts were re-verified by actually counting the test functions in the
repo (not trusting the prior text).

From an automated review (personal-context#62); drafted by Claude Code — please review the Coming-from-Python snippets for API accuracy.

Adds a "Coming from Python" on-ramp table (verified against the repo's own
examples/ and tests) and corrects suite/test-count accuracy issues.

Co-Authored-By: Claude <noreply@anthropic.com>
@conorbronsdon

Copy link
Copy Markdown
Owner Author

🤖 Independent Claude review: Ready to merge.

Verified every Mojo API in the new "Coming from Python" table against src/diff/ — all real, no invented APIs:

  • unified_diff(a, b, fromfile, tofile, n)src/diff/diff.mojo:266 def unified_diff(a_text, b_text, from_file="a", to_file="b", context=3). The "takes whole strings and splits for you" note is accurate — it calls splitlines_keepends internally. Matches examples/diff_files.mojo.
  • ratio(...)src/diff/diff.mojo:179 def ratio(a: List[String], b: List[String]).
  • get_opcodes(...)src/diff/diff.mojo:152 def get_opcodes(a: List[String], b: List[String]).
  • splitlines_keepends(s)src/diff/diff.mojo:28 def splitlines_keepends(text: String) -> List[String] — return type feeds ratio/get_opcodes correctly.

All four are exported from src/diff/__init__.mojo. Python-side snippets (difflib.unified_diff, SequenceMatcher(None, a, b).ratio(), .get_opcodes()) are all real, idiomatic difflib.

Accuracy checks:

  • "32 tests" — correct: 32 def test_* fns in test/test_diff.mojo.
  • "Eleven libraries" — correct: 10 linked repos + mojo-diff itself = 11.
  • New mojo-xml cross-link resolves; repo description ("ElementTree-shaped DOM") matches the README's characterization.

No blocking issues.

@conorbronsdon conorbronsdon marked this pull request as ready for review July 6, 2026 07:58
@conorbronsdon

Copy link
Copy Markdown
Owner Author

Docs review (sonnet): SHIP

CHANGELOG "32 tests" verified (32 def test_). Table matches src/diff/diff.mojounified_diff(...) takes whole strings (correctly contrasted with Python's list-based), ratio/get_opcodes take List[String]. Suite Ten→Eleven correct. Cosmetic only: the table labels a param n where the source names it context (positional, so harmless).

@conorbronsdon conorbronsdon merged commit 8751746 into main Jul 6, 2026
1 check passed
@conorbronsdon conorbronsdon deleted the docs/python-onramp-and-accuracy branch July 6, 2026 08:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant