t.w._flatten : module documentation

Part of twisted.web View Source

Context-free flattener/serializer for rendering Python objects, possibly complex or arbitrarily nested, as strings.
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 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.
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 (&amp;&lt;&gt;).

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

ParametersdataThe string to escape. (type: bytes or unicode)
ReturnsThe 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.
ParametersdataThe string to escape. (type: bytes or unicode)
ReturnsThe 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>&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, 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.

ParametersrootA value that may be yielded by _flattenElement; either an iterable yielding bytes (or more iterables), or bytes itself. (type: bytes or iterable)
ReturnsThe 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.
ParametersdataThe string to escape. (type: str or unicode)
ReturnsThe 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.
ParametersdataThe string to escape. (type: str or unicode)
ReturnsThe 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.
ParametersrequestA request object which will be passed to IRenderable.render.
rootAn object to be made flatter. This may be of type unicode, str, slot, Tag, URL, tuple, list, GeneratorType, Deferred, or an object that implements IRenderable.
slotDataA list of dict mapping str slot names to data with which those slots will be replaced.
renderFactoryIf not None, an object that provides IRenderable.
dataEscaperA 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.
ReturnsAn iterator that eventually yields bytes that should be written to the output. However it may also yield other iterators or Deferreds; 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.
ParametersrequestA request object which will be passed to IRenderable.render.
rootAn object to be made flatter. This may be of type unicode, bytes, slot, Tag, tuple, list, GeneratorType, Deferred, or something providing IRenderable.
ReturnsAn 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.
ParametersstateAn iterator of str and Deferred. str instances will be passed to write. Deferred instances will be waited on before resuming iteration of state.
writeA callable which will be invoked with each str produced by iterating state.
resultA 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.
ReturnsNone
API Documentation for Twisted, generated by pydoctor at 2014-05-12 18:27:00.