|
| 1 | +from w3.python.typing import _Document |
| 2 | +from w3.python.core.fundamental_interface.Node import Node |
| 3 | +from w3.python.core.fundamental_interface.Node import NodeType |
| 4 | + |
| 5 | + |
| 6 | +class DocumentFragment(Node): |
| 7 | + """Interface `DocumentFragment` |
| 8 | + |
| 9 | + `DocumentFragment` is a "lightweight" or "minimal" `Document` object. |
| 10 | + It is very common to want to be able to extract a portion of a document's tree or to create a new fragment of a document. |
| 11 | + Imagine implementing a user command like cut or rearranging a document by moving fragments around. |
| 12 | + It is desirable to have an object which can hold such fragments and it is quite natural to use a `Node` for this purpose. |
| 13 | + While it is true that a `Document` object could fulfil this role, a `Document` object can potentially be a heavyweight object, depending on the underlying implementation. |
| 14 | + What is really needed for this is a very lightweight object. |
| 15 | + `DocumentFragment` is such an object. |
| 16 | + |
| 17 | + Furthermore, various operations -- such as inserting nodes as children of another `Node` -- may take `DocumentFragment` objects as arguments; this results in all the child nodes of the `DocumentFragment` being moved to the child list of this node. |
| 18 | + |
| 19 | + The children of a `DocumentFragment` node are zero or more nodes representing the tops of any sub-trees defining the structure of the document. |
| 20 | + `DocumentFragment` nodes do not need to be well-formed XML documents (although they do need to follow the rules imposed upon well-formed XML parsed entities, which can have multiple top nodes). |
| 21 | + For example, a `DocumentFragment` might have only one child and that child node could be a `Text` node. |
| 22 | + Such a structure model represents neither an HTML document nor a well-formed XML document. |
| 23 | + |
| 24 | + When a `DocumentFragment` is inserted into a `Document` (or indeed any other `Node` that may take children) the children of the `DocumentFragment` and not the `DocumentFragment` itself are inserted into the `Node`. |
| 25 | + This makes the `DocumentFragment` very useful when the user wishes to create nodes that are siblings; the `DocumentFragment` acts as the parent of these nodes so that the user can use the standard methods from the `Node` interface, such as `insertBefore()` and `appendChild()`. |
| 26 | + """ |
| 27 | + |
| 28 | + def __init__(self, |
| 29 | + owner_document: _Document, |
| 30 | + read_only: bool = False) -> None: |
| 31 | + super().__init__(owner_document=owner_document, |
| 32 | + node_type=NodeType.DOCUMENT_FRAGMENT_NODE, |
| 33 | + node_name='#document-fragment', |
| 34 | + node_value=None, |
| 35 | + read_only=read_only) |
0 commit comments