Go to the latest version of this document.

# ``twisted`.`web`.`_flatten``

module documentation
(source)

Context-free flattener/serializer for rendering Python objects, possibly complex or arbitrarily nested, as strings.

Function | `attributeEscapingDoneOutside` | Escape some character or UTF-8 byte data for inclusion in the top level of an attribute. `attributeEscapingDoneOutside` actually passes the data through unchanged, because `writeWithAttributeEscaping` handles the quoting of the text within attributes outside the generator returned by ...
Function | `escapedCDATA` | Escape CDATA for inclusion in a document.
Function | `escapedComment` | Within comments the sequence `-->` can be mistaken as the end of the comment. To ensure consistent parsing and valid output the sequence is replaced with `--&gt;`. Furthermore, whitespace is added when a comment ends in a dash...
Function | `escapeForContent` | Escape some character or UTF-8 byte data for inclusion in an HTML or XML document, by replacing metacharacters (`&<>`) with their entity equivalents (`&amp;&lt;&gt;`).
Function | `writeWithAttributeEscaping` | Decorate a `write` callable so that all output written is properly quoted for inclusion within an XML attribute value.
Constant | `BUFFER_SIZE` | Undocumented
Type Variable | `T` | Undocumented
Function | `_flattenElement` | Make `root` slightly more flat by yielding all its immediate contents as strings, deferreds or generators that are recursive calls to itself.
Async Function | `_flattenTree` | Make `root` into an iterable of `bytes` and `Deferred` by doing a depth first traversal of the tree.
Function | `_fork` | Create a new `Deferred` based on `d` that will fire and fail with `d`'s result or error, but will not modify `d`'s callback type.
Function | `_getSlotValue` | Find the value of the named slot in the given stack of slot data.

def attributeEscapingDoneOutside(data: `bytes | str`) -> `bytes`: (source)

Escape some character or UTF-8 byte data for inclusion in the top level of an attribute. `attributeEscapingDoneOutside` actually passes the data through unchanged, because `writeWithAttributeEscaping` handles the quoting of the text within attributes outside the generator returned by `_flattenElement`; this is used as the `dataEscaper` argument to that `_flattenElement` call so that that generator does not redundantly escape its text output.

Parameters
data:`bytes | str` | The string to escape.

Returns
`bytes` | The string, unchanged, except for encoding.

def escapedCDATA(data: `bytes | str`) -> `bytes`: (source)

Escape CDATA for inclusion in a document.

Parameters
data:`bytes | str` | The string to escape.

Returns
`bytes` | The quoted form of `data`. If `data` is unicode, return a utf-8 encoded string.

def escapedComment(data: `bytes | str`) -> `bytes`: (source)

Within comments the sequence `-->` can be mistaken as the end of the comment. To ensure consistent parsing and valid output the sequence is replaced with `--&gt;`. Furthermore, whitespace is added when a comment ends in a dash. This is done to break the connection of the ending `-` with the closing `-->`.

Parameters
data:`bytes | str` | The string to escape.

Returns
`bytes` | The quoted form of `data`. If `data` is unicode, return a utf-8 encoded string.

def escapeForContent(data: `bytes | str`) -> `bytes`: (source)

Escape some character or UTF-8 byte data for inclusion in an HTML or XML document, by replacing metacharacters (`&<>`) with their entity equivalents (`&amp;&lt;&gt;`).

This is used as an input to `_flattenElement`'s `dataEscaper` parameter.

Parameters
data:`bytes | str` | The string to escape.

Returns
`bytes` | The quoted form of `data`. If `data` is `str`, return a utf-8 encoded string.

def writeWithAttributeEscaping(write: `Callable[[bytes], object]`) -> `Callable[[bytes], None]`: (source)

Decorate a `write` callable so that all output written is properly quoted for inclusion within an XML attribute value.

If a `Tag` `x` is flattened within the context of the contents of another `Tag` `y`, the metacharacters (`<>&"`) delimiting `x` should be passed through unchanged, but the textual content of `x` should still be quoted, as usual. For example: `<y><x>&amp;</x></y>`. That is the default behavior of `_flattenElement` when `escapeForContent` is passed as the `dataEscaper`.

