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.

TODO: it would be nice to be able to specify the Transform for another Language inside a Transform, just like a lexicon can target a lexicon from a different language. But I’m not yet sure how it would be specified.

class Item(lexicon, obj)

Bases: object

An Item wraps any object returned by a transform method.

It has two readonly attributes, lexicon and obj. The lexicon is the lexicon that created the items a transform method is called with. To be able to easily distinguish an Item from a Token, a fixed readonly class attribute is_token exists, set to False.

An Item can be unpacked in two variables, name and object:

item = Item(Json.root, "abc")
name, obj = item    # → 'root', 'abc'

is_token = False

lexicon

obj

property name

The lexicon’s name.

class Items

Bases: list

A list of Item and Token instances.

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.

tokens(*texts)

Yield only the tokens.

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

items(*names)

Yield only the sub-items.

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():
    ...

objects(*classes)

Yield only the objects from sub-items.

If one or mode classes are specified, only yields objects that are an instance of that class/classes.

action(*actions)

Yield only the tokens with one of the specified actions.

in_action(*actions)

Yield only the tokens with an action that’s in one of the specified actions.

grouped()

Yield two-tuples(tokens, item).

The tokens value is a tuple itself of zero or more tokens; grouped tokens (that originated from one match) are yielded together; otherwise there is just one token.

If the token(s) are followed by an item, it is yielded as well; if not, item is None. If there are no tokens after an item but there is another item; tokens is an empty tuple then.

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_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.

add_transform(language, transform)

Add a Transform instance for the specified language.

find_transform(language)

If no Transform was added, try to find a predefined one.

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 “Css”, this method tries to find a Transform in the same module with the name “CssTransform”.

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.

validate_transform(transform, language)

Check whether the Transform has a method for every lexicon.

Prints the missing names to the screen.

class BackgroundTransformer

Bases: parce.transform.Transformer

A Transformer that does its job in a background thread.

build(tree)

Reimplemented to build the transformation in a background thread.

This method starts a background thread performing the transformation and returns immediately.

wait(tree)

Wait for completion of the transformation of the tree if busy.

busy(tree)

Return True if a job transforming the tree is busy.