gh-151943: Document the CharacterData interface and other DOM members by serhiy-storchaka · Pull Request #155632 · python/cpython · GitHub

The CharacterData interface was not mentioned in the documentation at all, although Text, Comment and CDATASection inherit from it, so its length attribute and mutation methods were not documented.

Other implemented members which were omitted are documented too: Node.ownerDocument, Node.isSupported(), Node.getUserData(), Node.setUserData(), Document.doctype, Document.implementation, Document.documentURI, Document.strictErrorChecking, Document.createDocumentFragment(), Document.createCDATASection(), Document.importNode(), Document.renameNode(), Document.getElementById(), Element.setIdAttribute(), Element.setIdAttributeNS(), Element.setIdAttributeNode(), Attr.isId, Attr.ownerElement, Attr.specified, Text.wholeText, Text.splitText() and Text.replaceWholeText(), the getNamedItem*(), setNamedItem*() and removeNamedItem*() methods of NamedNodeMap, the DocumentFragment, Entity and Notation interfaces, the node type constants and the exception code constants.

Class directives are added for all documented interfaces, so that references to them resolve, and Doc/library/xml.dom.rst is removed from Doc/tools/.nitignore.

These points reported in gh-156388 are addressed:

which node types can have children, and children of which types;
the values of nodeName and nodeValue for every node type;
Node.childNodes is a NodeList;
NodeList does not inherit from Node;
NodeList.item() returns None for an index out of range, it does not forbid such index;
attribute nodes are not part of the document tree;
CDATASection extends Text, not CharacterData directly;
when DocumentType.publicId and DocumentType.systemId are None;
"minidom" is the only well-known implementation name;
nodeName is never None;
minidom specific differences are described in the minidom documentation: each of the NodeList and NamedNodeMap interfaces has two implementations, and the operations they support differ.

Issue: [xml.dom] The CharacterData interface and other members are not documented #155631

Issue: Fix all Sphinx reference warnings in Doc/library/{xml*,pyexpat}.rst #151943

Issue: xml.dom docs are missing important information necessary for usage #156388

…embers CharacterData was not mentioned at all, although Text, Comment and CDATASection inherit from it. Also document members which are implemented, but were omitted: Node.ownerDocument, Node.isSupported(), Node.getUserData(), Node.setUserData(), Document.doctype, Document.implementation, Document.documentURI, Document.strictErrorChecking, Document.createDocumentFragment(), Document.createCDATASection(), Document.importNode(), Document.renameNode(), Element.setIdAttribute(), Element.setIdAttributeNS(), Element.setIdAttributeNode(), Attr.isId, Attr.ownerElement, Text.wholeText, Text.splitText() and Text.replaceWholeText().

Documentation build overview

📚 cpython-previews | 🛠️ Build #34272182 | 📁 Comparing b92b565 against main (b11e749)

🔍 Preview build

61 files changed · + 1 added · ± 60 modified

+ Added

library/time-complexity.html

± Modified

…Map methods Add class directives for all documented DOM classes, so that references to them resolve. They use :no-typesetting:, because the classes are not instantiated directly and the sections already introduce them. Add a section for DocumentFragment, which was referenced, but had no section of its own, and document Document.getElementById() and the getNamedItem(), setNamedItem() and removeNamedItem() families of NamedNodeMap, which are implemented, but were omitted. Silence references to the illustrative names in the IDL mapping example and to the PYTHON_DOM environment variable.

…bers The node type constants and the exception code constants were referenced, but never documented. Document them, including ENTITY_REFERENCE_NODE, DOCUMENT_FRAGMENT_NODE and VALIDATION_ERR, which were not even mentioned, and the ValidationErr exception. Qualify references to attributes and methods with the class which defines them, so that they resolve, and refer to xml.dom.minidom for unlink(), which is not part of the DOM.

It no longer produces warnings in the Sphinx nit-picky mode.

….specified Entity and Notation were not mentioned at all, although they are implemented and DocumentType.entities and DocumentType.notations contain such nodes.

Co-authored-by: dgelessus <dgelessus@users.noreply.github.com>

…Attr CDATASection extends Text, as in the DOM Level 1 and Level 2 IDL. NodeList.item() returns None for an index out of range, it does not forbid such index. Attribute nodes are not part of the document tree.

