The transform module

Transform c.q. evaluate a tree or a stream of events.

This module provides the Transformer that does the work, the Transform base class for all your transforming classes, the Item that wraps the output of sub-contexts, the Items list type to ease iterating over the contents of a context, and some toplevel convenience functions.

See also the documentation: Transforming.

class Item(name, obj)

Bases: parce.transform.Item

A named tuple(name, obj) wrapping the return value of a Transform method.

The name attribute is the name of the Lexicon and transform method that created the object obj. To make it easier to distinguish an Item from a Token, Item has as class attribute is_token set to False.

is_token = False

class Items(arg, iterable=())

Bases: list

A list of Item and Token instances.

The Transformer populates this list with all the Tokens from a Context, replacing nested Contexts with an Item that wraps the return value of the Transform method for that Context’s lexicon.

The Transform methods are called with an instance of this class. Besides being a Python list, this class also has some methods that filter out items or tokens, etc.

Slicing from Items returns a new Items instance, so you can slice and the methods still work.

property arg

The lexicon’s argument (if any).

tokens(*texts)

Yield only the tokens, ignoring Item objects that represent sub-contexts.

If one or more texts are given, only yield tokens with one of the texts.

items(*names)

Yield only the sub-Items, ignoring any Token instances.

If one or more names are given, only yield items that have one of the names.

Because you know only Item instances and not Tokens will be yielded, you can unpack name and object in one go:

for name, obj in items.items():
    ...

grouped_objects(*names)

Yield objects in groups, specified by the names.

The order remains the same. For example, when you have a stream of key and value Item objects, calling grouped_objects(‘key’, ‘value’) yields the objects in (key, value) pairs.

For missing objects, None is yielded. Tokens are ignored.

peek(index, *values)

Return True if the items from index compare equal with the values.

For tokens, the value is their action; for Item instances their name. Negative indices are allowed.

New in version 0.27.0.

class Transform

Bases: object

This is the base class for a transform class.

Currently it has no special behaviour, but that might change in the future.

class Transformer

Bases: parce.util.Observable

Evaluate a tree.

For every context, the transformer calls the corresponding method of the Transform instance with the contents of that context, where sub-contexts are already replaced with the transformed result.

When a tree is transformed, Transformer emits the following events you can connect to:

"started":

emitted when transforming has started, with the tree as argument

"updated":

emitted when the transformation has fully completed, with the tree and the resulting transformation

"finished":

always emitted when transformation has quit, also when it was inrerrupted due to tree modification while transforming was busy; with the tree as argument

transform_name_template = '{}Transform'

This format string creates the name to look for when searching a suitable Transform class in a Language module space (see find_transform()).

New in version 0.27.0.

transform_text(root_lexicon, text, pos=0)

Directly create an evaluated object from text using root_lexicon.

The transform methods get intermediate tokens, but no tree is built and the tokens don’t have a parent.

transform_tree(tree)

Evaluate a tree structure.

build(tree)

Called when a tree needs to be transformed.

The default implementation iterates over process() to perform the job. You can reimplement this method to perform the job in a background thread.

process(tree)

Transform the tree and emit events.

Updates the cached result if the transformation was not interrupted. This method returns a generator; exhaust it fully to perform the transformation.

interrupt(tree)

Tell the Transformer to stop transforming the specified tree.

result(tree)

Get the result of the transformed tree.

Returns None if no result was yet created. Although this method is intended to return the transformed result for the root node, it can be used to get the intermediate result for any Context node.

invalidate_node(node)

Remove the transform results for this node and its ancestors from our cache.

Does not throw away the result for the root context.

connect_treebuilder(builder)

Connect to the events of the TreeBuilder.

This causes the Transformer to automatically update the transformation when the tree builder updates the tree.

disconnect_treebuilder(builder)

Disconnects from the events of the TreeBuilder.

slot_replace(builder)

Called when the tree builder starts altering the tree.

Interrupts a process if busy for that tree.

slot_update(builder)

Called when the tree builder has finished building the tree.

Starts a new transformation job for the tree.

get_transform(language)

Return a Transform class instance for the specified language.

May return None, if no Transform was added and none could be found.

add_transform(language, transform)

Add a Transform instance for the specified language.

You may also specify None, to disable transformation for that language even if a transform could automatically be found.

find_transform(language)

Try to find a Transform for the specified language definition.

This is done by looking for a Transform subclass in the language’s module, with the same name as the language with “Transform” appended. So for a language class named “Json”, this method tries to find a Transform in the same module with the name “JsonTransform”.

This naming scheme can be modified by setting the transform_name_template attribute.

This method is called by get_transform() if no Transform was added for the language.

transform_tree(tree, transform=None)

Convenience function that transforms tree using Transform.

If you don’t specify a Transform to use, parce tries to find one using the Transformer.find_transform() method.

If you want to specify multiple Transforms for different Language you expect in the tree you want to transform, instantiate a Transformer, add the Transforms you want and call its Transformer.transform_tree() method directly.

transform_text(root_lexicon, text, transform=None, pos=0)

Convenience function that transforms text directly using Transform.

If you don’t specify a Transform to use, parce tries to find one using the Transformer.find_transform() method.

If you want to specify multiple Transforms for different Language you expect in the text you want to transform, instantiate a Transformer, add the Transforms you want and call its Transformer.transform_text() method directly.

add_untransformed(func)

Decorator to mark a Transform method with the ‘add_untransformed’ flag.

When a Transform method has this flag, child contexts of this method’s context that have no transform method are not silently ignored, but added in an Item with name <untransformed> (including the angle brackets).

For example:

class MyLangTransform(Transform):
    @add_untransformed
    def root(self, items):
        "This method also gets the untransformed Contexts"
        for item in items:
            if not item.is_token and item.name == "<untransformed>":
                context = item.obj
                # do something with the parce context....