However, when a `Tag` `x` is flattened within the context of an attribute of another `Tag` `y`, then the metacharacters delimiting `x` should be quoted so that it can be parsed from the attribute's value. In the DOM itself, this is not a valid thing to do, but given that renderers and slots may be freely moved around in a `twisted.web.template` template, it is a condition which may arise in a document and must be handled in a way which produces valid output. So, for example, you should be able to get `<y attr="&lt;x /&gt;" />`. This should also be true for other XML/HTML meta-constructs such as comments and CDATA, so if you were to serialize a `comment` in an attribute you should get `<y attr="&lt;-- comment --&gt;" />`. Therefore in order to capture these meta-characters, flattening is done with `write` callable that is wrapped with `writeWithAttributeEscaping`.

The final case, and hopefully the much more common one as compared to serializing `Tag` and arbitrary `IRenderable` objects within an attribute, is to serialize a simple string, and those should be passed through for `writeWithAttributeEscaping` to quote without applying a second, redundant level of quoting.

Parameters
write:`Callable[[bytes], object]` | A callable which will be invoked with the escaped `bytes`.

Returns
`Callable[[bytes], None]` | A callable that writes data with escaping.

BUFFER_SIZE = (source)

Undocumented

Value

    2 ** 16

T = (source)

Undocumented

Value

    TypeVar('T')

def _flattenElement(request: `IRequest | None`, root: `Flattenable`, write: `Callable[[bytes], object]`, slotData: `list[Mapping[str, Flattenable] | None]`, renderFactory: `IRenderable | None`, dataEscaper: `Callable[[(bytes | str)], bytes]`) -> `Generator[Generator[Any, Any, Any] | Deferred[Flattenable], None, None]`: (source)

Make `root` slightly more flat by yielding all its immediate contents as strings, deferreds or generators that are recursive calls to itself.

Parameters
request:`IRequest | None` | A request object which will be passed to `IRenderable.render`.
root:`Flattenable` | An object to be made flatter. This may be of type `unicode`, `str`, `slot`, `Tag`, `tuple`, `list`, `types.GeneratorType`, `Deferred`, or an object that implements `IRenderable`.
write:`Callable[[bytes], object]` | A callable which will be invoked with each `bytes` produced by flattening `root`.
slotData:`list[Mapping[str, Flattenable] | None]` | A `list` of `dict` mapping `str` slot names to data with which those slots will be replaced.
renderFactory:`IRenderable | None` | If not `None`, an object that provides `IRenderable`.
dataEscaper:`Callable[[(bytes | str)], bytes]` | A 1-argument callable which takes `bytes` or `unicode` and returns `bytes`, quoted as appropriate for the rendering context. This is really only one of two values: `attributeEscapingDoneOutside` or `escapeForContent`, depending on whether the rendering context is within an attribute or not. See the explanation in `writeWithAttributeEscaping`.

Returns

`Generator[Generator[Any, Any, Any] | Deferred[Flattenable], None, None]`

An iterator that eventually writes `bytes` to `write`. It can yield other iterators or `Deferred`s; if it yields another iterator, the caller will iterate it; if it yields a `Deferred`, the result of that `Deferred` will be another generator, in which case it is iterated. See `_flattenTree` for the trampoline that consumes said values.

async def _flattenTree(request: `IRequest | None`, root: `Flattenable`, write: `Callable[[bytes], object]`): (source)

Make `root` into an iterable of `bytes` and `Deferred` by doing a depth first traversal of the tree.

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

Returns
A `Deferred`-returning coroutine that resolves to `None`.

def _fork(d: `Deferred[T]`) -> `Deferred[T]`: (source)

Create a new `Deferred` based on `d` that will fire and fail with `d`'s result or error, but will not modify `d`'s callback type.

def _getSlotValue(name: `str`, slotData: `Sequence[Mapping[str, Flattenable] | None]`, default: `Flattenable | None` = None) -> `Flattenable`: (source)

Find the value of the named slot in the given stack of slot data.