Skip to content

refactor(py/handlebars)!: stop exporting parsed-template classes - #638

Open
huangjeff5 wants to merge 2 commits into
mainfrom
jeff/hb-private-ast
Open

huangjeff5 wants to merge 2 commits into
mainfrom
jeff/hb-private-ast

Conversation

@huangjeff5

@huangjeff5 huangjeff5 commented Nov 11, 2026 •

Copy link
Copy Markdown
Collaborator

dotpromptz_handlebars exported the scanner token and AST classes its parser builds internally. No public method, attribute, callback, or exception accepts or returns them, so they're no longer importable from dotpromptz_handlebars or handlebarrz.

# still works (engine, helper annotations, render options, errors)
from dotpromptz_handlebars import Handlebars, HelperFn, HelperOptions, SafeString, StrictModeError

# now raises ImportError
from dotpromptz_handlebars import Mustache  # also Block, ElseNode, InlinePartial, Node,
                                            # Partial, PartialBlock, Program, TagToken, Text

Decisions

  • Audited every public signature for type-annotation coverage: None of the 10 removed names (Block, ElseNode, InlinePartial, Mustache, Node, Partial, PartialBlock, Program, TagToken, Text) appear in any public parameter, return type, attribute, or callback. Handlebars.compile() closes over the parsed Program internally and returns Callable[..., str], Handlebars.register_template() returns None and stores list[Node] on private _templates, and Handlebars exposes no parse() or AST visitor API (matching legacy handlebarrz 0.1.9).
  • Kept every caller-facing runtime and annotation type: Callers still have every type needed to annotate engine configuration (Handlebars, EscapeFunction), custom helpers (HelperFn, HelperOptions, BlockFn, SafeString, Context, ContextDict), render calls (RuntimeOptions), and try/except blocks (StrictModeError, TemplateRecursionError).
  • Avoid freezing internal parser layout before 1.0: Several removed dataclasses carry raw parser state (Mustache.call: dict[str, Any], ElseNode as a pre-fold marker, TagToken scanner flags) that should stay free to change internally.
  • Backward compatibility with published dotpromptz: Every symbol imported by dotpromptz 0.1.6 and 0.2.0 still resolves from both dotpromptz_handlebars and handlebarrz.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant