Go to the latest version of this document.

# ``twisted`.`web`.`template``

module documentation
(source)

HTML rendering for twisted.web.

Class | `CDATA` | A `<![CDATA[]]>` block from a template. Given a separate representation in the DOM so that they may be round-tripped through rendering without losing information.
Class | `CharRef` | A numeric character reference. Given a separate representation in the DOM so that non-ASCII characters may be output as pure ASCII.
Class | `Comment` | A `<!-- -->` comment from a template. Given a separate representation in the DOM so that they may be round-tripped through rendering without losing information.
Class | `Element` | Base for classes which can render part of a page.
Class | `slot` | Marker for markup insertion in a template.
Class | `Tag` | A `Tag` represents an XML tags with a tag name, attributes, and children. A `Tag` can be constructed using the special `twisted.web.template.tags` object, or it may be constructed directly with a tag name. `Tag`...
Class | `TagLoader` | An `ITemplateLoader` that loads an existing flattenable object.
Class | `XMLFile` | An `ITemplateLoader` that loads and parses XML from a file.
Class | `XMLString` | An `ITemplateLoader` that loads and parses XML from a string.
Function | `flatten` | Incrementally write out a string representation of `root` using `write`.
Function | `flattenString` | Collate a string representation of `root` into a single string.
Function | `renderElement` | Render an element or other `IRenderable`.
Function | `renderer` | Decorate with `renderer` to use methods as template render directives.
Constant | `TEMPLATE_NAMESPACE` | Undocumented
Constant | `VALID_HTML_TAG_NAMES` | Undocumented
Type Alias | `Flattenable` | Type alias containing all types that can be flattened by `flatten()`.
Variable | `tags` | Undocumented

def flatten(request: `IRequest | None`, root: `Flattenable`, write: `Callable[[bytes], object]`) -> `Deferred[None]`: (source)

Incrementally write out a string representation of `root` using `write`.

In order to create a string representation, `root` will be decomposed into simpler objects which will themselves be decomposed and so on until strings or objects which can easily be converted to strings are encountered.

Parameters
request:`IRequest | None` | A request object which will be passed to the `render` method of any `IRenderable` provider which is encountered.
root:`Flattenable` | An object to be made flatter. This may be of type `str`, `bytes`, `slot`, `Tag`, `tuple`, `list`, `types.GeneratorType`, `Deferred`, or something that provides `IRenderable`.
write:`Callable[[bytes], object]` | A callable which will be invoked with each `bytes` produced by flattening `root`.

Returns
`Deferred[None]` | A `Deferred` which will be called back with `None` when `root` has been completely flattened into `write` or which will be errbacked if an unexpected exception occurs.

def flattenString(request: `IRequest | None`, root: `Flattenable`) -> `Deferred[bytes]`: (source)

Collate a string representation of `root` into a single string.

This is basically gluing `flatten` to an `io.BytesIO` and returning the results. See `flatten` for the exact meanings of `request` and `root`.

Returns
`Deferred[bytes]` | A `Deferred` which will be called back with a single UTF-8 encoded string as its result when `root` has been completely flattened or which will be errbacked if an unexpected exception occurs.

def renderElement(request: `IRequest`, element: `IRenderable`, doctype: `bytes | None` = b'<!DOCTYPE html>', _failElement: `Callable[[Failure], Element] | None` = None) -> `object`: (source)

Render an element or other `IRenderable`.

Parameters
request:`IRequest` | The `IRequest` being rendered to.
element:`IRenderable` | An `IRenderable` which will be rendered.
doctype:`bytes | None` | A `bytes` which will be written as the first line of the request, or `None` to disable writing of a doctype. The argument should not include a trailing newline and will default to the HTML5 doctype `'<!DOCTYPE html>'`.
_failElement:`Callable[[Failure], Element] | None` | Undocumented

Returns
`object` | NOT_DONE_YET

Present Since
12.1

@exposer
def renderer(): (source)

Decorate with `renderer` to use methods as template render directives.

For example:

        class Foo(Element):
            @renderer
            def twiddle(self, request, tag):
                return tag('Hello, world.')

        <div xmlns:t="http://twistedmatrix.com/ns/twisted.web.template/0.1">
            <span t:render="twiddle" />
        </div>

Will result in this final output:

        <div>
            <span>Hello, world.</span>
        </div>

TEMPLATE_NAMESPACE: `str` = (source)

Undocumented

Value

    'http://twistedmatrix.com/ns/twisted.web.template/0.1'

VALID_HTML_TAG_NAMES: `set[str]` = (source)

Undocumented

Value

    set(['a',
         'abbr',
         'acronym',
         'address',
         'applet',
         'area',
         'article',
    ...

Flattenable = (source)

Type alias containing all types that can be flattened by `flatten()`.

Value

    bytes | str | slot | CDATA | Comment | Tag | tuple[FlattenableRecursive, ...] | list↵
    [FlattenableRecursive] | Generator[FlattenableRecursive, None, None] | CharRef |↵
     Deferred[FlattenableRecursive] | Coroutine[Deferred[FlattenableRecursive],
                                                object,
                                                FlattenableRecursive] | IRenderable

tags = (source)

Undocumented