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. Corrected test count 24 -> 29 in both README and CHANGELOG (re-verified by counting test functions: 29).

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.

Verified every Mojo snippet in the diff against src/tar/ — all APIs are real, no inventions:

  • read_tar_file(path)src/tar/tar.mojo (returns List[TarEntry])
  • e.info.name / e.info.size / e.info.mode / e.info.mtime / e.info.linknameTarEntry.info + TarInfo fields in src/tar/model.mojo
  • e.info.isfile() / isdir() / issym() / islnk() → all defined on TarInfo (model.mojo)
  • TarWriter() no-arg ctor → tar.mojo
  • w.add(name, data, mode=0o644, mtime=0) → matches TarWriter.add signature exactly (mode/mtime are real kwargs)
  • w.finalize() returns List[UInt8] → confirmed
  • add_dir(name) / add_symlink(name, target) → both present on TarWriter

Counts checked:

  • 29 tests — matches exactly (29 test_* fns in test/test_tar.mojo); CHANGELOG + README both updated. ✓
  • Eleven libraries — 10 sibling libs listed + mojo-tar itself = 11, consistent with the prior "Ten". ✓

Python-side snippets (tarfile.open, getmembers(), m.name/.size, m.isdir()/.issym()) are idiomatic and correct.

Minor (non-blocking): the tf.add(...)w.add("f.txt", data, ...) row is a loose analogy — Python's tarfile.add() reads a path from disk while mojo-tar's add takes in-memory bytes. The "/ write member" label makes the intent clear, so fine as a conceptual map.

No invented APIs, no wrong counts.

@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

Test count 24→29 verified exact (grep -c "^def test_" = 29). "Coming from Python" table checked line-by-line against src/tar/tar.mojo + model.mojo — all signatures match (read_tar_file, TarWriter().add(...), .finalize() -> List[UInt8], TarInfo.isfile/...). Suite count Ten→Eleven arithmetic correct; mojo-xml link resolves. CHANGELOG count consistent. No issues.

@conorbronsdon
conorbronsdon merged commit 9364722 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