Skip to content

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

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

docs: add Coming-from-Python section + fix stale counts#1
conorbronsdon merged 2 commits 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: 59 (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: Needs-work (one blocking accuracy issue; all fenced code snippets verified clean).

Verified against src/ + examples/:

  • The Mojo snippet checks out end-to-end: from template import render, Context, TemplateValue (all three exported from src/template/__init__.mojo), Context(), ctx["name"] = TemplateValue("...") (implicit String ctor in value.mojo), render(source, ctx) (render.mojo).
  • TemplateValue.dict([keys],[values]) and TemplateValue.list([...]) are real static factories (value.mojo), matching examples/render_email.mojo.
  • Filters | default(...), | length, and loop.index all exist (render.mojo: _apply_filter, _make_loop).
  • Python jinja2 snippet (Template(...).render(name=...)) is idiomatic and correct.
  • Counts: 59 test fns confirmed (grep -cE '^(fn|def) test' test/test_template.mojo = 59, matches README). "Eleven" is correct — the suite section lists 10 sibling libs after adding mojo-xml, +1 for mojo-template itself = 11. mojo-xml repo exists; description (xml.etree.ElementTree-shaped DOM) matches its GitHub description.

Blocking — misleading API capability (Coming-from-Python, final paragraph):

parse_template(source) returns a reusable Template if you want to render the same source repeatedly.

parse_template and Template exist, but:

  1. They are not exported from the template package (__init__.mojo only re-exports render, escape_html, TemplateValue, Context) — so from template import parse_template fails; you'd need from template.parser import ....
  2. More importantly, there is no public way to render a pre-parsed Template. Template has no render method, and the only render(source: String, context) re-parses internally every call. So the promised benefit ("render the same source repeatedly" from a cached Template) isn't achievable with the public API.

Fix: drop that sentence, or reword to note render() re-parses each call and there is no reuse path yet. Everything else is accurate and ready.

The section's closing sentence claimed `parse_template(source)` returns a
reusable `Template` "if you want to render the same source repeatedly."
That API is not public: `parse_template`/`Template` live in
`template.parser` and are not re-exported from the `template` package
(only `render`, `escape_html`, `TemplateValue`, and `Context` are), so
`from template import parse_template` would fail — and `Template` has no
render method anyway. Reword to describe the real, exported public API:
the single `render(source, context)` entry point, which compiles and
renders in one call. Every snippet in the section now uses only exported
symbols.

Co-Authored-By: Claude <noreply@anthropic.com>
@conorbronsdon
conorbronsdon marked this pull request as ready for review July 6, 2026 08:09
@conorbronsdon

Copy link
Copy Markdown
Owner Author

Docs review (sonnet): CHANGES-NEEDED

Most claims check out (Context, TemplateValue(...), .dict/.list, render(source, ctx), loop filters; 59-test count exact; suite arithmetic correct).

Finding — the new "Coming from Python" section says parse_template(source) returns a reusable Template for repeated rendering. But parse_template/Template are not exported from src/template/__init__.mojo (only TemplateValue, Context, render, escape_html), and there's no public render-from-Template path (render() always re-parses). Following that sentence literally → ImportError. This is exactly the sentence the PR asks reviewers to verify, so it's a blocker. Fix: soften to just render(source, ctx) (or export the symbols). A soften is being applied to this branch now.

@conorbronsdon
conorbronsdon merged commit 83a658a into main Jul 6, 2026
1 check passed
@conorbronsdon
conorbronsdon deleted the docs/python-onramp-and-accuracy branch July 6, 2026 08:16
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