o

�
b�@�@s�dZd
dl
mZ
d
dlmZ
d
dlmZ
d
dlmZ
d
dl	m
Z

d
dlmZm
Z
mZmZmZmZmZmZmZmZmZmZ
d
dlmZmZ
d
d	lmZ
d
d
lmZ
d
dlm Z m!Z!m"Z"m#Z#m$Z$m%Z%
d
dl&m'Z'm(Z(m)Z)
d
d
l*m+Z+m,Z,
ed�
Z-eZ.	ee/e0e$e e"e#ee.dfee.ee.ddfe!ee.eee.e1e.fe+f
Z2	dee/e0fde/fdd�Z3dee/e0fde/fdd�Z4de
e/g
e1fde
e/g
dffdd�Z5dee/e0fde/fdd�Z6dee/e0fde/fdd�Z7	d2de0deeee0e2fd ee2de2fd!d"�Z8d#ee-dee-fd$d%�Z9d&ee,d'e2de
e/g
e1fdeeee0e2fd(ee+d)e
ee/e0fg
e/fdeeeee2fddffd*d+�Z:d&ee,d'e2de
e/g
e1fddfd,d-�Z;d&ee,d'e2de
e/g
e1fdedfd.d/�Z<d&ee,d'e2dee/fd0d1�Z=dS)3zu
Context-free flattener/serializer for rendering Python objects, possibly
complex or arbitrarily nested, as strings.
�)
�iscoroutine)
�BytesIO)
�exc_info)
�
extract_tb)
�
GeneratorType)�Any�Callable�	Coroutine�	Generator�List�Mapping�Optional�Sequence�Tuple�TypeVar�Union�cast)�Deferred�ensureDeferred)
�nativeString)
�Failure)�CDATA�CharRef�Comment�Tag�slot�voidElements)�FlattenerError�UnfilledSlot�UnsupportedType)�IRenderable�IRequest�
T.N�data�returnc

Cs4t|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{&amp;&lt;&gt;}).

    This is used as an input to L{_flattenElement}'s C{dataEscaper} parameter.

    @param data: The string to escape.

    @return: The quoted form of C{data}.  If C{data} is L{str}, return a utf-8
        encoded string.
    �utf-8�
&s&amp;�
<s&lt;�
>�&gt;��
isinstance�str�encode�replace�
r#�r0�6/usr/lib/python3/dist-packages/twisted/web/_flatten.py�escapeForContentCs




r2c

Cst|t
�r
|�d
�
S|S)aG
    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.

    @param data: The string to escape.

    @return: The string, unchanged, except for encoding.
    r%)r+r,r-r/r0r0r1�attributeEscapingDoneOutsideVs



r3�writec
sd
tddf�f
dd�}
|
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 <twisted.web.template.Tag>} C{x} is flattened within the context
    of the contents of another L{Tag <twisted.web.template.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{<y><x>&amp;</x></y>}.  That is the default behavior
    of L{_flattenElement} when L{escapeForContent} is passed as the
    C{dataEscaper}.

    However, when a L{Tag <twisted.web.template.Tag>} C{x} is flattened within
    the context of an I{attribute} of another L{Tag <twisted.web.template.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{<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 L{comment
    <twisted.web.template.Comment>} in an attribute you should get C{<y
    attr="&lt;-- comment --&gt;" />}.  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 <twisted.web.template.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.
    r#r$Nc

s�t|�
�
d
d��

dS)N�
"s&quot;)r2r.r/�
r4r0r1�_write�s
z*writeWithAttributeEscaping.<locals>._write)
�bytes)r4r7r0r6r1�writeWithAttributeEscapingis)r9c

Cs t|t
�r
|�d
�
}|�dd�S)z�
    Escape CDATA for inclusion in a document.

    @param data: The string to escape.

    @return: The quoted form of C{data}. If C{data} is unicode, return a utf-8
        encoded string.
    r%�]]>s]]]]><![CDATA[>r*r/r0r0r1�escapedCDATA�s
	


r;c

CsHt|t
�r
|�d
�
}|�dd��dd�}|r"|dd�dkr"|d	7}|S)
z�
    Escape a comment for inclusion in a document.

    @param data: The string to escape.

    @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/r0r0r1�escapedComment�s
	





r?�name�slotData�defaultcCsD|
d
d
d�D]}|d
u
r||vr||
Sq|d
u
r|St|�
�
)zK
    Find the value of the named slot in the given stack of slot data.
    Nr<)
r)r@rArB�	slotFramer0r0r1�
_getSlotValue�s

�

rD�
dc
sLt�f
d
d��
�
dt
dt
f�
f
dd�}
dtdtf�
f
dd	�}��|
|�
�
S)
z�
    Create a new L{Deferred} based on C{d} that will fire and fail with C{d}'s
    result or error, but will not modify C{d}'s callback type.
    c

����S�
N)
�cancel�
�
_)
rEr0r1�<lambda>��z_fork.<locals>.<lambda>�resultr$c

