gh-126615: Add COMError to ctypes doc.
#126686
Conversation
bedevere-app
bot
added
docs
ZeroIntensity
added
topic-ctypes
needs backport to 3.12
junkmd
force-pushed
the
gh_126615_comerror_doc
branch
from
58cc032
to
90fb47f
Compare
Doc/library/ctypes.rst
Outdated
|
|
||
| .. exception:: COMError(hresult, text, details) | ||
|
|
||
| Windows only: This non-public exception is raised when a COM method call |
There was a problem hiding this comment.
You can use .. availability:: Windows (but put the directive after the class doc)
There was a problem hiding this comment.
I followed the pattern in ctypes.rst because it frequently used sentences like Windows only: ....
Since this markup wasn't mentioned in the documentation guide, I overlooked it.
Is this a more modern approach?
There was a problem hiding this comment.
It's widely used in the https://docs.python.org/3/library/socket.html module actually. But if it's not the pattern of ctypes maybe it's better to be consistent. We can make a follow-up PR to transform them into directives.
There was a problem hiding this comment.
I removed the Availability directive and reverted to the original "Windows only: ...".
Once this PR is merged, I would like to work for replacing "Foo only: ..." with the .. availability:: Foo directive.
There was a problem hiding this comment.
Referring to the socket.ioctl documentation, it seems that using :platform: Windows might be more appropriate than .. availability:: Windows. What do you think?
Alternatively, could it be that :platform: is intended to be used exclusively in module sections, as described in the documentation guide's "Module-specific markup"?
Doc/library/ctypes.rst
Outdated
| COM methods use a special calling convention: They require a pointer to | ||
| the COM interface as first argument, in addition to those parameters that | ||
| are specified in the :attr:`!argtypes` tuple. | ||
|
|
||
|
|
||
| .. exception:: COMError(hresult, text, details) |
There was a problem hiding this comment.
Should it be placed here or somewhere else? because it cuts the flow of the reading where paramflags is documented afterwards. Maybe we can put it before the functions?
There was a problem hiding this comment.
I was also unsure whether this was the right place to put it.
On the other hand, placing it above prototype or above FOOFUNCTYPE might seem abrupt.
Might it be appropriate to create the Exceptions section, including ArgumentError?
However, in this scope, I think making such a change that involves the "Foreign functions" section is excessive.
There was a problem hiding this comment.
Well.. honestly I think it makes sense to put it in an exception section. I think it could be fine for this small docs change (I mean, it's for our own convenience). We can ask @hugovk as a docs expert.
There was a problem hiding this comment.
Yes, we often have an exceptions section further down, see for example:
There was a problem hiding this comment.
If the community agrees, creating an "Exceptions" section is no problem at all.
For now, I think I'll try placing it at the end of the document, after the "Arrays and pointers" section.
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
Doc/library/ctypes.rst
Outdated
| @@ -1799,10 +1799,32 @@ different ways, depending on the type and number of the parameters in the call: | |||
| integer. *name* is name of the COM method. *iid* is an optional pointer to | |||
| the interface identifier which is used in extended error reporting. | |||
|
|
|||
| If *iid* is not specified, a :exc:`WindowsError` is raised if the COM method | |||
| call fails. If *iid* is specified, a :exc:`COMError` is raised instead. | |||
There was a problem hiding this comment.
Err... I wonder why the reference is not picked up here, because the class is documented. (May be a Sphinx issue?) Sorry, but you'll need the .COMError as before (my bad...)
There was a problem hiding this comment.
It has become harder to see after the rebase, but in the earlier commit without the dot, "Tests / Docs / Docs (pull_request)" failed in CI.
In contrast, the commit with the dot succeeded.
Additionally, without the dot, no link was generated.
I think also it's probably an issue with Sphinx.
There was a problem hiding this comment.
Additionally, without the dot, no link was generated.
That's because it couldn't find the reference. I'm wondering whether it couldn't find the reference because the exception is documented after or because of how it's declared (it might also happen that the module's scope was changed somewhere)
in order to maintain consistency with other sections.
Please refer also to gh-126384 and gh-126610 for the behavior when a foreign function fails to call a COM method.
COMErrorin the "Function prototypes" section ofctypesdocumentation. #126615📚 Documentation preview 📚: https://cpython-previews--126686.org.readthedocs.build/