twisted.web.

module documentation

(source)

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

Function	`attributeEscapingDoneOutside`	No summary
Function	`escapedCDATA`	Escape CDATA for inclusion in a document.
Function	`escapedComment`	Escape a comment for inclusion in a document.
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 (`&<>`).
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	`writeWithAttributeEscaping`	Decorate a `write` callable so that all output written is properly quoted for inclusion within an XML attribute value.
Variable	`Flattenable`	Type alias containing all types that can be flattened by `flatten()`.
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): (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:`Union[bytes, str]`	The string to escape.
Returns
`bytes`	The string, unchanged, except for encoding.

def escapedCDATA(data): (source)

Escape CDATA for inclusion in a document.

Parameters
data:`Union[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): (source)

Escape a comment for inclusion in a document.

Parameters
data:`Union[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): (source)

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

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

Parameters
data:`Union[bytes, str]`	The string to escape.
Returns
`bytes`	The quoted form of `data`. If `data` is `str`, return a utf-8 encoded string.

def flatten(request, root, write): (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:`Optional[IRequest]`	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, root): (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.

Parameters
request:`Optional[IRequest]`	Undocumented
root:`Flattenable`	Undocumented
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 writeWithAttributeEscaping(write): (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>&</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="<x />" />. 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="<-- comment -->" />. 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.

Flattenable = (source)

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

T = (source)

Undocumented

def _flattenElement(request, root, write, slotData, renderFactory, dataEscaper): (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:`Optional[IRequest]`	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[Optional[Mapping[str, Flattenable]]]`	A `list` of `dict` mapping `str` slot names to data with which those slots will be replaced.
renderFactory:`Optional[IRenderable]`	If not `None`, an object that provides `IRenderable`.
dataEscaper:`Callable[[Union[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[Union[Generator, 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, root, write): (source)

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

Parameters
request:`Optional[IRequest]`	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): (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.

Parameters
d:`Deferred[T]`	Undocumented
Returns
`Deferred[T]`	Undocumented

def _getSlotValue(name, slotData, default=None): (source)

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

Parameters
name:`str`	Undocumented
slotData:`Sequence[Optional[Mapping[str, Flattenable]]]`	Undocumented
default:`Optional[Flattenable]`	Undocumented
Returns
`Flattenable`	Undocumented

twisted.web._flatten

`twisted.web._flatten`