The treebuilderutil module

Helper functions and classes for the treebuilder module.

class BuildResult(tree, start, end, offset, lexicons)

Bases: tuple

encapsulates the return values of TreeBuilder.build_new_tree()


Alias for field number 2


Alias for field number 4


Alias for field number 3


Alias for field number 1


Alias for field number 0

class ReplaceResult(start, end, lexicons)

Bases: tuple

encapsulates the return values of TreeBuilder.replace_tree()


Alias for field number 1


Alias for field number 2


Alias for field number 0

class Changes[source]

Bases: object

Store changes that have to be made to a tree.

This object is used by get_changes(). Calling add() merges new changes with the existing changes.

add(text, root_lexicon=False, start=0, removed=None, added=None)[source]

Merge new change with existing changes.

If added and removed are not given, all text after start is considered to be replaced.


Return True when there are actually changes.


Return how the current changes would affect an older start.

get_prepared_lexer(tree, text, start, new_tree=False)[source]

Get a prepared lexer reading from text, positioned at (or before) start.

Returns the three-tuple (lexer, events, tokens). The events stream is returned seperately because the last Event can be pushed back, so it is yielded again. The tokens are the last tokens group that remained the same.

Returns None when no position to start can be found, just start from the beginning in this case.

If new_tree is True, does not find a start position if there would no tokens remain left of it. This is useful when restarting a tree build; it avoids leaving empty contexts in the build tree that should not be there.

events_with_tokens(start_token, last_token)[source]

Yield (Event, tokens) tuples for start_token until and including last_token.

Events are yielded together with token groups (or single tokens in a 1-length tuple).

This function is used by get_prepared_lexer() to compare an existing token structure with events originating from a lexer.

The start_token must be the first of a group, if it is a GroupToken. Additionally, it should not be the first token in a context whose lexicon has the consume flag set. But if the start_token is the very first token in a tree, it does not matter if it is not in the root context, this case is handled gracefully.


Get a Lexer initialized at the token’s ancestry.


Return an empty context (and its root) with the same ancestry as the token’s.

find_token_before(node, pos)[source]

A version of Context.find_token_before() that can handle empty contexts.

The new tree built inside TreeBuilder.build_new_tree() can have an empty context at the beginning and/or the end. Returns None if there is no token left from pos.


A version of Node.ancestors_with_index() that can handle empty contexts.


A version of Node.backward() that can handle empty contexts.

common_ancestor_with_trail(node, other)[source]

A version of Token.common_ancestor_with_trail() that can handle empty contexts.

same_events(e1, e2)[source]

Compare Event tuples in a robust way.

Returns True if the events are completely the same. The lexicon in a target is compared on identity instead of equality. This prevents different derived lexicons from comparing the same, which is needed when rebuilding a tree.