Python API | TeXForm

Conventions#

The texform Python package exposes the parser, document model, transform engine, and serializer from one Rust core. Install it with pip install texform; see Installation for supported Python versions and platforms. Methods and arguments use snake_case; the JavaScript binding uses camelCase. Both bindings share the parsing and transform core, but configuration interfaces and some exception types differ.

Structured data crosses the boundary as plain dicts, never custom wrapper classes: parse results, transform reports, diagnostics, and argspec results are all dicts, and option inputs are dicts too. The bundled type stubs (texform/__init__.pyi) describe those shapes as TypedDict types, so editors and type checkers see the exact keys. Document and Node are live handles into a Rust tree; a SyntaxNode is a plain dict snapshot.

Configuration is two-layered. A per-call config= argument must be a complete configuration class — ParseConfig or the phase-nested TransformConfig — and a dict there raises ConfigError. Partial adjustments go through keyword overlays instead (parse(src, reject_unknown=True), normalize(src, rewrite={"enabled": False})), where nested values are plain dicts, not phase-config instances. The parse baseline is lenient.

The structured library exceptions derive from TexformError, so a single except texform.TexformError catches them: ParseError (an operation needed a complete tree but parsing produced none), EditError (an invalid edit), ConfigError (invalid construction input), and TransformError (a transform-engine failure). Parser.parse returns malformed-input diagnostics and a document that may be None; invalid configuration still raises ConfigError.

Module map#

Parser #

Symbol	Kind	Description
`Parser`	class	Turn LaTeX source into a parse result.
`ParseConfig`	class	Complete parse configuration. The only accepted `config=` type for parse.
`ParseOverrides`	dict type	Keyword overlays for `parse`. Omitted keys keep the baseline.
`ParseResult`	dict type	The result of `Parser.parse`: an optional document plus diagnostics.
`ParseDiagnostic`	dict type	A single parse diagnostic emitted alongside a parse result.
`ParseDiagnosticKind`	type	Category of a parse diagnostic, such as `"unknown-command"` or `"argument-validation"`.
`Span`	type	Half-open UTF-8 byte range `{"start": int, "end": int}` into the source.
`SyntaxNode`	type	Lossless parse snapshot as a plain dict. The tagged-union shape is documented on the TypeScript `SyntaxNode` type; Python keeps this alias unexpanded.
`ContextItem`	type	A knowledge-injection item: a command, environment, or delimiter-control dict.
`CommandItem`	dict type	A custom command injected into parser knowledge.
`EnvironmentItem`	dict type	A custom environment injected into parser knowledge.
`DelimiterItem`	dict type	A custom delimiter control injected into parser knowledge.

KnowledgeBase #

Symbol	Kind	Description
`KnowledgeBase`	class	Immutable knowledge shared by parsers, engines, and documents.
`CommandItem`	dict type	A custom command injected into parser knowledge.
`EnvironmentItem`	dict type	A custom environment injected into parser knowledge.
`DelimiterItem`	dict type	A custom delimiter control injected into parser knowledge.

Document #

Symbol	Kind	Description
`Document`	class	The editable document tree — the working format you read, edit, and output.
`NodeSpanEntry`	dict type	One entry mapping a node identifier to its source byte span.
`TokenizedLatex`	dict type	Serialized LaTeX and tokens produced by the same serializer traversal.
`SerializationToken`	dict type	One serialization fragment with UTF-8 byte offsets.
`SerializationTokenKind`	type	Semantic category of one serialization fragment.
`NodeTable`	dict type	Preorder node columns. Row indices are local to this snapshot.
`ArgumentTable`	dict type	All argument slots, ordered by owner row and slot index.
`ColumnarTree`	dict type	Tree columns for bulk structural analysis with Arrow or DataFrame tools.

Node #

Symbol	Kind	Description
`Node`	class	A read-only handle into a `Document` for navigation and reading.
`NodeKind`	type	Node kind as reported by `Node.kind()`. Python uses PascalCase (`"Root"`, `"Command"`, `"ActiveSpace"`).
`RuntimeContentMode`	type	Runtime content mode reported by the tree API: `"math"` or `"text"`.
`ErrorParts`	dict type	The decomposed content of an `Error` placeholder node.
`GroupKindExplicit`	dict type	A group written with explicit braces `{ ... }`.
`GroupKindImplicit`	dict type	A group with no surrounding braces, inferred from structure.
`GroupKindDelimited`	dict type	A group bounded by a delimiter pair, such as `\left( ... \right)`.
`GroupKindInlineMath`	dict type	A group introduced by inline math shift, such as $ ... $ in text mode.
`GroupKindRef`	type	The kind of a `Group` node: explicit, implicit, delimited, or inline-math.
`DelimiterValue`	type	A delimiter string: a character, a backslash-prefixed control, or a dot.
`MathArg`	dict type	A command argument carrying math-mode content.
`TextArg`	dict type	A command argument carrying text-mode content.
`DelimiterArg`	dict type	A command argument that is a single delimiter token.
`CSNameArg`	dict type	A command argument that is a control-sequence name.
`DimensionArg`	dict type	A command argument that is a TeX dimension, such as `2pt`.
`IntegerArg`	dict type	A command argument that is an integer literal.
`KeyValArg`	dict type	A command argument that is a `key=value` list.
`ColumnArg`	dict type	A command argument that is a tabular column specification.
`BooleanArg`	dict type	A command argument that is a star flag, modeled as a boolean.
`ArgRef`	type	A read command argument: one of the discriminated argument-value dicts.
`ArgFormKind`	type
`NodeSlotKind`	type
`ArgForm`	dict type
`OperatorNameArg`	dict type
`Paired`	class	Immutable content and delimiter pair for an argspec Paired slot.
`Arg`	type	Slot input: source written inside the slot, a detached content node, a star flag, absence, or an explicit `Paired` delimiter pair.
`NodeSlot`	dict type

