René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"`ctypes`: Make `COMError`, mentioned in the \"Function prototypes\" section of documentation, public.","articleBody":"# Documentation\r\n\r\nI have been part of a project that handles COM with Python for several years now.\r\n\r\nWhen I first joined the project, `_ctypes.COMError` was a \"mysterious error\" to me. \r\n\r\nOver time, by implementing error handling within that project, contributing to [`comtypes`](https://github.com/enthought/comtypes/), and [adding `_ctypes.pyi` to typeshed](https://github.com/python/typeshed/pull/8582), I deepened my understanding of this error.\r\nYet, I always wondered why `ctypes` documentation never mentioned `COMError`.\r\n\r\nWhile reading through the function prototype section and working on gh-126384 and gh-126610, I realized that the section on \"extended error reporting\" may have implied `COMError`.\r\n\r\nhttps://github.com/python/cpython/blob/6293d00e7201f3f28b1f4512e57dc4f03855cabd/Doc/library/ctypes.rst?plain=1#L1793-L1800\r\n\r\n- If a foreign function generated from a function prototype without passing an `iid` fails to call a COM method, a [`WindowsError`](https://docs.python.org/3/library/exceptions.html#WindowsError) with the [`winerror` attribute](https://docs.python.org/3/library/exceptions.html#OSError.winerror) is raised.\r\n- On the other hand, if the foreign function is generated with an `iid` and fails to call, a `COMError` is raised, providing more \"extended error reporting\" with the following attributes:\r\n  - `hresult`: an `HRESULT` value indicating an error, with any integer other than `S_OK` = `0`\r\n  - `text`: an error message string\r\n  - `details`: a tuple of length 5 representing `Description`, `Source`, `HelpFile`, `HelpContext`, and `scode`\r\n\r\nClearly mentioning this behavior would benefit not only those working with `comtypes` but also anyone involved in projects where `COMError` may arise.\r\nAt the very least, it would guide developers encountering this error to search `hresult` as a Windows error code.\r\n\r\nReferring to the `COMError` exception type as a private element such as `_CData` and specific to Windows such as `HRESULT` could help prevent developers from feeling it’s a \"mysterious error\" as I once did.\r\n\r\nAny opinions would be appreciated.\n\n\u003c!-- gh-linked-prs --\u003e\n### Linked PRs\n* gh-126686\n\u003c!-- /gh-linked-prs --\u003e\n","author":{"url":"https://github.com/junkmd","@type":"Person","name":"junkmd"},"datePublished":"2024-11-09T06:30:11.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":0},"url":"https://github.com/126615/cpython/issues/126615"}