Update `xml.etree.ElementTree` docs to make clear the module is not deprecated

[tringenbach]

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.)

[picnixz]

Also, if you put "is elementtree deprecated?" into google, the AI says:

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.

I don't really know what cElementTree is and how it differs from ElementTree.

The cElementTree module was the accelerated C element tree module and could be directly available. Before, it was different from ElementTree which was in pure Python (it's still in pure Python but if a C acclerator module exists, then it will use it).

It sounds like there is alias for it named cElementTree and this alias is deprecated. That is quite a bit different!

Since the alias is a module, I'd say it's correct to say that xml.etree.cElementTree is deprecated. So strictly speaking, the notice is not incorrect. However, we can make it more explicit as you suggested.

cc @serhiy-storchaka

[tringenbach]

Since the alias is a module, I'd say it's correct to say that xml.etree.cElementTree is deprecated. So strictly speaking, the notice is not incorrect. However, we can make it more explicit as you suggested.

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 cElementTree alias. Except that there is no documentation for that alias. Instead it's at the top of the not deprecated ElementTree module.

[picnixz]

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 cElementTree module, we could assume that there are still users that know cElementTree but not ElementTree itself.