Reported in pythongh-156388: * which node types can have children, and of which types; * the values of nodeName and nodeValue for every node type; * childNodes is a NodeList; * NodeList does not inherit from Node; * when DocumentType.publicId and systemId are None; * "minidom" is the only well-known implementation name; * which mapping methods minidom adds to a NamedNodeMap, and where they are not available.

It is a list subclass, not a replacement for NodeList, and nodes which cannot have children use a tuple subclass. Remove the note about earlier versions of Python which did not support the official API.

The table above gives the value for every node type, and none of them is None.

…nd NEWS Suggested by dgelessus in the review of pythonGH-155632, where the same wording was used.

I applied suggestions and addressed more points from #156388.

… docs Each of the NodeList and NamedNodeMap interfaces has two implementations in minidom, which support additional operations. Move this and the notes about strictErrorChecking and Attr.specified out of the documentation of the generic DOM interface.

Thanks @serhiy-storchaka for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14, 3.15.
🐍🍒⛏🤖

GH-156632 is a backport of this pull request to the 3.15 branch.

GH-156633 is a backport of this pull request to the 3.14 branch.

GH-156634 is a backport of this pull request to the 3.13 branch.

…members (GH-155632) (GH-156633) CharacterData was not mentioned at all, although Text, Comment and CDATASection inherit from it. Document also DocumentFragment, Entity and Notation, many implemented members which were omitted, the node type constants and the exception code constants. Add class directives for all documented interfaces, so that references to them resolve, and remove xml.dom.rst from the nit-picky mode exceptions. Fix incorrect statements about nodeName, NodeList.item(), CDATASection and attribute nodes, and describe minidom specific differences in the minidom documentation. (cherry picked from commit 922c866) Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>

…members (GH-155632) (GH-156634) CharacterData was not mentioned at all, although Text, Comment and CDATASection inherit from it. Document also DocumentFragment, Entity and Notation, many implemented members which were omitted, the node type constants and the exception code constants. Add class directives for all documented interfaces, so that references to them resolve, and remove xml.dom.rst from the nit-picky mode exceptions. Fix incorrect statements about nodeName, NodeList.item(), CDATASection and attribute nodes, and describe minidom specific differences in the minidom documentation. (cherry picked from commit 922c866) Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>

