Reformat paragraphs, add backquotes, and add directives to (parts of) ctypes doc.

[junkmd]

In gh-127099, I reverted the reformatting paragraphs, leaving the lines in an unorganized state.

I noticed that in the recent documentation, certain parts that should be enclosed in backquotes or use directives were not properly formatted in the ctypes documentation.

I found similar parts in other sections, but for now, I focused on improving only the sections related to gh-127099.

---

📚 Documentation preview 📚: https://cpython-previews--127210.org.readthedocs.build/

[StanFromIreland]

Good consistency changes.

[encukou]

Thanks.
For the record: if the lines are shorter than 80 characters, it's not necessary to do any line-wrapping. It's OK to do it as part of a bigger change, though.

Small changes add noise to Git history, and more importantly, any change means the text needs to be re-translated for non-English versions of the docs. (It will appear in English before it's re-translated, see for example Japanese).

So, I'd like to ask: would you be willing to improve this documentation even more? As a maintainer of a major COM library, you are probably the best person to add things like:

• Stable links to official DllCanUnloadNow & DllGetClassObject documentation
• Correct documentation for the arguments and return values (including, for example, how to return a S_FALSE from Python -- if we even have public API for that).

[encukou]

Suggested change

	specified, the last error code is used by calling the Windows api function
	specified, the last error code is used by calling the Windows API function

[encukou]

Since Python 3.3 merged WindowsError into OSError, this is no longer the worst-named thing in ctypes (if it ever was) :)
And the negativity isn't helping anyone.

Suggested change

	This function is probably the worst-named thing in ``ctypes``. It creates an
	instance of :exc:`OSError`. If *code* is not specified, :func:`GetLastError`
	is called to determine the error code. If *descr* is not specified,
	:func:`FormatError` is called to get a textual description of the error.
	Creates an
	instance of :exc:`OSError`. If *code* is not specified, :func:`GetLastError`
	is called to determine the error code. If *descr* is not specified,
	:func:`FormatError` is called to get a textual description of the error.

[junkmd]

would you be willing to improve this documentation even more?

Sure. This documentation contains dozens of "ctypes" without backquotes. Should those also be included in this PR? <- edited: Considering the impact on documentation in languages other than English, I reconsidered and decided against adding a large number of backquotes.

• Correct documentation for the arguments and return values (including, for example, how to return a S_FALSE from Python -- if we even have public API for that).

I’m currently looking for appropriate examples. I’ll mention you once the sentence is finalized. Please give me some time.

[junkmd]

ctypes.DllCanUnloadNow calls the DllCanUnloadNow function from comtypes.

cpython/Lib/ctypes/__init__.py

Lines 574 to 579 in 2b0e2b2

	def DllCanUnloadNow():
	try:
	ccom = __import__("comtypes.server.inprocserver", globals(), locals(), ['*'])
	except ImportError:
	return 0 # S_OK
	return ccom.DllCanUnloadNow()

Similarly, ctypes.DllGetClassObject calls the DllGetClassObject function from comtypes.

cpython/Lib/ctypes/__init__.py

Lines 566 to 572 in 2b0e2b2

	def DllGetClassObject(rclsid, riid, ppv):
	try:
	ccom = __import__("comtypes.server.inprocserver", globals(), locals(), ['*'])
	except ImportError:
	return -2147221231 # CLASS_E_CLASSNOTAVAILABLE
	else:
	return ccom.DllGetClassObject(rclsid, riid, ppv)

It seems that for many years, there has been this state where the standard library ctypes depends on the third-party comtypes.

In fact, I have never directly called these functions myself. I am currently investigating how they behave in Python.

Depending on the results of my investigation, I may open an issue regarding these two functions and possibly revert the documentation changes related to them in this PR.

[encukou]

Oh. I should have checked the implementation!

IMO, we should deprecate those, tell people to import them from comtypes.server.inprocserver instead, and plan to remove them around Python 3.18. Ideally, you'd document them in comtypes instead :)
Would you be OK with that? If so I can write the PR for it.

[junkmd]

IMO, we should deprecate those, tell people to import them from comtypes.server.inprocserver instead, and plan to remove them around Python 3.18. Ideally, you'd document them in comtypes instead :)
Would you be OK with that? If so I can write the PR for it.

I have no objections to deprecating these APIs in ctypes.
Since this is neither an internal nor a small change, I believe it would also be necessary to open an issue.
I would appreciate it if you do that.

On the other hand, I haven’t been able to find any use cases where these functions are called directly.
While I have used the client-side functionality of comtypes, I have rarely utilized the server-side.
As a result, I am unsure how to approach documenting or testing these functions within comtypes.

I think it would be helpful if we could create a flow where developers who see the warning message triggered by calling these functions reach out to the maintainers of ctypes or comtypes and share their use cases.

[junkmd]

For now, I have reverted the documentation for DllCanUnloadNow and DllGetClassObject in this PR.

[junkmd]

It might be worth considering gathering opinions not only through this PR and issue but also on Discourse.

[junkmd]

Thank you for merging this.

I am compiling the current state of comtypes and my thoughts in preparation for the discussion in #127369.

Please wait a little.