Go to the latest version of this document.
search in docstrings

Search bar offers the following options:

- Term presence. The below example searches for documents that must contain “foo”, might contain “bar” and must not contain “baz”: `+foo bar -baz`
- Wildcards. The below example searches for documents with words beginning with “foo”: `foo*`
- Search in specific fields. The following search matches all objects in "twisted.mail" that matches “search”: `+qname:twisted.mail.* +search`

  Possible fields: 'name', 'qname' (fully qualified name), 'docstring', and 'kind'. Last two fields are only applicable if "search in docstrings" is enabled.

- Fuzzy matches. The following search matches all documents that have a word within 1 edit distance of “foo”: `foo~1`

Results provided by Lunr.js

# ``twisted`.`web`.`_flatten``

module documentation
(source)

Context-free flattener/serializer for rendering Python objects, possibly complex or arbitrarily nested, as strings.

Function | `attributeEscapingDoneOutside` | 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 ...
Function | `escapedCDATA` | Escape CDATA for inclusion in a document.
Function | `escapedComment` | Escape a comment for inclusion in a document.
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 | `writeWithAttributeEscaping` | Decorate a `write` callable so that all output written is properly quoted for inclusion within an XML attribute value.
Type Variable | `T` | For documentation purposes, read `FlattenableRecursive` as `Flattenable`. However, since mypy doesn't support recursive type definitions (yet?), we'll put Any in the actual definition.
Function | `_flattenElement` | Make `root` slightly more flat by yielding all its immediate contents as strings, deferreds or generators that are recursive calls to itself.
Async Function | `_flattenTree` | Make `root` into an iterable of `bytes` and `Deferred` by doing a depth first traversal of the tree.
Function | `_fork` | Create a new `Deferred` based on `d` that will fire and fail with `d`'s result or error, but will not modify `d`'s callback type.
Function | `_getSlotValue` | Find the value of the named slot in the given stack of slot data.

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 `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:`Union[bytes, str]` | The string to escape.
Returns
`bytes` | The string, unchanged, except for encoding.

def escapedCDATA(data): (source)

Escape CDATA for inclusion in a document.

Parameters
data:`Union[bytes, str]` | The string to escape.
Returns
`bytes` | The quoted form of `data`. If `data` is unicode, return a utf-8 encoded string.

def escapedComment(data): (source)

Escape a comment for inclusion in a document.

Parameters
data:`Union[bytes, str]` | The string to escape.
Returns
`bytes` | The quoted form of `data`. If `data` is unicode, return a utf-8 encoded string.

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.

Parameters
data:`Union[bytes, str]` | The string to escape.
Returns
`bytes` | The quoted form of `data`. If `data` is `str`, return a utf-8 encoded string.

def writeWithAttributeEscaping(write): (source)

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>&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, 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:`Callable[[bytes], object]` | A callable which will be invoked with the escaped `bytes`.
Returns
`Callable[[bytes], None]` | A callable that writes data with escaping.

T = (source)

For documentation purposes, read `FlattenableRecursive` as `Flattenable`. However, since mypy doesn't support recursive type definitions (yet?), we'll put Any in the actual definition.

Value

    TypeVar('T')

def _flattenElement(request, root, write, 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.

Parameters
request:`Optional[IRequest]` | A request object which will be passed to `IRenderable.render`.
root:`Flattenable` | 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:`Callable[[bytes], object]` | A callable which will be invoked with each `bytes` produced by flattening `root`.
slotData:`List[Optional[Mapping[str, Flattenable]]]` | A `list` of `dict` mapping `str` slot names to data with which those slots will be replaced.
renderFactory:`Optional[IRenderable]` | If not `None`, an object that provides `IRenderable`.
dataEscaper:`Callable[[Union[bytes, str]], bytes]` | 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

`Generator[Union[Generator, Deferred[Flattenable]], None, None]`

An iterator that eventually writes `bytes` to `write`. It can 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 be another generator, in which case it is iterated. See `_flattenTree` for the trampoline that consumes said values.

async def _flattenTree(request, root, write): (source)

Make `root` into an iterable of `bytes` and `Deferred` by doing a depth first traversal of the tree.

Parameters
request:`Optional[IRequest]` | A request object which will be passed to `IRenderable.render`.
root:`Flattenable` | 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:`Callable[[bytes], object]` | A callable which will be invoked with each `bytes` produced by flattening `root`.
Returns
A `Deferred`-returning coroutine that resolves to `None`.

def _fork(d): (source)

Create a new `Deferred` based on `d` that will fire and fail with `d`'s result or error, but will not modify `d`'s callback type.

Parameters
d:`Deferred[T]` | Undocumented
Returns
`Deferred[T]` | Undocumented

def _getSlotValue(name, slotData, default=None): (source)

Find the value of the named slot in the given stack of slot data.

Parameters
name:`str` | Undocumented
slotData:`Sequence[Optional[Mapping[str, Flattenable]]]` | Undocumented
default:`Optional[Flattenable]` | Undocumented
Returns
`Flattenable` | Undocumented