What does the python re.template function do?

Question

While using the re module in ipython I noticed an undocumented template function:

In [420]: re.template?
Type:           function
Base Class:     <type 'function'>
String Form:    <function template at 0xb7eb8e64>
Namespace:      Interactive
File:           /usr/tideway/lib/python2.7/re.py
Definition:     re.template(pattern, flags=0)
Docstring:
    Compile a template pattern, returning a pattern object

there is also a flag re.TEMPLATE and its alias re.T.

None of this is mentioned in the docs for either 2.7 or 3.2. What do they do? Are they obsolete hangovers from an earlier version of Python, or an experimental feature that may be officially added in the future?

Answer 1

In CPython 2.7.1, re.template() is defined as:

def template(pattern, flags=0):
    "Compile a template pattern, returning a pattern object"
    return _compile(pattern, flags|T)

_compile calls _compile_typed which calls sre_compile.compile. The only place in the code where the T (aka SRE_FLAG_TEMPLATE) flag is checked is in that function:

    elif op in REPEATING_CODES:
        if flags & SRE_FLAG_TEMPLATE:
            raise error, "internal: unsupported template operator"
            emit(OPCODES[REPEAT])
            skip = _len(code); emit(0)
            emit(av[0])
            emit(av[1])
            _compile(code, av[2], flags)
            emit(OPCODES[SUCCESS])
            code[skip] = _len(code) - skip
    ...

This would have the effect of disabling all repetition operators (*, +, ?, {} etc):

In [10]: re.template('a?')
---------------------------------------------------------------------------
.....
error: internal: unsupported template operator

The way the code is structured (the unconditional raise preceding a bunch of dead code) makes me think that the feature was either never fully implemented, or has been turned off due to some problems. I can only guess what the intended semantics may have been.

The end result is that the function does nothing useful.

Answer 2

I don't know what this function does, but it's been in the code since at least as far back as 2.3, in the sre.py file, and the code still has this comment:

# sre extensions (experimental, don't rely on these)
T = TEMPLATE = sre_compile.SRE_FLAG_TEMPLATE # disable backtracking

I would stay away from them.