…members (GH-155632) (#156632) Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>

…embers (pythonGH-155632) CharacterData was not mentioned at all, although Text, Comment and CDATASection inherit from it. Document also DocumentFragment, Entity and Notation, many implemented members which were omitted, the node type constants and the exception code constants. Add class directives for all documented interfaces, so that references to them resolve, and remove xml.dom.rst from the nit-picky mode exceptions. Fix incorrect statements about nodeName, NodeList.item(), CDATASection and attribute nodes, and describe minidom specific differences in the minidom documentation.

bedevere-app Bot added docs Documentation in the Doc dir skip news labels Aug 12, 2026

github-project-automation Bot added this to Docs PRs Aug 12, 2026

bedevere-app Bot mentioned this pull request Aug 12, 2026

[xml.dom] The CharacterData interface and other members are not documented #155631

Closed

bedevere-app Bot added the awaiting core review label Aug 12, 2026

github-project-automation Bot moved this to Todo in Docs PRs Aug 12, 2026

serhiy-storchaka added needs backport to 3.13 only security fixes needs backport to 3.14 bugs and security fixes needs backport to 3.15 bugs and security fixes labels Aug 12, 2026

serhiy-storchaka added 3 commits August 12, 2026 19:59

pythongh-155631 : Remove xml.dom.rst from the nit-picky mode exceptions

cef4943

It no longer produces warnings in the Sphinx nit-picky mode.

serhiy-storchaka requested review from AA-Turner, StanFromIreland and hugovk as code owners August 12, 2026 17:37

pythongh-155631 : Document the Entity and Notation interfaces and Attr…

9e94614

….specified Entity and Notation were not mentioned at all, although they are implemented and DocumentType.entities and DocumentType.notations contain such nodes.

StanFromIreland changed the title gh-155631: Document the CharacterData interface and other DOM members gh-151943: Document the CharacterData interface and other DOM members Aug 12, 2026

bedevere-app Bot mentioned this pull request Aug 12, 2026

Fix all Sphinx reference warnings in Doc/library/{xml*,pyexpat}.rst #151943

Open

serhiy-storchaka mentioned this pull request Aug 27, 2026

xml.dom docs are missing important information necessary for usage #156388

Open

16 of 19 tasks

dgelessus reviewed Aug 27, 2026

View reviewed changes

Comment thread Doc/library/xml.dom.rst Outdated

Comment thread Doc/library/xml.dom.rst Outdated

Comment thread Doc/library/xml.dom.rst Outdated

serhiy-storchaka and others added 5 commits August 28, 2026 09:27

Apply batched suggestions from code review

af7e732

Co-authored-by: dgelessus <dgelessus@users.noreply.github.com>

pythongh-151943 : Fix the documentation of CDATASection, NodeList and …

28dcdee

…Attr CDATASection extends Text, as in the DOM Level 1 and Level 2 IDL. NodeList.item() returns None for an index out of range, it does not forbid such index. Attribute nodes are not part of the document tree.

pythongh-151943 : Clarify how minidom implements NodeList

d67e631

It is a list subclass, not a replacement for NodeList, and nodes which cannot have children use a tuple subclass. Remove the note about earlier versions of Python which did not support the official API.

pythongh-151943 : Do not claim that nodeName can be None

7fa7f46

The table above gives the value for every node type, and none of them is None.

serhiy-storchaka added a commit to serhiy-storchaka/cpython that referenced this pull request Aug 28, 2026

pythongh-44871 : Say "created by another document" in the What's New a…

d9a6005

…nd NEWS Suggested by dgelessus in the review of pythonGH-155632, where the same wording was used.

serhiy-storchaka merged commit 922c866 into python:main Aug 30, 2026
30 checks passed

github-project-automation Bot moved this from Todo to Done in Docs PRs Aug 30, 2026

bedevere-app Bot removed the awaiting core review label Aug 30, 2026

serhiy-storchaka deleted the doc-characterdata branch August 30, 2026 08:17

bedevere-app Bot removed the needs backport to 3.15 bugs and security fixes label Aug 30, 2026

bedevere-app Bot removed the needs backport to 3.14 bugs and security fixes label Aug 30, 2026

bedevere-app Bot removed the needs backport to 3.13 only security fixes label Aug 30, 2026

hugovk pushed a commit that referenced this pull request Aug 30, 2026

[3.15] gh-151943 : Document the CharacterData interface and other DOM …

3fc79f7

…members (GH-155632) (#156632) Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>

gh-151943: Document the CharacterData interface and other DOM members by serhiy-storchaka · Pull Request #155632 · python/cpython · GitHub

Repository navigation

gh-151943: Document the CharacterData interface and other DOM members - #155632

gh-151943: Document the CharacterData interface and other DOM members#155632
serhiy-storchaka merged 11 commits into
python:mainfrom
serhiy-storchaka:doc-characterdata

serhiy-storchaka commented Aug 12, 2026 •
edited
Loading

Uh oh!

Uh oh!

read-the-docs-community Bot commented Aug 12, 2026 •
edited
Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

serhiy-storchaka commented Aug 28, 2026

Uh oh!

Uh oh!

miss-islington-app Bot commented Aug 30, 2026

Uh oh!

bedevere-app Bot commented Aug 30, 2026

Uh oh!

bedevere-app Bot commented Aug 30, 2026

Uh oh!

bedevere-app Bot commented Aug 30, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

gh-151943: Document the CharacterData interface and other DOM members by serhiy-storchaka · Pull Request #155632 · python/cpython · GitHub

Repository navigation

gh-151943: Document the CharacterData interface and other DOM members - #155632

gh-151943: Document the CharacterData interface and other DOM members#155632serhiy-storchaka merged 11 commits intopython:mainpython/cpython:mainfrom serhiy-storchaka:doc-characterdataserhiy-storchaka/cpython:doc-characterdataCopy head branch name to clipboard

Conversation

serhiy-storchaka commented Aug 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

read-the-docs-community Bot commented Aug 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

serhiy-storchaka commented Aug 28, 2026

Uh oh!

Uh oh!

miss-islington-app Bot commented Aug 30, 2026

Uh oh!

bedevere-app Bot commented Aug 30, 2026

Uh oh!

bedevere-app Bot commented Aug 30, 2026

Uh oh!

bedevere-app Bot commented Aug 30, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

gh-151943: Document the CharacterData interface and other DOM members#155632
serhiy-storchaka merged 11 commits into
python:mainfrom
serhiy-storchaka:doc-characterdata

serhiy-storchaka commented Aug 12, 2026 •
edited
Loading

read-the-docs-community Bot commented Aug 12, 2026 •
edited
Loading