Skip to content
Permalink
Browse files

bpo-33187: Document ElementInclude (XInclude) support in ElementTree (G…

…H-8861) (GH-15958)

(cherry picked from commit 97b817e)

Co-authored-by: Anjali Bansal <anjali.mca17.du@gmail.com>
  • Loading branch information...
2 people authored and scoder committed Sep 11, 2019
1 parent 8ee8ad2 commit 6cf0ba8a632b1c0bd3576ed33c971ca3778000de
Showing with 92 additions and 0 deletions.
  1. +89 −0 Doc/library/xml.etree.elementtree.rst
  2. +3 −0 Doc/tools/susp-ignored.csv
@@ -726,6 +726,95 @@ Functions
:class:`Element` instance and a dictionary.


.. _elementtree-xinclude:

XInclude support
----------------

This module provides limited support for
`XInclude directives <https://www.w3.org/TR/xinclude/>`_, via the :mod:`xml.etree.ElementInclude` helper module. This module can be used to insert subtrees and text strings into element trees, based on information in the tree.

Example
^^^^^^^

Here's an example that demonstrates use of the XInclude module. To include an XML document in the current document, use the ``{http://www.w3.org/2001/XInclude}include`` element and set the **parse** attribute to ``"xml"``, and use the **href** attribute to specify the document to include.

.. code-block:: xml
<?xml version="1.0"?>
<document xmlns:xi="http://www.w3.org/2001/XInclude">
<xi:include href="source.xml" parse="xml" />
</document>
By default, the **href** attribute is treated as a file name. You can use custom loaders to override this behaviour. Also note that the standard helper does not support XPointer syntax.

To process this file, load it as usual, and pass the root element to the :mod:`xml.etree.ElementTree` module:

.. code-block:: python
from xml.etree import ElementTree, ElementInclude
tree = ElementTree.parse("document.xml")
root = tree.getroot()
ElementInclude.include(root)
The ElementInclude module replaces the ``{http://www.w3.org/2001/XInclude}include`` element with the root element from the **source.xml** document. The result might look something like this:

.. code-block:: xml
<document xmlns:xi="http://www.w3.org/2001/XInclude">
<para>This is a paragraph.</para>
</document>
If the **parse** attribute is omitted, it defaults to "xml". The href attribute is required.

To include a text document, use the ``{http://www.w3.org/2001/XInclude}include`` element, and set the **parse** attribute to "text":

.. code-block:: xml
<?xml version="1.0"?>
<document xmlns:xi="http://www.w3.org/2001/XInclude">
Copyright (c) <xi:include href="year.txt" parse="text" />.
</document>
The result might look something like:

.. code-block:: xml
<document xmlns:xi="http://www.w3.org/2001/XInclude">
Copyright (c) 2003.
</document>
Reference
---------

.. _elementinclude-functions:

Functions
^^^^^^^^^

.. function:: xml.etree.ElementInclude.default_loader( href, parse, encoding=None)

Default loader. This default loader reads an included resource from disk. *href* is a URL.
*parse* is for parse mode either "xml" or "text". *encoding*
is an optional text encoding. If not given, encoding is ``utf-8``. Returns the
expanded resource. If the parse mode is ``"xml"``, this is an ElementTree
instance. If the parse mode is "text", this is a Unicode string. If the
loader fails, it can return None or raise an exception.


.. function:: xml.etree.ElementInclude.include( elem, loader=None)

This function expands XInclude directives. *elem* is the root element. *loader* is
an optional resource loader. If omitted, it defaults to :func:`default_loader`.
If given, it should be a callable that implements the same interface as
:func:`default_loader`. Returns the expanded resource. If the parse mode is
``"xml"``, this is an ElementTree instance. If the parse mode is "text",
this is a Unicode string. If the loader fails, it can return None or
raise an exception.


.. _elementtree-element-objects:

Element Objects
@@ -331,6 +331,9 @@ library/xml.etree.elementtree,,:character,<fictional:character>Commander Clement
library/xml.etree.elementtree,,:actor,"for actor in root.findall('real_person:actor', ns):"
library/xml.etree.elementtree,,:name,"name = actor.find('real_person:name', ns)"
library/xml.etree.elementtree,,:character,"for char in actor.findall('role:character', ns):"
library/xml.etree.elementtree,,:xi,<document xmlns:xi="http://www.w3.org/2001/XInclude">
library/xml.etree.elementtree,,:include, <xi:include href="source.xml" parse="xml" />
library/xml.etree.elementtree,,:include, Copyright (c) <xi:include href="year.txt" parse="text" />.
library/zipapp,,:main,"$ python -m zipapp myapp -m ""myapp:main"""
library/zipapp,,:fn,"pkg.mod:fn"
library/zipapp,,:callable,"pkg.module:callable"

0 comments on commit 6cf0ba8

Please sign in to comment.
You can’t perform that action at this time.