TransformEngine #

Symbol	Kind	Description
`TransformEngine`	class	Normalize a formula into the canonical form selected by a profile.
`TransformConfig`	class	Complete transform configuration, nested by pipeline phase.
`RewriteConfig`	class	Complete Rewrite phase configuration.
`LowerAttributesConfig`	class	Complete LowerAttributes phase configuration.
`FinalizeAstConfig`	class	Complete FinalizeAst phase configuration.
`FlattenGroupsConfig`	class	Complete FlattenGroups phase configuration.
`NormalizeOverrides`	class	Flat parse+transform overlays for `normalize`.
`TransformOverrides`	dict type	Keyword overlays for `transform`.
`RewriteOverrides`	dict type	Keyword overlays for the Rewrite phase.
`LowerAttributesOverrides`	dict type	Keyword overlays for the LowerAttributes phase.
`FinalizeAstOverrides`	dict type	Keyword overlays for the FinalizeAst phase.
`FlattenGroupsOverrides`	dict type	Keyword overlays for the FlattenGroups phase.
`NormalizeReportResult`	dict type	Text plus the diagnostic report from one explicit normalize report call.
`TransformReport`	dict type	Diagnostic report for one explicit report call.
`TransformWarning`	dict type	An unknown input name whose arguments or scope cannot be guaranteed.
`LowerAttributesReport`	dict type	The LowerAttributes phase report.
`AttributeStat`	dict type	Activity for one `(attr, value)` pair in LowerAttributes.
`AttributeFormCounts`	dict type	Counts of one attribute form, split by carrier.
`RewriteReport`	dict type	The Rewrite phase report.
`RewriteRuleStat`	dict type	One rewrite rule's outcome for a single call.
`FinalizeAstReport`	dict type	The FinalizeAst phase report.
`FlattenGroupsReport`	dict type	The FlattenGroups phase report.
`FlattenGroupsActionCounts`	dict type	Flatten actions that changed the tree.
`FlattenGroupsGuardCounts`	dict type	Preserve-guard hits for one FlattenGroups run.
`TransformProfile`	type	Normalization profile name: `"authoring"`, `"faithful"`, `"corpus"`, or `"equiv"`.

serialize #

Symbol	Kind	Description
`serialize`	function	Render a `SyntaxNode` dict to LaTeX text.
`SerializeOptions`	dict type	Options for `Document.to_latex`, `Document.to_tokenized_latex`, and `serialize`.
`Style`	type	Spaced output is byte-stable; compact preserves structure and text idempotency.

validate_argspec #

Symbol	Kind	Description
`validate_argspec`	function	Validate an xparse-style argspec string and report its parsed slots.
`ValidateArgspecResult`	dict type	The outcome of validating an argspec string with `validate_argspec`.
`ParsedArgSpecSlot`	dict type	One parsed argument slot of an xparse-style specification.
`ArgSpecKindType`	type	Value kind of one parsed argspec slot (content, delimiter, star, ...).
`ArgSpecFormType`	type	Surface form of one parsed argspec slot (mandatory, optional group, paired, ...).

Utilities #

Symbol	Kind	Description
`list_packages`	function	List the built-in knowledge packages with their record counts.
`count_targets`	function	Count command, environment, and character targets in a LaTeX formula.
`PackageInfo`	dict type	Summary of one built-in knowledge package.
`TexformError`	exception	Base class for every exception the library raises.
`ParseError`	exception	Raised when source could not be parsed into a complete tree.
`EditError`	exception	Raised by a `Document` editing method on an invalid edit.
`ConfigError`	exception	Raised on invalid construction or per-call configuration input.
`TransformError`	exception	Raised on a transform-engine failure.
`ConformanceError`	exception	Raised when a construction, edit, or syntax import violates the knowledge base or the document's structure.
`list_rules`	function	List the built-in rewrite rules, sorted by key.
`RuleInfo`	dict type	Summary of one built-in rewrite rule.
`RuleFidelity`	type	A rewrite rule's worst-case equivalence guarantee, least to most faithful: `"math"` (meaning preserved, rendering may change), `"reading"` (notation content, reading order, and structural roles preserved), or `"render"` (rendering equivalent under the reference renderer).
`RuleLevel`	type	The first profile that accepts a rewrite rule's output as a suitable product.