U ljF@sdZddlmZddlmZddlmZddlmZddl m Z ddl m Z ddl mZmZmZmZmZmZmZmZmZmZmZmZdd lmZmZdd lmZdd lm Z dd l!m"Z"m#Z#m$Z$m%Z%m&Z&m'Z'dd l(m)Z)m*Z*m+Z+ddl,m-Z-m.Z.edZ/eZ0ee1e2e&e"e$e%ee0dfee0ee0ddfe#ee0eee0e3e0fe-f Z4dZ5dddddZ6dddddZ7dddddZ8ddddd Z9dddd!d"Z:dAd#d$d%d&d'd(d)Z;d*d*d+d,d-Zd.d&dd:d7d;d<Z?d.d&d=d>d?d@Z@dS)Bzu Context-free flattener/serializer for rendering Python objects, possibly complex or arbitrarily nested, as strings. ) annotations) iscoroutine)BytesIO)exc_info) extract_tb) GeneratorType) AnyCallable Coroutine GeneratorListMappingOptionalSequenceTupleTypeVarUnioncast)DeferredensureDeferred) nativeString)Failure)CDATACharRefCommentTagslot voidElements)FlattenerError UnfilledSlotUnsupportedType) IRenderableIRequestT.NizUnion[bytes, str]bytesdatareturncCs4t|tr|d}|dddddd}|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. @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&s> isinstancestrencodereplacer&r28/tmp/pip-unpacked-wheel-aghyhbke/twisted/web/_flatten.pyescapeForContentGs  r4cCst|tr|dS|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/r1r2r2r3attributeEscapingDoneOutsideZs  r5Callable[[bytes], object]zCallable[[bytes], None])writer'csdddfdd }|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. r$Noner%cst|dddS)N"s")r4r0r1r7r2r3_writesz*writeWithAttributeEscaping.._writer2)r7r;r2r:r3writeWithAttributeEscapingms)r<cCs t|tr|d}|ddS)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]]]]>r,r1r2r2r3 escapedCDATAs  r>cCs@t|tr|d}|dd}|r<|dddkr<|d7}|S)a Within comments the sequence C{-->} can be mistaken as the end of the comment. To ensure consistent parsing and valid output the sequence is replaced with C{-->}. Furthermore, whitespace is added when a comment ends in a dash. This is done to break the connection of the ending C{-} with the closing C{-->}. @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-->N- r,r1r2r2r3escapedComments   rCr.z-Sequence[Optional[Mapping[str, Flattenable]]]zOptional[Flattenable] Flattenable)nameslotDatadefaultr'cCsBt|D] }|dk r||kr||Sq|dk r6|St|dS)zK Find the value of the named slot in the given stack of slot data. N)reversedr)rErFrGZ slotFramer2r2r3 _getSlotValues  rIz Deferred[T])dr'csHtfdddddfdd }dddfd d }||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. csSN)cancel_)rJr2r3z_fork..r#resultr'cs||SrK)callbackrRd2r2r3rSs z_fork..callbackr)failurer'cs||SrK)errback)rWrUr2r3rXs z_fork..errback)rZ addCallbacks)rJrSrXr2)rJrVr3_forks  rYzOptional[IRequest]z)List[Optional[Mapping[str, Flattenable]]]Optional[IRenderable]$Callable[[Union[bytes, str]], bytes]zMGenerator[Union[Generator[Any, Any, Any], Deferred[Flattenable]], None, None])requestrootr7rF renderFactory dataEscaperr'c#s |||fddddddfdd d d d fd d }t|ttfrV|||nt|tr~t|j|j}|Vnt|tr|d |t|j |dn^t|t r|d|t |j |dn2t|t r< |j|j}|dk rR|dkrtd|d|d} d| _||} | | } | VdS|jsj|jVdS|dt|jtr|jd} n|j} || |jD]L\} }t| tr| d} |d| d|tt|dV|dq|js t| tkr2|d|jtV|d| dn|dnt|ttt frf|D]}|VqRnt|t!rd|j"f}||dnzt|t#r|t$|Vn^t%|r|t#&t't(t#t)t*t)f|Vn.t+,|r|} | |dVnt-|dS) 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 }, 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. rDr[rZr6z@Generator[Union[Flattenable, Deferred[Flattenable]], None, None])newRootr_r^r7r'cst||||SrK)_flattenElement)r`r_r^r7)r\rFr2r3 keepGoingsz"_flattenElement..keepGoingzDeferred[Flattenable]rQcs |SrK) addCallbackrT)rbr2r3keepGoingAsyncsz'_flattenElement..keepGoingAsyncs z&#%d;)r^).r-r$r.rrIrErGrr>r&rrCrappendrFrender ValueErrorcloneZlookupRenderMethodpoptagNamechildrenr/ attributesitemsr5r<rrr4tuplelistrrZordinalrrYrZ fromCoroutinerr rDobjectr!Z providedByr )r\r]r7rFr^r_rdZ slotValueZ rendererNameZ rootCloneZ renderMethodrRrkkvelementescapedr2)rbr\rFr3ras1                          rar8)r\r]r7r'c sgddddfdd }ddfdd t|||gd tg}|r z*t|d }t|trx|Id H}Wntk r|YqJtk r}zLg}|D] }|jd k r| |jj d q|t ||t t d W5d }~XYqJX| |qJd 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 }, 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}. rr$r8)bsr'cs(|t|7tkr$dSrK)rflen BUFFER_SIZE)rv)bufbufSize flushBufferr2r3 bufferedWrites  z#_flattenTree..bufferedWrite)r'cs(dkr$ddd=ddS)NrrP)joinr2)ryrzr7r2r3r{s z!_flattenTree..flushBufferNr@r])rar4nextr-r StopIterationrj Exceptiongi_framerff_localsrrr) r\r]r7r|stackrteroots generatorr2)ryrzr{r7r3 _flattenTreess.     ( rzDeferred[None]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 }, 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)r\r]r7r2r2r3flattensrzDeferred[bytes])r\r]r'cs4tt||j}|fddttt|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. csSrK)getvaluerMior2r3rOrPzflattenString..)rrr7rcrrr$)r\r]rJr2rr3 flattenStrings r)N)A__doc__ __future__rinspectrrrsysr tracebackrtypesrtypingrr r r r r rrrrrrZtwisted.internet.deferrrZtwisted.python.compatrZtwisted.python.failurerZtwisted.web._stanrrrrrrZtwisted.web.errorrrr Ztwisted.web.iwebr!r"r#ZFlattenableRecursiver$r.rqrDrxr4r5r<r>rCrIrYrarrrr2r2r2r3sZ      8     /H