https://github.com/python/cpython/commit/050fd7dd32df87e8f9b39a3e2fb643ce1e4c4e3a
commit: 050fd7dd32df87e8f9b39a3e2fb643ce1e4c4e3a
branch: main
author: Serhiy Storchaka <[email protected]>
committer: serhiy-storchaka <[email protected]>
date: 2026-09-03T12:26:28+03:00
summary:
gh-126273: Add missing docstrings in the C implementation of xml.etree
(GH-156783)
Copy the docstrings of the Element, TreeBuilder and XMLParser classes and
their methods from the Python implementation. Element, TreeBuilder and
XMLParser now also have the text signature.
files:
M Modules/_elementtree.c
M Modules/clinic/_elementtree.c.h
diff --git a/Modules/_elementtree.c b/Modules/_elementtree.c
index 18bbbb618c2b18..f6dedeed981c40 100644
--- a/Modules/_elementtree.c
+++ b/Modules/_elementtree.c
@@ -720,12 +720,17 @@ _elementtree.Element.append
subelement: object(subclass_of='clinic_state()->Element_Type')
/
+Add *subelement* to the end of this element.
+
+The new element will appear in document order after the last
+existing subelement (or directly after the text, if it's the first
+subelement), but before the end tag for this element.
[clinic start generated code]*/
static PyObject *
_elementtree_Element_append_impl(ElementObject *self, PyTypeObject *cls,
PyObject *subelement)
-/*[clinic end generated code: output=d00923711ea317fc input=8baf92679f9717b8]*/
+/*[clinic end generated code: output=d00923711ea317fc input=a59ebce98937a372]*/
{
elementtreestate *st = get_elementtree_state_by_cls(cls);
if (element_add_subelement(st, self, subelement) < 0)
@@ -737,11 +742,15 @@ _elementtree_Element_append_impl(ElementObject *self,
PyTypeObject *cls,
/*[clinic input]
_elementtree.Element.clear
+Reset element.
+
+This function removes all subelements, clears all attributes, and
+sets the text and tail attributes to None.
[clinic start generated code]*/
static PyObject *
_elementtree_Element_clear_impl(ElementObject *self)
-/*[clinic end generated code: output=8bcd7a51f94cfff6 input=3c719ff94bf45dd6]*/
+/*[clinic end generated code: output=8bcd7a51f94cfff6 input=135c2ab634d0fdf5]*/
{
clear_extra(self);
@@ -1250,12 +1259,15 @@ _elementtree.Element.extend
elements: object
/
+Append subelements from a sequence.
+
+*elements* is a sequence with zero or more elements.
[clinic start generated code]*/
static PyObject *
_elementtree_Element_extend_impl(ElementObject *self, PyTypeObject *cls,
PyObject *elements)
-/*[clinic end generated code: output=3e86d37fac542216 input=6479b1b5379d09ae]*/
+/*[clinic end generated code: output=3e86d37fac542216 input=401ac1d07e13282b]*/
{
PyObject* seq;
Py_ssize_t i;
@@ -1289,12 +1301,19 @@ _elementtree.Element.find
path: object
namespaces: object = None
+Find first matching element by tag name or path.
+
+*path* is a string having either an element tag or an XPath,
+*namespaces* is an optional mapping from namespace prefix to full
+name.
+
+Return the first matching element, or None if no element was found.
[clinic start generated code]*/
static PyObject *
_elementtree_Element_find_impl(ElementObject *self, PyTypeObject *cls,
PyObject *path, PyObject *namespaces)
-/*[clinic end generated code: output=18f77d393c9fef1b input=94df8a83f956acc6]*/
+/*[clinic end generated code: output=18f77d393c9fef1b input=3aec422879a342e1]*/
{
elementtreestate *st = get_elementtree_state_by_cls(cls);
@@ -1332,13 +1351,23 @@ _elementtree.Element.findtext
default: object = None
namespaces: object = None
+Find text for first matching element by tag name or path.
+
+*path* is a string having either an element tag or an XPath,
+*default* is the value to return if the element was not found,
+*namespaces* is an optional mapping from namespace prefix to full
+name.
+
+Return text content of first matching element, or default value if
+none was found. Note that if an element is found having no text
+content, the empty string is returned.
[clinic start generated code]*/
static PyObject *
_elementtree_Element_findtext_impl(ElementObject *self, PyTypeObject *cls,
PyObject *path, PyObject *default_value,
PyObject *namespaces)
-/*[clinic end generated code: output=6af7a2d96aac32cb input=32f252099f62a3d2]*/
+/*[clinic end generated code: output=6af7a2d96aac32cb input=64610701f762c4f5]*/
{
elementtreestate *st = get_elementtree_state_by_cls(cls);
@@ -1381,12 +1410,19 @@ _elementtree.Element.findall
path: object
namespaces: object = None
+Find all matching subelements by tag name or path.
+
+*path* is a string having either an element tag or an XPath,
+*namespaces* is an optional mapping from namespace prefix to full
+name.
+
+Returns list containing all matching elements in document order.
[clinic start generated code]*/
static PyObject *
_elementtree_Element_findall_impl(ElementObject *self, PyTypeObject *cls,
PyObject *path, PyObject *namespaces)
-/*[clinic end generated code: output=65e39a1208f3b59e input=7aa0db45673fc9a5]*/
+/*[clinic end generated code: output=65e39a1208f3b59e input=2208ddeb5f1cc7c3]*/
{
elementtreestate *st = get_elementtree_state_by_cls(cls);
@@ -1427,12 +1463,19 @@ _elementtree.Element.iterfind
path: object
namespaces: object = None
+Find all matching subelements by tag name or path.
+
+*path* is a string having either an element tag or an XPath,
+*namespaces* is an optional mapping from namespace prefix to full
+name.
+
+Return an iterable yielding all matching elements in document order.
[clinic start generated code]*/
static PyObject *
_elementtree_Element_iterfind_impl(ElementObject *self, PyTypeObject *cls,
PyObject *path, PyObject *namespaces)
-/*[clinic end generated code: output=be5c3f697a14e676 input=88766875a5c9a88b]*/
+/*[clinic end generated code: output=be5c3f697a14e676 input=00bea06334260582]*/
{
PyObject* tag = path;
elementtreestate *st = get_elementtree_state_by_cls(cls);
@@ -1447,12 +1490,20 @@ _elementtree.Element.get
key: object
default: object = None
+Get element attribute.
+
+Equivalent to attrib.get, but some implementations may handle this a
+bit more efficiently. *key* is what attribute to look for, and
+*default* is what to return if the attribute was not found.
+
+Returns a string containing the attribute value, or the default if
+attribute was not found.
[clinic start generated code]*/
static PyObject *
_elementtree_Element_get_impl(ElementObject *self, PyObject *key,
PyObject *default_value)
-/*[clinic end generated code: output=523c614142595d75 input=ee153bbf8cdb246e]*/
+/*[clinic end generated code: output=523c614142595d75 input=332624526ef81a70]*/
{
if (self->extra && self->extra->attrib) {
PyObject *attrib = Py_NewRef(self->extra->attrib);
@@ -1478,12 +1529,24 @@ _elementtree.Element.iter
/
tag: object = None
+Create tree iterator.
+
+The iterator loops over the element and all subelements in document
+order, returning all elements with a matching tag.
+
+If the tree structure is modified during iteration, new or removed
+elements may or may not be included. To get a stable set, use the
+list() function on the iterator, and loop over the resulting list.
+
+*tag* is what tags to look for (default is to return all elements)
+
+Return an iterator containing all the matching elements.
[clinic start generated code]*/
static PyObject *
_elementtree_Element_iter_impl(ElementObject *self, PyTypeObject *cls,
PyObject *tag)
-/*[clinic end generated code: output=bff29dc5d4566c68 input=f6944c48d3f84c58]*/
+/*[clinic end generated code: output=bff29dc5d4566c68 input=e4c542a12e6f9199]*/
{
if (PyUnicode_Check(tag)) {
if (PyUnicode_GET_LENGTH(tag) == 1 && PyUnicode_READ_CHAR(tag, 0) ==
'*')
@@ -1505,11 +1568,15 @@ _elementtree.Element.itertext
cls: defining_class
/
+Create text iterator.
+
+The iterator loops over the element and all subelements in document
+order, returning all inner text.
[clinic start generated code]*/
static PyObject *
_elementtree_Element_itertext_impl(ElementObject *self, PyTypeObject *cls)
-/*[clinic end generated code: output=fdeb2a3bca0ae063 input=a1ef1f0fc872a586]*/
+/*[clinic end generated code: output=fdeb2a3bca0ae063 input=eaffe70224da7f02]*/
{
elementtreestate *st = get_elementtree_state_by_cls(cls);
return create_elementiter(st, self, Py_None, 1);
@@ -1556,12 +1623,13 @@ _elementtree.Element.insert
subelement: object(subclass_of='clinic_state()->Element_Type')
/
+Insert *subelement* at position *index*.
[clinic start generated code]*/
static PyObject *
_elementtree_Element_insert_impl(ElementObject *self, Py_ssize_t index,
PyObject *subelement)
-/*[clinic end generated code: output=990adfef4d424c0b input=9530f4905aa401ca]*/
+/*[clinic end generated code: output=990adfef4d424c0b input=2886a2266de15ed7]*/
{
Py_ssize_t i;
@@ -1594,11 +1662,14 @@ _elementtree_Element_insert_impl(ElementObject *self,
Py_ssize_t index,
/*[clinic input]
_elementtree.Element.items
+Get element attributes as (name, value) pairs.
+
+Equivalent to attrib.items().
[clinic start generated code]*/
static PyObject *
_elementtree_Element_items_impl(ElementObject *self)
-/*[clinic end generated code: output=6db2c778ce3f5a4d input=adbe09aaea474447]*/
+/*[clinic end generated code: output=6db2c778ce3f5a4d input=7b5adcd8f774d4e0]*/
{
if (!self->extra || !self->extra->attrib)
return PyList_New(0);
@@ -1609,11 +1680,14 @@ _elementtree_Element_items_impl(ElementObject *self)
/*[clinic input]
_elementtree.Element.keys
+Get attribute names.
+
+Equivalent to attrib.keys()
[clinic start generated code]*/
static PyObject *
_elementtree_Element_keys_impl(ElementObject *self)
-/*[clinic end generated code: output=bc5bfabbf20eeb3c input=f02caf5b496b5b0b]*/
+/*[clinic end generated code: output=bc5bfabbf20eeb3c input=6d860fbdb565115d]*/
{
if (!self->extra || !self->extra->attrib)
return PyList_New(0);
@@ -1639,12 +1713,19 @@ _elementtree.Element.makeelement
attrib: object(subclass_of='&PyDict_Type')
/
+Create a new element with the same type.
+
+*tag* is a string containing the element name. *attrib* is a
+dictionary containing the element attributes.
+
+Do not call this method, use the SubElement factory function
+instead.
[clinic start generated code]*/
static PyObject *
_elementtree_Element_makeelement_impl(ElementObject *self, PyTypeObject *cls,
PyObject *tag, PyObject *attrib)
-/*[clinic end generated code: output=d50bb17a47077d47 input=589829dab92f26e8]*/
+/*[clinic end generated code: output=d50bb17a47077d47 input=02b62a503fa25ae7]*/
{
PyObject* elem;
@@ -1666,11 +1747,20 @@ _elementtree.Element.remove
subelement: object(subclass_of='clinic_state()->Element_Type')
/
+Remove matching subelement.
+
+Unlike the find methods, this method compares elements based on
+identity, NOT ON tag value or contents. To remove subelements by
+other means, the easiest way is to use a list comprehension to
+select what elements to keep, and then use slice assignment to
+update the parent element.
+
+ValueError is raised if a matching element could not be found.
[clinic start generated code]*/
static PyObject *
_elementtree_Element_remove_impl(ElementObject *self, PyObject *subelement)
-/*[clinic end generated code: output=38fe6c07d6d87d1f input=6133e1d05597d5ee]*/
+/*[clinic end generated code: output=38fe6c07d6d87d1f input=e035af9d920f785b]*/
{
Py_ssize_t i;
// When iterating over the list of children, we need to check that the
@@ -1748,12 +1838,17 @@ _elementtree.Element.set
value: object
/
+Set element attribute.
+
+Equivalent to attrib[key] = value, but some implementations may
+handle this a bit more efficiently. *key* is what attribute to set,
+and *value* is the attribute value to set it to.
[clinic start generated code]*/
static PyObject *
_elementtree_Element_set_impl(ElementObject *self, PyObject *key,
PyObject *value)
-/*[clinic end generated code: output=fb938806be3c5656 input=1efe90f7d82b3fe9]*/
+/*[clinic end generated code: output=fb938806be3c5656 input=bbaadd68b86636d7]*/
{
PyObject* attrib;
@@ -2470,6 +2565,24 @@ _elementtree.TreeBuilder.__init__
insert_comments: bool = False
insert_pis: bool = False
+Generic element structure builder.
+
+This builder converts a sequence of start, data, and end method
+calls to a well-formed element structure.
+
+You can use this class to build an element structure using a custom
+XML parser, or a parser for some other XML-like format.
+
+*element_factory* is an optional element factory which is called
+to create new Element instances, as necessary.
+
+*comment_factory* is a factory to create comments to be used instead
+of the standard factory. If *insert_comments* is false (the
+default), comments will not be inserted into the tree.
+
+*pi_factory* is a factory to create processing instructions to be
+used instead of the standard factory. If *insert_pis* is false (the
+default), processing instructions will not be inserted into the tree.
[clinic start generated code]*/
static int
@@ -2478,7 +2591,7 @@ _elementtree_TreeBuilder___init___impl(TreeBuilderObject
*self,
PyObject *comment_factory,
PyObject *pi_factory,
int insert_comments, int insert_pis)
-/*[clinic end generated code: output=8571d4dcadfdf952 input=ae98a94df20b5cc3]*/
+/*[clinic end generated code: output=8571d4dcadfdf952 input=24fb5a482d93f8e4]*/
{
if (element_factory != Py_None) {
Py_XSETREF(self->element_factory, Py_NewRef(element_factory));
@@ -3004,11 +3117,12 @@ _elementtree.TreeBuilder.data
data: object
/
+Add text to current element.
[clinic start generated code]*/
static PyObject *
_elementtree_TreeBuilder_data_impl(TreeBuilderObject *self, PyObject *data)
-/*[clinic end generated code: output=dfa02b68f732b8c0 input=a0540c532b284d29]*/
+/*[clinic end generated code: output=dfa02b68f732b8c0 input=679b26864cecbde8]*/
{
return treebuilder_handle_data(self, data);
}
@@ -3019,11 +3133,14 @@ _elementtree.TreeBuilder.end
tag: object
/
+Close and return current Element.
+
+*tag* is the element name.
[clinic start generated code]*/
static PyObject *
_elementtree_TreeBuilder_end_impl(TreeBuilderObject *self, PyObject *tag)
-/*[clinic end generated code: output=84cb6ca9008ec740 input=22dc3674236f5745]*/
+/*[clinic end generated code: output=84cb6ca9008ec740 input=9d161338282e5fac]*/
{
return treebuilder_handle_end(self, tag);
}
@@ -3034,12 +3151,15 @@ _elementtree.TreeBuilder.comment
text: object
/
+Create a comment using the comment_factory.
+
+*text* is the text of the comment.
[clinic start generated code]*/
static PyObject *
_elementtree_TreeBuilder_comment_impl(TreeBuilderObject *self,
PyObject *text)
-/*[clinic end generated code: output=a555ef39027c3823 input=47e7ebc48ed01dfa]*/
+/*[clinic end generated code: output=a555ef39027c3823 input=b1579b62bb9277e4]*/
{
return treebuilder_handle_comment(self, text);
}
@@ -3051,12 +3171,16 @@ _elementtree.TreeBuilder.pi
text: object = None
/
+Create a processing instruction using the pi_factory.
+
+*target* is the target name of the processing instruction. *text* is
+the data of the processing instruction, or ''.
[clinic start generated code]*/
static PyObject *
_elementtree_TreeBuilder_pi_impl(TreeBuilderObject *self, PyObject *target,
PyObject *text)
-/*[clinic end generated code: output=21eb95ec9d04d1d9 input=349342bd79c35570]*/
+/*[clinic end generated code: output=21eb95ec9d04d1d9 input=160b939cc17e4121]*/
{
return treebuilder_handle_pi(self, target, text);
}
@@ -3079,11 +3203,12 @@ treebuilder_done(TreeBuilderObject* self)
/*[clinic input]
_elementtree.TreeBuilder.close
+Flush builder buffers and return toplevel document Element.
[clinic start generated code]*/
static PyObject *
_elementtree_TreeBuilder_close_impl(TreeBuilderObject *self)
-/*[clinic end generated code: output=b441fee3202f61ee input=f7c9c65dc718de14]*/
+/*[clinic end generated code: output=b441fee3202f61ee input=461e8391c6b73c5f]*/
{
return treebuilder_done(self);
}
@@ -3095,12 +3220,16 @@ _elementtree.TreeBuilder.start
attrs: object(subclass_of='&PyDict_Type')
/
+Open new element and return it.
+
+*tag* is the element name, *attrs* is a dict containing element
+attributes.
[clinic start generated code]*/
static PyObject *
_elementtree_TreeBuilder_start_impl(TreeBuilderObject *self, PyObject *tag,
PyObject *attrs)
-/*[clinic end generated code: output=e7e9dc2861349411 input=7288e9e38e63b2b6]*/
+/*[clinic end generated code: output=e7e9dc2861349411 input=26cccb49c3b8b12f]*/
{
return treebuilder_handle_start(self, tag, attrs);
}
@@ -3715,18 +3844,25 @@ ignore_attribute_error(PyObject *value)
}
/*[clinic input]
+@permit_long_summary
_elementtree.XMLParser.__init__
*
target: object = None
encoding: str(accept={str, NoneType}) = None
+Element structure builder for XML source data based on the expat parser.
+
+*target* is an optional target object which defaults to an instance
+of the standard TreeBuilder class, *encoding* is an optional encoding
+string which if given, overrides the encoding specified in the XML
+file: http://www.iana.org/assignments/character-sets
[clinic start generated code]*/
static int
_elementtree_XMLParser___init___impl(XMLParserObject *self, PyObject *target,
const char *encoding)
-/*[clinic end generated code: output=3ae45ec6cdf344e4 input=7e716dd6e4f3e439]*/
+/*[clinic end generated code: output=3ae45ec6cdf344e4 input=43dcd316382c80a2]*/
{
self->entity = PyDict_New();
if (!self->entity)
@@ -3969,11 +4105,12 @@ expat_parse_large(elementtreestate *st, XMLParserObject
*self,
/*[clinic input]
_elementtree.XMLParser.close
+Finish feeding data to parser and return element structure.
[clinic start generated code]*/
static PyObject *
_elementtree_XMLParser_close_impl(XMLParserObject *self)
-/*[clinic end generated code: output=d68d375dd23bc7fb input=ca7909ca78c3abfe]*/
+/*[clinic end generated code: output=d68d375dd23bc7fb input=177603f3353e644f]*/
{
/* end feeding data to parser */
@@ -4040,11 +4177,12 @@ _elementtree.XMLParser.feed
data: object
/
+Feed encoded data to parser.
[clinic start generated code]*/
static PyObject *
_elementtree_XMLParser_feed_impl(XMLParserObject *self, PyObject *data)
-/*[clinic end generated code: output=503e6fbf1adf17ab input=fe231b6b8de3ce1f]*/
+/*[clinic end generated code: output=503e6fbf1adf17ab input=9432a189100bc488]*/
{
/* feed data to parser */
@@ -4360,7 +4498,27 @@ static PyGetSetDef element_getsetlist[] = {
{NULL},
};
+PyDoc_STRVAR(element_doc,
+"Element(tag, attrib={}, **extra)\n"
+"--\n"
+"\n"
+"An XML element.\n"
+"\n"
+"This class is the reference implementation of the Element interface.\n"
+"\n"
+"An element's length is its number of subelements. That means if you\n"
+"want to check if an element is truly empty, you should check BOTH\n"
+"its length AND its text attribute.\n"
+"\n"
+"*tag* is the element name. *attrib* is an optional dictionary\n"
+"containing element attributes. *extra* are additional element\n"
+"attributes given as keyword arguments.\n"
+"\n"
+"Example form:\n"
+" <tag attrib>text<child/>...</tag>tail");
+
static PyType_Slot element_slots[] = {
+ {Py_tp_doc, (void *)element_doc},
{Py_tp_dealloc, element_dealloc},
{Py_tp_repr, element_repr},
{Py_tp_getattro, PyObject_GenericGetAttr},
@@ -4401,6 +4559,7 @@ static PyMethodDef treebuilder_methods[] = {
};
static PyType_Slot treebuilder_slots[] = {
+ {Py_tp_doc, (void *)_elementtree_TreeBuilder___init____doc__},
{Py_tp_dealloc, treebuilder_dealloc},
{Py_tp_traverse, treebuilder_gc_traverse},
{Py_tp_clear, treebuilder_gc_clear},
@@ -4428,6 +4587,7 @@ static PyMethodDef xmlparser_methods[] = {
};
static PyType_Slot xmlparser_slots[] = {
+ {Py_tp_doc, (void *)_elementtree_XMLParser___init____doc__},
{Py_tp_dealloc, xmlparser_dealloc},
{Py_tp_traverse, xmlparser_gc_traverse},
{Py_tp_clear, xmlparser_gc_clear},
diff --git a/Modules/clinic/_elementtree.c.h b/Modules/clinic/_elementtree.c.h
index c9e77a4c2b92d8..a39e738ec538b6 100644
--- a/Modules/clinic/_elementtree.c.h
+++ b/Modules/clinic/_elementtree.c.h
@@ -12,7 +12,12 @@ preserve
PyDoc_STRVAR(_elementtree_Element_append__doc__,
"append($self, subelement, /)\n"
"--\n"
-"\n");
+"\n"
+"Add *subelement* to the end of this element.\n"
+"\n"
+"The new element will appear in document order after the last\n"
+"existing subelement (or directly after the text, if it\'s the first\n"
+"subelement), but before the end tag for this element.");
#define _ELEMENTTREE_ELEMENT_APPEND_METHODDEF \
{"append", _PyCFunction_CAST(_elementtree_Element_append),
METH_METHOD|METH_FASTCALL|METH_KEYWORDS, _elementtree_Element_append__doc__},
@@ -60,7 +65,11 @@ _elementtree_Element_append(PyObject *self, PyTypeObject
*cls, PyObject *const *
PyDoc_STRVAR(_elementtree_Element_clear__doc__,
"clear($self, /)\n"
"--\n"
-"\n");
+"\n"
+"Reset element.\n"
+"\n"
+"This function removes all subelements, clears all attributes, and\n"
+"sets the text and tail attributes to None.");
#define _ELEMENTTREE_ELEMENT_CLEAR_METHODDEF \
{"clear", (PyCFunction)_elementtree_Element_clear, METH_NOARGS,
_elementtree_Element_clear__doc__},
@@ -214,7 +223,10 @@ _elementtree_Element___setstate__(PyObject *self,
PyTypeObject *cls, PyObject *c
PyDoc_STRVAR(_elementtree_Element_extend__doc__,
"extend($self, elements, /)\n"
"--\n"
-"\n");
+"\n"
+"Append subelements from a sequence.\n"
+"\n"
+"*elements* is a sequence with zero or more elements.");
#define _ELEMENTTREE_ELEMENT_EXTEND_METHODDEF \
{"extend", _PyCFunction_CAST(_elementtree_Element_extend),
METH_METHOD|METH_FASTCALL|METH_KEYWORDS, _elementtree_Element_extend__doc__},
@@ -258,7 +270,14 @@ _elementtree_Element_extend(PyObject *self, PyTypeObject
*cls, PyObject *const *
PyDoc_STRVAR(_elementtree_Element_find__doc__,
"find($self, /, path, namespaces=None)\n"
"--\n"
-"\n");
+"\n"
+"Find first matching element by tag name or path.\n"
+"\n"
+"*path* is a string having either an element tag or an XPath,\n"
+"*namespaces* is an optional mapping from namespace prefix to full\n"
+"name.\n"
+"\n"
+"Return the first matching element, or None if no element was found.");
#define _ELEMENTTREE_ELEMENT_FIND_METHODDEF \
{"find", _PyCFunction_CAST(_elementtree_Element_find),
METH_METHOD|METH_FASTCALL|METH_KEYWORDS, _elementtree_Element_find__doc__},
@@ -323,7 +342,17 @@ _elementtree_Element_find(PyObject *self, PyTypeObject
*cls, PyObject *const *ar
PyDoc_STRVAR(_elementtree_Element_findtext__doc__,
"findtext($self, /, path, default=None, namespaces=None)\n"
"--\n"
-"\n");
+"\n"
+"Find text for first matching element by tag name or path.\n"
+"\n"
+"*path* is a string having either an element tag or an XPath,\n"
+"*default* is the value to return if the element was not found,\n"
+"*namespaces* is an optional mapping from namespace prefix to full\n"
+"name.\n"
+"\n"
+"Return text content of first matching element, or default value if\n"
+"none was found. Note that if an element is found having no text\n"
+"content, the empty string is returned.");
#define _ELEMENTTREE_ELEMENT_FINDTEXT_METHODDEF \
{"findtext", _PyCFunction_CAST(_elementtree_Element_findtext),
METH_METHOD|METH_FASTCALL|METH_KEYWORDS, _elementtree_Element_findtext__doc__},
@@ -396,7 +425,14 @@ _elementtree_Element_findtext(PyObject *self, PyTypeObject
*cls, PyObject *const
PyDoc_STRVAR(_elementtree_Element_findall__doc__,
"findall($self, /, path, namespaces=None)\n"
"--\n"
-"\n");
+"\n"
+"Find all matching subelements by tag name or path.\n"
+"\n"
+"*path* is a string having either an element tag or an XPath,\n"
+"*namespaces* is an optional mapping from namespace prefix to full\n"
+"name.\n"
+"\n"
+"Returns list containing all matching elements in document order.");
#define _ELEMENTTREE_ELEMENT_FINDALL_METHODDEF \
{"findall", _PyCFunction_CAST(_elementtree_Element_findall),
METH_METHOD|METH_FASTCALL|METH_KEYWORDS, _elementtree_Element_findall__doc__},
@@ -461,7 +497,14 @@ _elementtree_Element_findall(PyObject *self, PyTypeObject
*cls, PyObject *const
PyDoc_STRVAR(_elementtree_Element_iterfind__doc__,
"iterfind($self, /, path, namespaces=None)\n"
"--\n"
-"\n");
+"\n"
+"Find all matching subelements by tag name or path.\n"
+"\n"
+"*path* is a string having either an element tag or an XPath,\n"
+"*namespaces* is an optional mapping from namespace prefix to full\n"
+"name.\n"
+"\n"
+"Return an iterable yielding all matching elements in document order.");
#define _ELEMENTTREE_ELEMENT_ITERFIND_METHODDEF \
{"iterfind", _PyCFunction_CAST(_elementtree_Element_iterfind),
METH_METHOD|METH_FASTCALL|METH_KEYWORDS, _elementtree_Element_iterfind__doc__},
@@ -526,7 +569,15 @@ _elementtree_Element_iterfind(PyObject *self, PyTypeObject
*cls, PyObject *const
PyDoc_STRVAR(_elementtree_Element_get__doc__,
"get($self, /, key, default=None)\n"
"--\n"
-"\n");
+"\n"
+"Get element attribute.\n"
+"\n"
+"Equivalent to attrib.get, but some implementations may handle this a\n"
+"bit more efficiently. *key* is what attribute to look for, and\n"
+"*default* is what to return if the attribute was not found.\n"
+"\n"
+"Returns a string containing the attribute value, or the default if\n"
+"attribute was not found.");
#define _ELEMENTTREE_ELEMENT_GET_METHODDEF \
{"get", _PyCFunction_CAST(_elementtree_Element_get),
METH_FASTCALL|METH_KEYWORDS, _elementtree_Element_get__doc__},
@@ -591,7 +642,19 @@ _elementtree_Element_get(PyObject *self, PyObject *const
*args, Py_ssize_t nargs
PyDoc_STRVAR(_elementtree_Element_iter__doc__,
"iter($self, /, tag=None)\n"
"--\n"
-"\n");
+"\n"
+"Create tree iterator.\n"
+"\n"
+"The iterator loops over the element and all subelements in document\n"
+"order, returning all elements with a matching tag.\n"
+"\n"
+"If the tree structure is modified during iteration, new or removed\n"
+"elements may or may not be included. To get a stable set, use the\n"
+"list() function on the iterator, and loop over the resulting list.\n"
+"\n"
+"*tag* is what tags to look for (default is to return all elements)\n"
+"\n"
+"Return an iterator containing all the matching elements.");
#define _ELEMENTTREE_ELEMENT_ITER_METHODDEF \
{"iter", _PyCFunction_CAST(_elementtree_Element_iter),
METH_METHOD|METH_FASTCALL|METH_KEYWORDS, _elementtree_Element_iter__doc__},
@@ -654,7 +717,11 @@ _elementtree_Element_iter(PyObject *self, PyTypeObject
*cls, PyObject *const *ar
PyDoc_STRVAR(_elementtree_Element_itertext__doc__,
"itertext($self, /)\n"
"--\n"
-"\n");
+"\n"
+"Create text iterator.\n"
+"\n"
+"The iterator loops over the element and all subelements in document\n"
+"order, returning all inner text.");
#define _ELEMENTTREE_ELEMENT_ITERTEXT_METHODDEF \
{"itertext", _PyCFunction_CAST(_elementtree_Element_itertext),
METH_METHOD|METH_FASTCALL|METH_KEYWORDS, _elementtree_Element_itertext__doc__},
@@ -675,7 +742,8 @@ _elementtree_Element_itertext(PyObject *self, PyTypeObject
*cls, PyObject *const
PyDoc_STRVAR(_elementtree_Element_insert__doc__,
"insert($self, index, subelement, /)\n"
"--\n"
-"\n");
+"\n"
+"Insert *subelement* at position *index*.");
#define _ELEMENTTREE_ELEMENT_INSERT_METHODDEF \
{"insert", _PyCFunction_CAST(_elementtree_Element_insert), METH_FASTCALL,
_elementtree_Element_insert__doc__},
@@ -720,7 +788,10 @@ _elementtree_Element_insert(PyObject *self, PyObject
*const *args, Py_ssize_t na
PyDoc_STRVAR(_elementtree_Element_items__doc__,
"items($self, /)\n"
"--\n"
-"\n");
+"\n"
+"Get element attributes as (name, value) pairs.\n"
+"\n"
+"Equivalent to attrib.items().");
#define _ELEMENTTREE_ELEMENT_ITEMS_METHODDEF \
{"items", (PyCFunction)_elementtree_Element_items, METH_NOARGS,
_elementtree_Element_items__doc__},
@@ -737,7 +808,10 @@ _elementtree_Element_items(PyObject *self, PyObject
*Py_UNUSED(ignored))
PyDoc_STRVAR(_elementtree_Element_keys__doc__,
"keys($self, /)\n"
"--\n"
-"\n");
+"\n"
+"Get attribute names.\n"
+"\n"
+"Equivalent to attrib.keys()");
#define _ELEMENTTREE_ELEMENT_KEYS_METHODDEF \
{"keys", (PyCFunction)_elementtree_Element_keys, METH_NOARGS,
_elementtree_Element_keys__doc__},
@@ -754,7 +828,14 @@ _elementtree_Element_keys(PyObject *self, PyObject
*Py_UNUSED(ignored))
PyDoc_STRVAR(_elementtree_Element_makeelement__doc__,
"makeelement($self, tag, attrib, /)\n"
"--\n"
-"\n");
+"\n"
+"Create a new element with the same type.\n"
+"\n"
+"*tag* is a string containing the element name. *attrib* is a\n"
+"dictionary containing the element attributes.\n"
+"\n"
+"Do not call this method, use the SubElement factory function\n"
+"instead.");
#define _ELEMENTTREE_ELEMENT_MAKEELEMENT_METHODDEF \
{"makeelement", _PyCFunction_CAST(_elementtree_Element_makeelement),
METH_METHOD|METH_FASTCALL|METH_KEYWORDS,
_elementtree_Element_makeelement__doc__},
@@ -804,7 +885,16 @@ _elementtree_Element_makeelement(PyObject *self,
PyTypeObject *cls, PyObject *co
PyDoc_STRVAR(_elementtree_Element_remove__doc__,
"remove($self, subelement, /)\n"
"--\n"
-"\n");
+"\n"
+"Remove matching subelement.\n"
+"\n"
+"Unlike the find methods, this method compares elements based on\n"
+"identity, NOT ON tag value or contents. To remove subelements by\n"
+"other means, the easiest way is to use a list comprehension to\n"
+"select what elements to keep, and then use slice assignment to\n"
+"update the parent element.\n"
+"\n"
+"ValueError is raised if a matching element could not be found.");
#define _ELEMENTTREE_ELEMENT_REMOVE_METHODDEF \
{"remove", (PyCFunction)_elementtree_Element_remove, METH_O,
_elementtree_Element_remove__doc__},
@@ -832,7 +922,12 @@ _elementtree_Element_remove(PyObject *self, PyObject *arg)
PyDoc_STRVAR(_elementtree_Element_set__doc__,
"set($self, key, value, /)\n"
"--\n"
-"\n");
+"\n"
+"Set element attribute.\n"
+"\n"
+"Equivalent to attrib[key] = value, but some implementations may\n"
+"handle this a bit more efficiently. *key* is what attribute to set,\n"
+"and *value* is the attribute value to set it to.");
#define _ELEMENTTREE_ELEMENT_SET_METHODDEF \
{"set", _PyCFunction_CAST(_elementtree_Element_set), METH_FASTCALL,
_elementtree_Element_set__doc__},
@@ -859,6 +954,30 @@ _elementtree_Element_set(PyObject *self, PyObject *const
*args, Py_ssize_t nargs
return return_value;
}
+PyDoc_STRVAR(_elementtree_TreeBuilder___init____doc__,
+"TreeBuilder(element_factory=None, *, comment_factory=None,\n"
+" pi_factory=None, insert_comments=False, insert_pis=False)\n"
+"--\n"
+"\n"
+"Generic element structure builder.\n"
+"\n"
+"This builder converts a sequence of start, data, and end method\n"
+"calls to a well-formed element structure.\n"
+"\n"
+"You can use this class to build an element structure using a custom\n"
+"XML parser, or a parser for some other XML-like format.\n"
+"\n"
+"*element_factory* is an optional element factory which is called\n"
+"to create new Element instances, as necessary.\n"
+"\n"
+"*comment_factory* is a factory to create comments to be used instead\n"
+"of the standard factory. If *insert_comments* is false (the\n"
+"default), comments will not be inserted into the tree.\n"
+"\n"
+"*pi_factory* is a factory to create processing instructions to be\n"
+"used instead of the standard factory. If *insert_pis* is false (the\n"
+"default), processing instructions will not be inserted into the tree.");
+
static int
_elementtree_TreeBuilder___init___impl(TreeBuilderObject *self,
PyObject *element_factory,
@@ -993,7 +1112,8 @@ _elementtree__set_factories(PyObject *module, PyObject
*const *args, Py_ssize_t
PyDoc_STRVAR(_elementtree_TreeBuilder_data__doc__,
"data($self, data, /)\n"
"--\n"
-"\n");
+"\n"
+"Add text to current element.");
#define _ELEMENTTREE_TREEBUILDER_DATA_METHODDEF \
{"data", (PyCFunction)_elementtree_TreeBuilder_data, METH_O,
_elementtree_TreeBuilder_data__doc__},
@@ -1014,7 +1134,10 @@ _elementtree_TreeBuilder_data(PyObject *self, PyObject
*data)
PyDoc_STRVAR(_elementtree_TreeBuilder_end__doc__,
"end($self, tag, /)\n"
"--\n"
-"\n");
+"\n"
+"Close and return current Element.\n"
+"\n"
+"*tag* is the element name.");
#define _ELEMENTTREE_TREEBUILDER_END_METHODDEF \
{"end", (PyCFunction)_elementtree_TreeBuilder_end, METH_O,
_elementtree_TreeBuilder_end__doc__},
@@ -1035,7 +1158,10 @@ _elementtree_TreeBuilder_end(PyObject *self, PyObject
*tag)
PyDoc_STRVAR(_elementtree_TreeBuilder_comment__doc__,
"comment($self, text, /)\n"
"--\n"
-"\n");
+"\n"
+"Create a comment using the comment_factory.\n"
+"\n"
+"*text* is the text of the comment.");
#define _ELEMENTTREE_TREEBUILDER_COMMENT_METHODDEF \
{"comment", (PyCFunction)_elementtree_TreeBuilder_comment, METH_O,
_elementtree_TreeBuilder_comment__doc__},
@@ -1057,7 +1183,11 @@ _elementtree_TreeBuilder_comment(PyObject *self,
PyObject *text)
PyDoc_STRVAR(_elementtree_TreeBuilder_pi__doc__,
"pi($self, target, text=None, /)\n"
"--\n"
-"\n");
+"\n"
+"Create a processing instruction using the pi_factory.\n"
+"\n"
+"*target* is the target name of the processing instruction. *text* is\n"
+"the data of the processing instruction, or \'\'.");
#define _ELEMENTTREE_TREEBUILDER_PI_METHODDEF \
{"pi", _PyCFunction_CAST(_elementtree_TreeBuilder_pi), METH_FASTCALL,
_elementtree_TreeBuilder_pi__doc__},
@@ -1091,7 +1221,8 @@ _elementtree_TreeBuilder_pi(PyObject *self, PyObject
*const *args, Py_ssize_t na
PyDoc_STRVAR(_elementtree_TreeBuilder_close__doc__,
"close($self, /)\n"
"--\n"
-"\n");
+"\n"
+"Flush builder buffers and return toplevel document Element.");
#define _ELEMENTTREE_TREEBUILDER_CLOSE_METHODDEF \
{"close", (PyCFunction)_elementtree_TreeBuilder_close, METH_NOARGS,
_elementtree_TreeBuilder_close__doc__},
@@ -1108,7 +1239,11 @@ _elementtree_TreeBuilder_close(PyObject *self, PyObject
*Py_UNUSED(ignored))
PyDoc_STRVAR(_elementtree_TreeBuilder_start__doc__,
"start($self, tag, attrs, /)\n"
"--\n"
-"\n");
+"\n"
+"Open new element and return it.\n"
+"\n"
+"*tag* is the element name, *attrs* is a dict containing element\n"
+"attributes.");
#define _ELEMENTTREE_TREEBUILDER_START_METHODDEF \
{"start", _PyCFunction_CAST(_elementtree_TreeBuilder_start),
METH_FASTCALL, _elementtree_TreeBuilder_start__doc__},
@@ -1139,6 +1274,17 @@ _elementtree_TreeBuilder_start(PyObject *self, PyObject
*const *args, Py_ssize_t
return return_value;
}
+PyDoc_STRVAR(_elementtree_XMLParser___init____doc__,
+"XMLParser(*, target=None, encoding=None)\n"
+"--\n"
+"\n"
+"Element structure builder for XML source data based on the expat parser.\n"
+"\n"
+"*target* is an optional target object which defaults to an instance\n"
+"of the standard TreeBuilder class, *encoding* is an optional encoding\n"
+"string which if given, overrides the encoding specified in the XML\n"
+"file: http://www.iana.org/assignments/character-sets";);
+
static int
_elementtree_XMLParser___init___impl(XMLParserObject *self, PyObject *target,
const char *encoding);
@@ -1223,7 +1369,8 @@ _elementtree_XMLParser___init__(PyObject *self, PyObject
*args, PyObject *kwargs
PyDoc_STRVAR(_elementtree_XMLParser_close__doc__,
"close($self, /)\n"
"--\n"
-"\n");
+"\n"
+"Finish feeding data to parser and return element structure.");
#define _ELEMENTTREE_XMLPARSER_CLOSE_METHODDEF \
{"close", (PyCFunction)_elementtree_XMLParser_close, METH_NOARGS,
_elementtree_XMLParser_close__doc__},
@@ -1257,7 +1404,8 @@ _elementtree_XMLParser_flush(PyObject *self, PyObject
*Py_UNUSED(ignored))
PyDoc_STRVAR(_elementtree_XMLParser_feed__doc__,
"feed($self, data, /)\n"
"--\n"
-"\n");
+"\n"
+"Feed encoded data to parser.");
#define _ELEMENTTREE_XMLPARSER_FEED_METHODDEF \
{"feed", (PyCFunction)_elementtree_XMLParser_feed, METH_O,
_elementtree_XMLParser_feed__doc__},
@@ -1331,4 +1479,4 @@ _elementtree_XMLParser__setevents(PyObject *self,
PyObject *const *args, Py_ssiz
exit:
return return_value;
}
-/*[clinic end generated code: output=c863ce16d8566291 input=a9049054013a1b77]*/
+/*[clinic end generated code: output=e2e9cf288c4400f6 input=a9049054013a1b77]*/
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]
