GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — gh-151943: Document the CharacterData interface and other DOM members by serhiy-storchaka · Pull Request #155632 · python/cpython

Conversation

@serhiy-storchaka

@serhiy-storchaka serhiy-storchaka commented Aug 12, 2026 •
edited
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Member

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

dgelessus reacted with thumbs up emoji
All reactions
  • 👍 1 reaction
@serhiy-storchaka
pythongh-155631: Document the CharacterData interface and other DOM m…
dcbb0fb
…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().
@bedevere-app bedevere-app Bot added docs Documentation in the Doc dir skip news labels Aug 12, 2026
@github-project-automation github-project-automation Bot added this to Docs PRs Aug 12, 2026
@bedevere-app 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 bedevere-app Bot added the awaiting core review label Aug 12, 2026
@github-project-automation github-project-automation Bot moved this to Todo in Docs PRs Aug 12, 2026
@serhiy-storchaka 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
@read-the-docs-community

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

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown

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

  • glossary.html
  • c-api/import.html
  • extending/extending.html
  • faq/design.html
  • faq/programming.html
  • library/annotationlib.html
  • library/asyncio-stream.html
  • library/asyncio-subprocess.html
  • library/asyncio-task.html
  • library/audit_events.html
  • and 50 more...
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

serhiy-storchaka added 3 commits August 12, 2026 19:59
@serhiy-storchaka
pythongh-155631: Document the classes, DocumentFragment and NamedNode…
363e3cc
…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.
@serhiy-storchaka
pythongh-155631: Document the DOM constants and fix references to mem…
22cf801
…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.
@serhiy-storchaka
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
serhiy-storchaka requested review from AA-Turner, StanFromIreland and hugovk as code owners August 12, 2026 17:37
@serhiy-storchaka
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 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 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 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
dgelessus reviewed Aug 27, 2026
View reviewed changes
Comment thread Doc/library/xml.dom.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.

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

Uh oh!

There was an error while loading. Please reload this page.

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

Uh oh!

There was an error while loading. Please reload this page.

serhiy-storchaka and others added 5 commits August 28, 2026 09:27
@serhiy-storchaka @dgelessus
Apply batched suggestions from code review
af7e732
Co-authored-by: dgelessus <[email protected]>
@serhiy-storchaka
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.
@serhiy-storchaka
pythongh-151943: Document more details of the DOM interfaces
e48c25e
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.
@serhiy-storchaka
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.
@serhiy-storchaka
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
@serhiy-storchaka
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

serhiy-storchaka commented Aug 28, 2026

Copy link
Copy Markdown
Member Author

I applied suggestions and addressed more points from #156388.

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@serhiy-storchaka
pythongh-151943: Document minidom specific differences in the minidom…
b92b565
… 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.
@serhiy-storchaka
serhiy-storchaka merged commit 922c866 into python:main Aug 30, 2026
30 checks passed

Uh oh!

There was an error while loading. Please reload this page.

@github-project-automation github-project-automation Bot moved this from Todo to Done in Docs PRs Aug 30, 2026
@bedevere-app bedevere-app Bot removed the awaiting core review label Aug 30, 2026
@miss-islington-app

miss-islington-app Bot commented Aug 30, 2026

Copy link
Copy Markdown

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

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

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

bedevere-app Bot commented Aug 30, 2026

Copy link
Copy Markdown

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

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

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

bedevere-app Bot commented Aug 30, 2026

Copy link
Copy Markdown

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

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

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

bedevere-app Bot commented Aug 30, 2026

Copy link
Copy Markdown

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

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@bedevere-app bedevere-app Bot removed the needs backport to 3.13 only security fixes label Aug 30, 2026
serhiy-storchaka added a commit that referenced this pull request Aug 30, 2026
@miss-islington @serhiy-storchaka
[3.14] gh-151943: Document the CharacterData interface and other DOM …
acc9a22
…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 <[email protected]>
serhiy-storchaka added a commit that referenced this pull request Aug 30, 2026
@miss-islington @serhiy-storchaka
[3.13] gh-151943: Document the CharacterData interface and other DOM …
21f5c44
…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 <[email protected]>
hugovk pushed a commit that referenced this pull request Aug 30, 2026
@miss-islington @serhiy-storchaka
[3.15] gh-151943: Document the CharacterData interface and other DOM …
3fc79f7
…members (GH-155632) (#156632)

Co-authored-by: Serhiy Storchaka <[email protected]>
clin1234 pushed a commit to clin1234/cpython that referenced this pull request Sep 12, 2026
@serhiy-storchaka @clin1234
pythongh-151943: Document the CharacterData interface and other DOM m…
2df0566
…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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@AA-Turner AA-Turner Awaiting requested review from AA-Turner AA-Turner is a code owner
@hugovk hugovk Awaiting requested review from hugovk hugovk is a code owner
@StanFromIreland StanFromIreland Awaiting requested review from StanFromIreland StanFromIreland is a code owner
1 more reviewer
@dgelessus dgelessus dgelessus left review comments
Reviewers whose approvals may not affect merge requirements

Uh oh!

There was an error while loading. Please reload this page.

Assignees

No one assigned

Labels

docs Documentation in the Doc dir skip news

Projects

Docs PRs
Status: Done

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Uh oh!

There was an error while loading. Please reload this page.

2 participants

@serhiy-storchaka @dgelessus
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.