From 54881691697fcaa3d5f46a70df472b41dc2d3ce2 Mon Sep 17 00:00:00 2001 From: Mikhail Beloborodyy Date: Fri, 3 Feb 2023 18:38:13 -0500 Subject: [PATCH 1/8] gh-101549: fix documentation of xml.etree.ElementInclude fixed wrong type in default_loader description. fixed description of the include method. --- Doc/library/xml.etree.elementtree.rst | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst index f9290f528e5555..0d10c3d07d35ca 100644 --- a/Doc/library/xml.etree.elementtree.rst +++ b/Doc/library/xml.etree.elementtree.rst @@ -825,19 +825,19 @@ Reference Functions ^^^^^^^^^ -.. function:: xml.etree.ElementInclude.default_loader( href, parse, encoding=None) +.. function:: xml.etree.ElementInclude.default_loader(href, parse, encoding=None) :module: - Default loader. This default loader reads an included resource from disk. *href* is a URL. + 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 + expanded resource. If the parse mode is ``"xml"``, this is an Element 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, base_url=None, \ - max_depth=6) +.. function:: xml.etree.ElementInclude.include(elem, loader=None, base_url=None, \ + max_depth=6) :module: This function expands XInclude directives. *elem* is the root element. *loader* is @@ -848,10 +848,7 @@ Functions 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. + Returns the expanded resource in *elem*. .. versionadded:: 3.9 The *base_url* and *max_depth* parameters. From 8ff783db42af28f4d86daf097d9da6633274c1c3 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Fri, 12 Jan 2024 23:31:45 +0000 Subject: [PATCH 2/8] Markup; remove unneeded note about unicode strings --- Doc/library/xml.etree.elementtree.rst | 13 +++++++------ Lib/xml/etree/ElementInclude.py | 4 ++-- 2 files changed, 9 insertions(+), 8 deletions(-) diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst index 6ddf77355e6da5..4246712a81bcc4 100644 --- a/Doc/library/xml.etree.elementtree.rst +++ b/Doc/library/xml.etree.elementtree.rst @@ -833,12 +833,13 @@ Functions .. function:: xml.etree.ElementInclude.default_loader(href, parse, encoding=None) :module: - 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 Element - 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:`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, \ diff --git a/Lib/xml/etree/ElementInclude.py b/Lib/xml/etree/ElementInclude.py index 40a9b22292479f..1091008e20edd4 100644 --- a/Lib/xml/etree/ElementInclude.py +++ b/Lib/xml/etree/ElementInclude.py @@ -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. From 094867acb0da5a7a74db4d8d5168bcc0a89629ad Mon Sep 17 00:00:00 2001 From: Mikhail B <55960560+mbel0@users.noreply.github.com> Date: Wed, 21 Feb 2024 10:38:29 -0500 Subject: [PATCH 3/8] Update Doc/library/xml.etree.elementtree.rst Co-authored-by: Serhiy Storchaka --- Doc/library/xml.etree.elementtree.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst index 4246712a81bcc4..85b94261082bf9 100644 --- a/Doc/library/xml.etree.elementtree.rst +++ b/Doc/library/xml.etree.elementtree.rst @@ -846,7 +846,8 @@ Functions max_depth=6) :module: - This function expands XInclude directives. *elem* is the root element. *loader* is + This function expands XInclude directives in-place in *elem*. + *elem* is the root element or an :class:`ElementTree` instance. *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 From 7f16cb74404cd9b9336dbe71bda6ba8884b6737a Mon Sep 17 00:00:00 2001 From: Mikhail B <55960560+mbel0@users.noreply.github.com> Date: Wed, 21 Feb 2024 10:38:37 -0500 Subject: [PATCH 4/8] Update Doc/library/xml.etree.elementtree.rst Co-authored-by: Serhiy Storchaka --- Doc/library/xml.etree.elementtree.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst index 85b94261082bf9..cd34b4168f0fc7 100644 --- a/Doc/library/xml.etree.elementtree.rst +++ b/Doc/library/xml.etree.elementtree.rst @@ -852,8 +852,8 @@ Functions 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. + inclusions. Limited to reduce the risk of malicious content explosion. + Pass ``None`` to disable the limitation. Returns the expanded resource in *elem*. From 5d6e5e5f4f5fe4bbb11d6761da0be161d0974a13 Mon Sep 17 00:00:00 2001 From: Mikhail Beloborodyy Date: Wed, 21 Feb 2024 11:25:30 -0500 Subject: [PATCH 5/8] fix rewiew comments attempt to fix documentation check errors by using absolute class names --- Doc/library/xml.etree.elementtree.rst | 14 +++++++------- Lib/xml/etree/ElementInclude.py | 5 +++-- 2 files changed, 10 insertions(+), 9 deletions(-) diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst index cd34b4168f0fc7..4e369572c519b3 100644 --- a/Doc/library/xml.etree.elementtree.rst +++ b/Doc/library/xml.etree.elementtree.rst @@ -834,20 +834,20 @@ Functions :module: 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``. + *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:`Element` instance. + If the parse mode is ``"xml"``, this is an :class:`xml.etree.Element` instance. If the parse mode is ``"text"``, this is a string. - If the loader fails, it can return None or raise an exception. + 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: - This function expands XInclude directives in-place in *elem*. - *elem* is the root element or an :class:`ElementTree` instance. *loader* is + This function expands XInclude directives in-place in *elem*. *elem* is the + root element or an :class:`xml.etree.ElementTree` instance. *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 @@ -855,7 +855,7 @@ Functions inclusions. Limited to reduce the risk of malicious content explosion. Pass ``None`` to disable the limitation. - Returns the expanded resource in *elem*. + Returns ``None``. Updates tree pointed by *elem*. .. versionadded:: 3.9 The *base_url* and *max_depth* parameters. diff --git a/Lib/xml/etree/ElementInclude.py b/Lib/xml/etree/ElementInclude.py index 1091008e20edd4..d9292b1bacbadd 100644 --- a/Lib/xml/etree/ElementInclude.py +++ b/Lib/xml/etree/ElementInclude.py @@ -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 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): From 82ea41e3683f638914f21829f18109a16f4c9f66 Mon Sep 17 00:00:00 2001 From: Mikhail Beloborodyy Date: Wed, 21 Feb 2024 12:07:18 -0500 Subject: [PATCH 6/8] remove old hack with :module: --- Doc/library/xml.etree.elementtree.rst | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst index 4e369572c519b3..e92a14b4509754 100644 --- a/Doc/library/xml.etree.elementtree.rst +++ b/Doc/library/xml.etree.elementtree.rst @@ -830,24 +830,22 @@ 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 :class:`xml.etree.Element` instance. + If the parse mode is ``"xml"``, this is an :class:`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, \ +.. function:: include(elem, loader=None, base_url=None, \ max_depth=6) - :module: This function expands XInclude directives in-place in *elem*. *elem* is the - root element or an :class:`xml.etree.ElementTree` instance. *loader* is + root element or an :class:`ElementTree` instance. *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 From 6cf07dfb6cb8a43f00ef8cba41b5577ca9cf7f53 Mon Sep 17 00:00:00 2001 From: Mikhail Beloborodyy Date: Wed, 21 Feb 2024 12:30:31 -0500 Subject: [PATCH 7/8] correct cross-module references --- Doc/library/xml.etree.elementtree.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst index e92a14b4509754..fac85aab6b4235 100644 --- a/Doc/library/xml.etree.elementtree.rst +++ b/Doc/library/xml.etree.elementtree.rst @@ -836,16 +836,15 @@ Functions *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:`Element` instance. + 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:: include(elem, loader=None, base_url=None, \ - max_depth=6) +.. function:: include(elem, loader=None, base_url=None, max_depth=6) This function expands XInclude directives in-place in *elem*. *elem* is the - root element or an :class:`ElementTree` instance. *loader* is + root element or an :class:`~xml.etree.ElementTree.ElementTree` instance. *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 From 67ff8d83e0a58dd1531318ede41f4cb471b487e9 Mon Sep 17 00:00:00 2001 From: Mikhail Beloborodyy Date: Wed, 21 Feb 2024 22:18:11 -0500 Subject: [PATCH 8/8] fix review comments --- Doc/library/xml.etree.elementtree.rst | 9 ++++----- Lib/xml/etree/ElementInclude.py | 4 ++-- 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst index fac85aab6b4235..5b3dbcfb4e35e0 100644 --- a/Doc/library/xml.etree.elementtree.rst +++ b/Doc/library/xml.etree.elementtree.rst @@ -843,17 +843,16 @@ Functions .. function:: include(elem, loader=None, base_url=None, max_depth=6) - This function expands XInclude directives in-place in *elem*. *elem* is the - root element or an :class:`~xml.etree.ElementTree.ElementTree` instance. *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 ``None`` to disable the limitation. - Returns ``None``. Updates tree pointed by *elem*. - .. versionadded:: 3.9 The *base_url* and *max_depth* parameters. diff --git a/Lib/xml/etree/ElementInclude.py b/Lib/xml/etree/ElementInclude.py index d9292b1bacbadd..986e6c3bbe90f6 100644 --- a/Lib/xml/etree/ElementInclude.py +++ b/Lib/xml/etree/ElementInclude.py @@ -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 default_loader. @@ -110,7 +110,7 @@ def default_loader(href, parse, encoding=None): # @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. +# @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}