Tag module

The tie.tag module exposes the functions needed to manage your tag patterns, as well as the base classes needed to customize their behaviour or the way they will be managed in your application.

Module’s Top level Classes & Utilities

tie.tag.register(*tag_list)

Register a sequence of tags.

Call this function and pass it an arbitrary number of tags to register them with TIE.

Since your Tag list is needed by various internal parts of the TIE library, you must use this function in order for them to have any effect. TIE stores them in a default TagManager instance, which you can replace if you need it to behave differently (See below).

Each tag parameter should be either a string of the tag’s regular expression (or an already compiled regex object), or an instance of Tag (or of any class inheriting from it). Instanciating your Tag objects manually allows you to adjust their behaviour, either by tweaking their default parameters or by using a custom subclass:

tie.tag.register(
    "sometagpattern",
    tie.Tag("anothertag", processor=FOO),
    MyCustomTagSubclass("taggytagtag"),
    ...
)

Internally, this function simply hands each of its parameters to the current TagManager and lets it handle the registration process. Actual error checking is done in the Tag ‘s constructor.

Note

The actual arguments expected by register might vary if you decide to use a different TagManager. For instance, a PriorityTagManager will expect tuples of (tag, priority). register will simply pass each item it receives to the current manager; see their documentation, as well as the one for any custom Tag class you might use, to know for certain how you should register your tag patterns.

class tie.tag.Tag(pattern, flags=0, processor=tie.processors.sub)

The Tag class is TIE’s central component.

It’s a somewhat boosted regular expression object, which knows how to match itself against a given template, and modify each occurence of its pattern within the template’s text using its internal processor function.

TIE takes care of managing and handling its registered Tag object, but instanciating them manually allows one to change their default behaviour by providing a custom callback as the processor argument. (Default processors callbacks are defined in the <tie.processors> module.)

If further customisation is needed, feel free to override its public methods in a subclass.

Parameters:

• pattern: Regular expression used for tag matching.

  This can be either a normal string or an already compiled regular expression.

• flags: re module’s flags for pattern compilation.

  Pass them just as you would when using the re.compile() function.

• processor: Tag processing callback.

  Processor function should accept a match object as their first parameter, and a dictionnary of keyword arguments containing the context variables available for processing.

  For more information about tag processors, see this HOWTO on tags customization (once its there, that is...)

Todo

Link to custom tags guide

Tag.match(template)

Find all matches in template and return them as an generator object.

Tag.process(template, **context)

Scan the template string for all occurences of the Tag and process those using the instance’s own processor function. Context args will be passed to the processor function. Return a dictionnary mapping the matched tags from the template with their corresponding values.

Note

For convenience, the Tag class is imported into TIE’s global namespace, so you can just import tie.Tag.

Managers

TIE uses an internal manager object to keep track of every registered tag. It will use a basic TagManager instance by default, which should be able to handle the simplest use cases, so that you don’t have to worry about those if you don’t need to.

It also provides a few specialized managers with commonly needed special behaviour. If you need tighter control on how your tags should be stored and handled, you can also define and use your own TagManager subclass.

The tie.tag module exposes the two following functions to set or access the current manager:

tie.tag.set_manager(manager)

Set the global TagManager to manager. Only useful to setup a custom manager.

tie.tag.get_manager()

Return the global TagManager

Note

Since the register function appends the tags it receives to the current manager, it should only be called after setting any custom one.

Warning

Unlike Template Managers, which are completely optionnal, most of TIE’s internal objects require a global TagManager instance to be set in order to be able to perform their tasks. While it is possible to bypass calling the get_manager function when using a non-default manager if you also tweak these objects, doing so will probably bypass most of TIE’s convenience as well.

TIE comes with the following managers:

class tie.tag.TagManager

A basic Tag container to keep track of registered tags. TIE will use this manager by default. You can iterate over it to retrieve individual tags – Those will be yielded in the order of their insertion:

>>> tie.tag.register('pattern2',
...                  'pattern1',
...                  'pattern3'
... )
>>> manager = tie.tag.get_manager()
>>> for tag in manager:
...     print(tag)
...
<Tag 'pattern2'>
<Tag 'pattern1'>
<Tag 'pattern3'>

Tags are stored in a simple list, in a “private” _tag_list attribute. Subclasses will probably need to override this attribute in order to use other data structures.

TagManager.add(tag)

Register a new tag. Override this method to accomodate a different internal data strucutre.

This method is called by the register function.

TagManager.clear()

Clear the internal tag list. Override to accomodate a different internal data strucutre.

TagManager.__iter__()

Yield contained tags. Override to accomodate a different internal data strucutre.

TagManager._check_tag(tag, cls=tie.tag.Tag)

Static method.

Internal checking method, called before inserting any tag to the manager’s tag list. It simply passes its tag parameter to the cls constructor if tag is not already an instance (or subclass) of it – This is what allows you to pass either regular strings or Tag instances to the register function.

Actual error handling is left to the called constructor.

You might need to override this method if you’re using fancier Tag objects. If not, you should probably still remember to call it before inserting your tags when redefining the add method.

Moar specialized managers provided by TIE are listed below:

class tie.tag.PriorityTagManager

Bases: tie.tag.TagManager

TagManager that keeps a priority value along its tags and yields them in that order.

Tags with the lowest priority value will be yielded first:

>>> tie.tag.set_manager(tie.tag.PriorityTagManager())
>>> tie.tag.register(
...     ('sometag', 2),
...     ('othertag', 0),
...     ('taggytag', 1),
... )
>>> manager = tie.tag.get_manager()
>>> for tag in manager:
...     print(tag)
...
<Tag 'othertag'>
<Tag 'taggytag'>
<Tag 'sometag'>

add(tag)

Register a new tag. tag should be a tupple (tag, priority). If not, priority will default to 0.

clear()

Clear the internal tag list.