Repository navigation
Update xml.etree.ElementTree docs to make clear the module is not deprecated #128805
Description
Documentation
"The xml.etree.cElementTree module is deprecated" notice is confusing.
On https://docs.python.org/3.14/library/xml.etree.elementtree.html it states that:
Deprecated since version 3.3: The xml.etree.cElementTree module is deprecated.
As I have not used ElementTree before, I initially thought that the xml.etree.ElementTree module is deprecated. After digging it into, I'm about 70% sure that's not the case. It sounds like there is alias for it named cElementTree and this alias is deprecated. That is quite a bit different!
I suggest updating the wording to say something to the effect of "This module is also available under the alias cElementTree, but this alias has been deprecated since 3.3, please use ElementTree instead."
Why it's confusing:
There are not any other mentions of "cElementTree" on that page. I don't really know what cElementTree is and how it differs from ElementTree. My initial thinking was that it was either a typo, or that it is the implementation of ElementTree (and that its deprecation also deprecates ElementTree). Or maybe just what Python devs call it internally.
Also, if you put "is elementtree deprecated?" into google, the AI says:
Deprecated since version 3.3: The xml.etree.cElementTree module is deprecated. The xml.etree.ElementTree module is not secure against maliciously constructed data. If you need to parse untrusted or unauthenticated data see XML vulnerabilities.
That also makes it sound like it is deprecated. (Some of the actual search results do say what is going on.)
Finally, since the Python stdlib has a handful XML parsers available, the idea that one or more would be deprecated (and replaced by the others) seemed very plausible.
Related:
Related to #84246 but that issue is about removing the deprecation notice all together, because the alias was removed, but then added back again, so now that issue is in limbo. That issue doesn't talk about the confusing wording, so I don't believe I am creating a duplicate. (Though removing the deprecation notice would also solve this issue, but it sounds like that isn't going to happen.)
Linked PRs
- gh-128805: Clarify cElementTree deprecation notice #144459
- gh-128805: Clarify the deprecation notice of xml.etree.cElementTree #156779
- [3.15] gh-128805: Clarify the deprecation notice of xml.etree.cElementTree (GH-156779) #156883
- [3.14] gh-128805: Clarify the deprecation notice of xml.etree.cElementTree (GH-156779) #156884
- [3.13] gh-128805: Clarify the deprecation notice of xml.etree.cElementTree (GH-156779) #156885
Activity
picnixz commentedon Jan 14, 2025
That's not a CPython issue IMO. It's an issue with the fact that Google does not catch that these are two separate paragraphs.
The
cElementTreemodule was the accelerated C element tree module and could be directly available. Before, it was different fromElementTreewhich was in pure Python (it's still in pure Python but if a C acclerator module exists, then it will use it).Since the alias is a module, I'd say it's correct to say that
xml.etree.cElementTreeis deprecated. So strictly speaking, the notice is not incorrect. However, we can make it more explicit as you suggested.cc @serhiy-storchaka
tringenbach commentedon Jan 14, 2025
Thanks!
Perhaps part of the problem is that the notice is in the wrong place. I would expect it to be on the documentation for the
cElementTreealias. Except that there is no documentation for that alias. Instead it's at the top of the not deprecatedElementTreemodule.picnixz commentedon Jan 14, 2025
Since this would be an overkill to have a page for a deprecated module, it was probably decided to keep it at the top. However, if you want to write a PR that amends the deprecation notice, I think it could be worth it. Considering that we decided to deprecate and not remove the
cElementTreemodule, we could assume that there are still users that knowcElementTreebut notElementTreeitself.LeonxLJX commentedon Sep 3, 2026
I'd like to take this one.
Reading the issue, this looks like a documentation-clarity gap rather than a code defect: the current page doesn't give readers enough to self-diagnose, which is why it surfaces here as an issue instead of being answered by the docs.
Plan: locate the relevant section, confirm what the code actually does today (so the docs match behavior, not intent), tighten the wording, and scan neighboring pages for the same inconsistency — otherwise the fix just relocates the confusion.
One thing to confirm before writing: minimal correction scoped to this page, or also cross-link from related guides if the same gap shows up there?
(claiming via @LeonxLJX)
serhiy-storchaka commentedon Sep 3, 2026
@LeonxLJX Please, read the issue before posting such comments. There is already a PR.
So, please avoid posting LLM generated comments which simply reiterate what was said.
gh-128805: Clarify the deprecation notice of xml.etree.cElementTree (G…
[3.13] gh-128805: Clarify the deprecation notice of xml.etree.cElemen…
[3.14] gh-128805: Clarify the deprecation notice of xml.etree.cElemen…
[3.15] gh-128805: Clarify the deprecation notice of xml.etree.cElemen…
pythongh-128805: Clarify the deprecation notice of xml.etree.cElement…