���|�

|SrG)
�callback�
rM�
�d2r0r1rO��


z_fork.<locals>.callback�failurec

rNrG)
�errback)
rTrQr0r1rU�rSz_fork.<locals>.errback)rr"r�addCallbacks)rErOrUr0)rErRr1�_fork�s

rW�request�root�
renderFactory�dataEscaperc#sV�|||fd
tdt
tttfg
tfdttdt
tg
tfdtttt	tfddff
�
�fdd�
�d	t	tdt	tf�f
d
d�}t
|
ttf�rP|||
�
�

dSt
|
t�rdt|
j
�|
j�}�|�
V
dSt
|
t�rz|d�

|t|
j�
�

|d
�

dSt
|
t�r�|d�

|t|
j�
�

|d�

dSt
|
t��
r@��|
j�

|
j}|du
r�|dur�td|�d��
�
|
�d�
}	d|	_|�|�
}
|
�
|	�}�|�
V
���
dS|
js׈|
j�
V
dS|d�

t
|
jt�r�|
j�d�
}n|
j}||�

|
j� �D]%\}
}t
|
t��
r|
�d�
}
|d|
d�

�|t!t"|�
d�V
|d�

q�|
j�
s%t#|�
t$v
�
r:|d�

�|
jt%�V
|d|d�

dS|d�

dSt
|
t&t't(f��
rV|
D]}�|�
V
�
qKdSt
|
t)��
rkd|
j*f
}||�d�
�

dSt
|
t	��
rz|t+|
�
�
V
dSt,|
�
�
r�|t	�-t.t/t	tttf|
��
�
V
dSt�0|
�
�
r�|
��
�
}�||
d�V
dSt1|
�
�
)at
    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 <twisted.web.template.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 writes L{bytes} to C{write}.
        It can 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 be another generator, in which
        case it is iterated.  See L{_flattenTree} for the trampoline that
        consumes said values.
    �newRootr[rZr4r$Ncst�||�
||
�SrG)
�_flattenElement)r\r[rZr4)rXrAr0r1�	keepGoing

s
�z"_flattenElement.<locals>.keepGoingrMc

s
|���
SrG)
�addCallbackrP)
r^r0r1�keepGoingAsync
s

z'_flattenElement.<locals>.keepGoingAsyncs	<![CDATA[r:s<!--s-->z$Tag wants to be rendered by method "z)" but is not contained in any IRenderableFr'�asciir>s="r6r5r(s</s />z&#%d;)
rZ)2�Flattenablerrr8r,r
r �objectr
rr+rrDr@rBrr;r#rr?r�appendrA�render�
ValueError�clone�lookupRenderMethod�pop�tagName�childrenr-�
attributes�itemsr3r9rrr2�tuple�listrr�ordinalrWr�
fromCoroutinerr	�
providedByr)rXrYr4rArZr[r`�	slotValue�rendererName�	rootClone�renderMethodrMrj�
k�
v�element�escapedr0)r^rXrAr1r]�s��1

�
�����























�





















�





�








�
�


r]c	
�s��
t||
|gd
t
�g
}|rmz|dj}t|d�
}t|t�r#|Id
H}Wn?ty1


|��
Yn8tyc
}
z'|��
g}|D]}|�	|jj
d�

q@|�	|j
d�

t||tt
�d�
��
d
}~w
w|�	|�

|s
d
Sd
S)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 <twisted.web.template.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: A C{Deferred}-returning coroutine that resolves to C{None}.
    Nr<rY�)r]r2�gi_frame�nextr+r�
StopIterationri�	Exceptionrd�f_localsrrr)	rXrYr4�stack�framery�
e�roots�	generatorr0r0r1�_flattenTreel
s.��







�








��
�r�cCstt
||
|��
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{str},
        L{bytes}, L{slot}, L{Tag <twisted.web.template.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 with C{None} when C{root}
        has been completely flattened into C{write} or which will be errbacked
        if an unexpected exception occurs.
    )rr�)rXrYr4r0r0r1�flatten�
sr�cs4t��t
||
�j�}|��f
d
d��

ttt|�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 UTF-8 encoded
        string as its result when C{root} has been completely flattened or which
        will be errbacked if an unexpected exception occurs.
    c

rFrG)
�getvaluerI�
�ior0r1rK�
rLzflattenString.<locals>.<lambda>)rr�r4r_rrr8)rXrYrEr0r�r1�
flattenString�
s


r�rG)>�__doc__�inspectrr�r�sysr�	tracebackr�typesr�typingrrr	r
rrr
rrrrr�twisted.internet.deferrr�twisted.python.compatr�twisted.python.failurer�twisted.web._stanrrrrrr�twisted.web.errorrrr�twisted.web.iwebr r!r"�FlattenableRecursiver8r,rcrbr2r3r9r;r?rDrWr]r�r�r�r0r0r0r1�<module>
s�



8


 

















��
�
�/�
���
�
������

�
�
�
�
�*
�
�
�
�"