U
¹êW[(> ã @ s4 d Z ddlmZmZ ddlmZ ddlmZ ddlm Z ddl
m Z zddl m
Z
W n ek
rp dd „ Z
Y nX dd
lmZmZmZ dd lmZmZ dd lmZmZmZmZmZm Z dd
l m Z m Z m Z ddl!m"Z" dd„ Z#dd„ Z$dd„ Z%dd„ Z&dd„ Z'd&dd„Z(d d „ Z)d d „ Z*d d!„ Z+d"d#„ Z,d$d%„ Z-dS )'zu
Context-free flattener/serializer for rendering Python objects, possibly
complex or arbitrarily nested, as strings.
é )ÚdivisionÚabsolute_import)ÚBytesIO)Úexc_info)Ú
GeneratorType)Ú
extract_tb)Ú iscoroutinec O s dS )NF© )ÚargsÚkwargsr r ú6/usr/lib/python3/dist-packages/twisted/web/_flatten.pyr s r )ÚunicodeÚ nativeStringÚ iteritems)ÚDeferredÚensureDeferred)ÚTagÚslotÚ voidElementsÚCommentÚCDATAÚCharRef)Ú UnfilledSlotÚUnsupportedTypeÚFlattenerError)Ú IRenderablec C s4 t | tƒr| d¡} | dd¡ dd¡ dd¡} | S )aØ
Escape some character or UTF-8 byte data for inclusion in an HTML or XML
document, by replacing metacharacters (C{&<>}) with their entity
equivalents (C{&<>}).
This is used as an input to L{_flattenElement}'s C{dataEscaper} parameter.
@type data: C{bytes} or C{unicode}
@param data: The string to escape.
@rtype: C{bytes}
@return: The quoted form of C{data}. If C{data} is unicode, return a utf-8
encoded string.
úutf-8ó &s &ó ó >©Ú
isinstancer
ÚencodeÚreplace©Údatar r r ÚescapeForContent s
ÿ þr' c C s t | tƒr| d¡S | S )aƒ
Escape some character or UTF-8 byte data for inclusion in the top level of
an attribute. L{attributeEscapingDoneOutside} actually passes the data
through unchanged, because L{writeWithAttributeEscaping} handles the
quoting of the text within attributes outside the generator returned by
L{_flattenElement}; this is used as the C{dataEscaper} argument to that
L{_flattenElement} call so that that generator does not redundantly escape
its text output.
@type data: C{bytes} or C{unicode}
@param data: The string to escape.
@return: The string, unchanged, except for encoding.
@rtype: C{bytes}
r )r" r
r# r% r r r Ú attributeEscapingDoneOutside8 s
r( c s ‡ fdd„}|S )aU
Decorate a C{write} callable so that all output written is properly quoted
for inclusion within an XML attribute value.
If a L{Tag } C{x} is flattened within the context
of the contents of another L{Tag } C{y}, the
metacharacters (C{<>&"}) delimiting C{x} should be passed through
unchanged, but the textual content of C{x} should still be quoted, as
usual. For example: C{&}. That is the default behavior
of L{_flattenElement} when L{escapeForContent} is passed as the
C{dataEscaper}.
However, when a L{Tag } C{x} is flattened within
the context of an I{attribute} of another L{Tag }
C{y}, then the metacharacters delimiting C{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 L{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 C{}. This should also be true for other XML/HTML meta-constructs such as
comments and CDATA, so if you were to serialize a L{comment
} in an attribute you should get C{}. Therefore in order to capture these
meta-characters, flattening is done with C{write} callable that is wrapped
with L{writeWithAttributeEscaping}.
The final case, and hopefully the much more common one as compared to
serializing L{Tag } and arbitrary L{IRenderable}
objects within an attribute, is to serialize a simple string, and those
should be passed through for L{writeWithAttributeEscaping} to quote
without applying a second, redundant level of quoting.
@param write: A callable which will be invoked with the escaped L{bytes}.
@return: A callable that writes data with escaping.
c s ˆ t | ƒ dd¡ƒ d S )Nó "s ")r' r$ r% ©Úwriter r Ú_writet s z*writeWithAttributeEscaping.._writer )r+ r, r r* r ÚwriteWithAttributeEscapingN s & r- c C s t | tƒr| d¡} | dd¡S )zû
Escape CDATA for inclusion in a document.
@type data: L{str} or L{unicode}
@param data: The string to escape.
@rtype: L{str}
@return: The quoted form of C{data}. If C{data} is unicode, return a utf-8
encoded string.
r ó ]]>s ]]]]>r! r% r r r Ú escapedCDATAz s
r/ c C sH t | tƒr| d¡} | dd¡ dd¡} | rD| dd… dkrD| d 7 } | S )
zÿ
Escape a comment for inclusion in a document.
@type data: L{str} or L{unicode}
@param data: The string to escape.
@rtype: C{str}
@return: The quoted form of C{data}. If C{data} is unicode, return a utf-8
encoded string.
r s --s - - r r éÿÿÿÿNó -ó r! r% r r r ÚescapedComment‹ s
r3 Nc C sH |ddd… D ] }|dk r| |kr|| S q|dk r<|S t | ƒ‚dS )zK
Find the value of the named slot in the given stack of slot data.
Nr0 )r )ÚnameÚslotDataÚdefaultZ slotFramer r r Ú
_getSlotValueŸ s r7 c # sÐ |||f‡‡fdd„ ‰ t |ttfƒr4|||ƒƒ n˜t |tƒr\t|jˆ|jƒ}ˆ |ƒV npt |tƒrˆ|dƒ |t|j ƒƒ |dƒ nDt |t
ƒr´|dƒ |t |j ƒƒ |dƒ nt |t ƒrˆ
|j¡ |jdk r|j}| d¡}d|_| |¡} | ˆ|ƒ}
ˆ |
ƒV ˆ ¡ dS |js0ˆ |jƒV dS |d ƒ t |jtƒrT|j d
¡} n|j} || ƒ t|jƒD ]L\} }
t | tƒrŠ| d
¡} |d | d ƒ ˆ |
tt|ƒd
V |dƒ ql|jsÐt| ƒtkrø|dƒ ˆ |jt ƒV |d| d ƒ n|dƒ nÊt |t t t fƒr,|D ]}ˆ |ƒV qn t |t ƒrTd|j!f }|| d
¡ƒ nxt |t"ƒrv| #‡ fdd„¡V nVt$|ƒržt%|ƒ}| #‡ fdd„¡V n.t& '|¡rÄ| ˆ¡}
ˆ |
|dV nt(|ƒ‚dS )a<
Make C{root} slightly more flat by yielding all its immediate contents as
strings, deferreds or generators that are recursive calls to itself.
@param request: A request object which will be passed to
L{IRenderable.render}.
@param root: An object to be made flatter. This may be of type C{unicode},
L{str}, L{slot}, L{Tag }, L{tuple}, L{list},
L{types.GeneratorType}, L{Deferred}, or an object that implements
L{IRenderable}.
@param write: A callable which will be invoked with each L{bytes} produced
by flattening C{root}.
@param slotData: A L{list} of L{dict} mapping L{str} slot names to data
with which those slots will be replaced.
@param renderFactory: If not L{None}, an object that provides
L{IRenderable}.
@param dataEscaper: A 1-argument callable which takes L{bytes} or
L{unicode} and returns L{bytes}, quoted as appropriate for the
rendering context. This is really only one of two values:
L{attributeEscapingDoneOutside} or L{escapeForContent}, depending on
whether the rendering context is within an attribute or not. See the
explanation in L{writeWithAttributeEscaping}.
@return: An iterator that eventually yields L{bytes} that should be written
to the output. However it may also yield other iterators or
L{Deferred}s; if it yields another iterator, the caller will iterate
it; if it yields a L{Deferred}, the result of that L{Deferred} will
either be L{bytes}, in which case it's written, or another generator,
in which case it is iterated. See L{_flattenTree} for the trampoline
that consumes said values.
@rtype: An iterator which yields L{bytes}, L{Deferred}, and more iterators
of the same type.
c s t ˆ | |ˆ||ƒS ©N)Ú_flattenElement)ZnewRootÚ dataEscaperÚ
renderFactoryr+ )Úrequestr5 r r Ú keepGoingÕ s
ÿz"_flattenElement..keepGoings NFr Úasciir2 s ="r* r) r s z&#%d;c s | ˆ | ƒfS r8 r ©Úresult©r= r r Ú ó z!_flattenElement..c s | ˆ | ƒfS r8 r r? rA r r rB rC )r; ))r" Úbytesr
r r7 r4 r6 r r/ r& r r3 r Úappendr5 ZrenderZcloneZlookupRenderMethodÚpopÚtagNameZchildrenr# r Z
attributesr( r- r r r' ÚtupleÚlistr r Zordinalr Ú addCallbackr r r Z
providedByr )r< Úrootr+ r5 r; r: Z slotValueZ rendererNameZ rootCloneZ renderMethodr@ rG ÚkÚvÚelementZescapedÚdr )r= r< r5 r r9 s„ ( ÿ
ý
r9 c
# sò t | ||g dtƒg‰ ˆ rîzˆ d j}tˆ d ƒ}W nŠ tk
rN ˆ ¡ Y q tk
r¼ } zRˆ ¡ g }ˆ D ]}| |jjd ¡ qn| |jd ¡ t ||t
t ƒ d ƒƒ‚W 5 d}~X Y qX t |t
ƒr⇠fdd„}| |¡V qˆ |¡ qdS )a\
Make C{root} into an iterable of L{bytes} and L{Deferred} by doing a depth
first traversal of the tree.
@param request: A request object which will be passed to
L{IRenderable.render}.
@param root: An object to be made flatter. This may be of type C{unicode},
L{bytes}, L{slot}, L{Tag }, L{tuple},
L{list}, L{types.GeneratorType}, L{Deferred}, or something providing
L{IRenderable}.
@param write: A callable which will be invoked with each L{bytes} produced
by flattening C{root}.
@return: An iterator which yields objects of type L{bytes} and L{Deferred}.
A L{Deferred} is only yielded when one is encountered in the process of
flattening C{root}. The returned iterator must not be iterated again
until the L{Deferred} is called back.
Nr0 rK é c s | \}}ˆ |¡ |S r8 )rE )ZoriginalAndToFlattenÚoriginalZ toFlatten©Ústackr r ÚcbxM s
z_flattenTree..cbx)r9 r' Úgi_frameÚnextÚ
StopIterationrF Ú ExceptionrE Úf_localsr r r r" r rJ ) r< rK r+ ÚframerN ÚeÚrootsÚ generatorrT r rR r Ú _flattenTree( s$
(
r^ c sd z t ˆƒ}W n0 tk
r* ˆ d¡ Y q` ˆ ¡ Y q`X ‡ ‡‡fdd„}| |ˆ j¡ q`q dS )a¥
Take strings from an iterator and pass them to a writer function.
@param state: An iterator of L{str} and L{Deferred}. L{str} instances will
be passed to C{write}. L{Deferred} instances will be waited on before
resuming iteration of C{state}.
@param write: A callable which will be invoked with each L{str}
produced by iterating C{state}.
@param result: A L{Deferred} which will be called back when C{state} has
been completely flattened into C{write} or which will be errbacked if
an exception in a generator passed to C{state} or an errback from a
L{Deferred} from state occurs.
@return: L{None}
Nc s t ˆˆˆ ƒ | S r8 )Ú_writeFlattenedData)rQ ©r@ Ústater+ r r Úcbyp s z _writeFlattenedData..cby)rV rW ÚcallbackZerrbackZ addCallbacks)ra r+ r@ rN rb r r` r r_ V s r_ c C s" t ƒ }t| ||ƒ}t|||ƒ |S )aü
Incrementally write out a string representation of C{root} using C{write}.
In order to create a string representation, C{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.
@param request: A request object which will be passed to the C{render}
method of any L{IRenderable} provider which is encountered.
@param root: An object to be made flatter. This may be of type L{unicode},
L{bytes}, L{slot}, L{Tag }, L{tuple},
L{list}, L{types.GeneratorType}, L{Deferred}, or something that provides
L{IRenderable}.
@param write: A callable which will be invoked with each L{bytes} produced
by flattening C{root}.
@return: A L{Deferred} which will be called back when C{root} has been
completely flattened into C{write} or which will be errbacked if an
unexpected exception occurs.
)r r^ r_ )r< rK r+ r@ ra r r r Úflattenx s rd c s* t ƒ ‰ t| |ˆ jƒ}| ‡ fdd„¡ |S )aË
Collate a string representation of C{root} into a single string.
This is basically gluing L{flatten} to an L{io.BytesIO} and returning
the results. See L{flatten} for the exact meanings of C{request} and
C{root}.
@return: A L{Deferred} which will be called back with a single string as
its result when C{root} has been completely flattened into C{write} or
which will be errbacked if an unexpected exception occurs.
c s ˆ ¡ S r8 )Úgetvalue)Ú_©Úior r rB ¤ rC z flattenString..)r rd r+ rJ )r< rK rO r rg r Ú
flattenString– s ri )N).Ú__doc__Z
__future__r r rh r Úsysr Útypesr Ú tracebackr Úinspectr Ú ImportErrorZtwisted.python.compatr
r r Ztwisted.internet.deferr r Ztwisted.web._stanr r r r r r Ztwisted.web.errorr r r Ztwisted.web.iwebr r' r( r- r/ r3 r7 r9 r^ r_ rd ri r r r r Ú s2 ,
{."