gh-89554: Document socket, thread and expat type objects as classes

[gaborbernat]

socket.SocketType, _thread.LockType, and xml.parsers.expat.XMLParserType are classes (the type objects for socket, lock, and expat parser objects), but the documentation marks them with the .. data:: directive, so :class: cross-references to them cannot resolve against a py:class target.

Switch these three entries to .. class::.

Refs: gh-89554. Documentation-only change, so no Misc/NEWS entry (skip news).

These files are not covered by CODEOWNERS, so cc @vstinner (socket and _thread) and @picnixz (pyexpat), who review most changes to these modules.

[picnixz]

Please, don't create a PR. We already did so for PyExpat but the problem is the name of the class and for now we gave up. And if you want to document the others, you need to open separate PRs.

[gaborbernat]

We already did so for PyExpat but the problem is the name of the class and for now we gave up.

Can you expand on why?

[gaborbernat]

Thanks, that makes sense. I have closed this and split it into separate PRs: #150683 for socket.SocketType and #150684 for _thread.LockType. I left XMLParserType out given the existing PyExpat work and the open question on the class name.

[picnixz]

Can you expand on why?

At runtime, the name of the class is xmlparser:

>>>pyexpat.ParserCreate()
<pyexpat.xmlparserobjectat0x0000026B96F1AC70>

and xml.parsers.expat.XMLParserType is exposed as:

cpython/Modules/pyexpat.c

Lines 2445 to 2447 in 2f8f569

	if (PyModule_AddObjectRef(mod, "XMLParserType",
	(PyObject*) state->xml_parse_type) <0) {
	return-1;

So, if we now change to class, users may be confused because the name of the class is not XMLParserType but xmlparser. And changing the C name is also not preferrable as it could break pickle or other things relying on it.

The issue is #140771. And we still don't know what to do with it.

Note that changing the directives will make packages relying on intersphinx broken and this will break all links. I don't know how we can mitigate this (i.e. using :data:[...] will no longer work and for people building docs with errors, this will break them hard).

[vstinner]

Is it a problem to document socket.SocketType and `_thread.LockType

>>> import socket
>>> socket.SocketType
<class '_socket.socket'>
>>> import _thread
>>> _thread.LockType
<class '_thread.lock'>

The two types are already documented at:

• https://docs.python.org/dev/library/socket.html#socket.SocketType
• https://docs.python.org/dev/library/_thread.html#thread.LockType

[vstinner]

I have closed this and split it into separate PRs: #150683 for socket.SocketType and #150684 for _thread.LockType.

Oops, I missed that. Thanks I will follow-up in these PRs.