languages/cpython
languages/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython synced 2024-10-14 22:28:32 +00:00
Code Issues Packages Projects Releases Wiki Activity

[3.12] gh-101549: fix documentation of xml.etree.ElementInclude (GH-101550) (#117754)

Browse source 
Co-authored-by: Mikhail B <55960560+mbel0@users.noreply.github.com>
Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
This commit is contained in:
Miss Islington (bot) 2024-04-11 16:53:27 +02:00 committed by GitHub
parent a4541a6080
commit a3f1e980c3
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 22 additions and 26 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

35
Doc/library/xml.etree.elementtree.rst
View file

@ -835,33 +835,28 @@ Functions
.. module:: xml.etree.ElementInclude
.. function:: xml.etree.ElementInclude.default_loader( href, parse, encoding=None)
:module:
.. function:: 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.
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 :class:`~xml.etree.ElementTree.Element` instance.
If the parse mode is ``"text"``, this is a string.
If the loader fails, it can return ``None`` or raise an exception.
.. function:: xml.etree.ElementInclude.include( elem, loader=None, base_url=None, \
max_depth=6)
:module:
.. function:: include(elem, loader=None, base_url=None, max_depth=6)
This function expands XInclude directives. *elem* is the root element. *loader* is
an optional resource loader. If omitted, it defaults to :func:`default_loader`.
This function expands XInclude directives in-place in tree pointed by *elem*.
*elem* is either the root :class:`~xml.etree.ElementTree.Element` or an
:class:`~xml.etree.ElementTree.ElementTree` instance to find such 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`. *base_url* is base URL of the original file, to resolve
relative include file references. *max_depth* is the maximum number of recursive
inclusions. Limited to reduce the risk of malicious content explosion. Pass a
negative value to disable the limitation.
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.
inclusions. Limited to reduce the risk of malicious content explosion.
Pass ``None`` to disable the limitation.
.. versionchanged:: 3.9
Added the *base_url* and *max_depth* parameters.

13
Lib/xml/etree/ElementInclude.py
View file

@ -79,8 +79,8 @@ class LimitedRecursiveIncludeError(FatalIncludeError):
# @param parse Parse mode. Either "xml" or "text".
# @param encoding Optional text encoding (UTF-8 by default for "text").
# @return 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
# is an Element instance. If the parse mode is "text", this
# is a string. If the loader fails, it can return None
# or raise an OSError exception.
# @throws OSError If the loader fails to load the resource.
@ -98,7 +98,7 @@ def default_loader(href, parse, encoding=None):
##
# Expand XInclude directives.
#
# @param elem Root element.
# @param elem Root Element or any ElementTree of a tree to be expanded
# @param loader Optional resource loader. If omitted, it defaults
# to {@link default_loader}. If given, it should be a callable
# that implements the same interface as <b>default_loader</b>.
@ -106,12 +106,13 @@ def default_loader(href, parse, encoding=None):
# relative include file references.
# @param max_depth The maximum number of recursive inclusions.
# Limited to reduce the risk of malicious content explosion.
# Pass a negative value to disable the limitation.
# Pass None to disable the limitation.
# @throws LimitedRecursiveIncludeError If the {@link max_depth} was exceeded.
# @throws FatalIncludeError If the function fails to include a given
# resource, or if the tree contains malformed XInclude elements.
# @throws IOError If the function fails to load a given resource.
# @returns the node or its replacement if it was an XInclude node
# @throws OSError If the function fails to load a given resource.
# @throws ValueError If negative {@link max_depth} is passed.
# @returns None. Modifies tree pointed by {@link elem}
def include(elem, loader=None, base_url=None,
max_depth=DEFAULT_MAX_INCLUSION_DEPTH):