twisted.web._flatten : API documentation

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	The string to escape. (type: `bytes` or `unicode`)
Returns	The quoted form of `data`. If `data` is unicode, return a utf-8 encoded string. (type: `bytes`)

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 flattenWithAttributeEscaping 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	The string to escape. (type: `bytes` or `unicode`)
Returns	The string, unchanged, except for encoding. (type: `bytes`)

def flattenWithAttributeEscaping(root): (source)

Decorate the generator returned by _flattenElement so that its output 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, the attribute generator from _flattenElement context is wrapped with an flattenWithAttributeEscaping.

Because all characters serialized in the context of an attribute are quoted before they are yielded by the generator returned by flattenWithAttributeEscaping, on the "outside" of the _flattenElement call, the _flattenElement generator therefore no longer needs to quote text that appears directly within the attribute itself.

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 flattenWithAttributeEscaping to quote without applying a second, redundant level of quoting.

Parameters	root	A value that may be yielded by `_flattenElement`; either an iterable yielding `bytes` (or more iterables), or bytes itself. (type: `bytes` or `iterable`)
Returns	The same type as `_flattenElement` returns, with all the bytes encoded for representation within an attribute. (type: the same type as the `subFlatten` argument)

def escapedCDATA(data): (source)

Escape CDATA for inclusion in a document.

Parameters	data	The string to escape. (type: `str` or `unicode`)
Returns	The quoted form of `data`. If `data` is unicode, return a utf-8 encoded string. (type: `str`)

def escapedComment(data): (source)

Escape a comment for inclusion in a document.

Parameters	data	The string to escape. (type: `str` or `unicode`)
Returns	The quoted form of `data`. If `data` is unicode, return a utf-8 encoded string. (type: `str`)

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

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

def _flattenElement(request, root, 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	A request object which will be passed to `IRenderable.render`.
	root	An object to be made flatter. This may be of type `unicode`, `str`, `slot`, `Tag`, `tuple`, `list`, `GeneratorType`, `Deferred`, or an object that implements `IRenderable`.
	slotData	A `list` of `dict` mapping `str` slot names to data with which those slots will be replaced.
	renderFactory	If not `None`, an object that provides `IRenderable`.
	dataEscaper	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 `flattenWithAttributeEscaping`.
Returns	An iterator that eventually yields `bytes` that should be written to the output. However it may also 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 either be `bytes`, in which case it's written, or another generator, in which case it is iterated. See `_flattenTree` for the trampoline that consumes said values. (type: An iterator which yields `bytes`, `Deferred`, and more iterators of the same type.)

def _flattenTree(request, root): (source)

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

Parameters	request	A request object which will be passed to `IRenderable.render`.
	root	An object to be made flatter. This may be of type `unicode`, `bytes`, `slot`, `Tag`, `tuple`, `list`, `GeneratorType`, `Deferred`, or something providing `IRenderable`.
Returns	An iterator which yields objects of type `bytes` and `Deferred`. A `Deferred` is only yielded when one is encountered in the process of flattening `root`. The returned iterator must not be iterated again until the `Deferred` is called back.

def _writeFlattenedData(state, write, result): (source)

Take strings from an iterator and pass them to a writer function.

Parameters	state	An iterator of `str` and `Deferred`. `str` instances will be passed to `write`. `Deferred` instances will be waited on before resuming iteration of `state`.
	write	A callable which will be invoked with each `str` produced by iterating `state`.
	result	A `Deferred` which will be called back when `state` has been completely flattened into `write` or which will be errbacked if an exception in a generator passed to `state` or an errback from a `Deferred` from state occurs.
Returns	`None`

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	attributeEscapingDoneOutside	No summary
Function	flattenWithAttributeEscaping	Decorate the generator returned by `_flattenElement` so that its output is properly quoted for inclusion within an XML attribute value.
Function	escapedCDATA	Escape CDATA for inclusion in a document.
Function	escapedComment	Escape a comment for inclusion in a document.
Function	_getSlotValue	Find the value of the named slot in the given stack of slot data.
Function	_flattenElement	Make `root` slightly more flat by yielding all its immediate contents as strings, deferreds or generators that are recursive calls to itself.
Function	_flattenTree	Make `root` into an iterable of `bytes` and `Deferred` by doing a depth first traversal of the tree.
Function	_writeFlattenedData	Take strings from an iterator and pass them to a writer function.

twisted.web._flatten module documentation

`twisted.web._flatten` module documentation