twisted.web._flatten
module documentationtwisted.web
View Source
Context-free flattener/serializer for rendering Python objects, possibly complex or arbitrarily nested, as strings.
Function | iscoroutine | Undocumented |
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 | writeWithAttributeEscaping | Decorate a write callable so that all output written 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. |
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 ) |
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 | The string to escape. (type: bytes or unicode ) |
Returns | The string, unchanged, except for encoding. (type: bytes ) |
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 | A callable which will be invoked with the escaped bytes . |
Returns | A callable that writes data with escaping. |
Find the value of the named slot in the given stack of slot data.
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 ,
types.GeneratorType ,
Deferred ,
or an object that implements IRenderable . | |
write | A callable which will be invoked with each bytes
produced by flattening root . | |
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 writeWithAttributeEscaping . | |
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.) |
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 ,
types.GeneratorType ,
Deferred ,
or something providing IRenderable . | |
write | A callable which will be invoked with each bytes
produced by flattening root . | |
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. |
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 |