From 84e13f3b4e3737c9b682c55c06a375f992fd00da Mon Sep 17 00:00:00 2001 From: Jun Komoda <45822440+junkmd@users.noreply.github.com> Date: Thu, 21 Nov 2024 12:03:11 +0000 Subject: [PATCH 1/3] Replace "Foo only: ..." with the `.. availability:: Foo` directive. --- Doc/library/ctypes.rst | 101 +++++++++++++++++++++++++++-------------- 1 file changed, 66 insertions(+), 35 deletions(-) diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index 8ed75d9b7560b9..3828e89d0c373f 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -1413,13 +1413,15 @@ way is to instantiate one of the following classes: .. class:: OleDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False, winmode=None) - Windows only: Instances of this class represent loaded shared libraries, - functions in these libraries use the ``stdcall`` calling convention, and are - assumed to return the windows specific :class:`HRESULT` code. :class:`HRESULT` + Instances of this class represent loaded shared libraries, functions in + these libraries use the ``stdcall`` calling convention, and are assumed + to return the windows specific :class:`HRESULT` code. :class:`HRESULT` values contain information specifying whether the function call failed or succeeded, together with additional error code. If the return value signals a failure, an :class:`OSError` is automatically raised. + .. availability:: Windows + .. versionchanged:: 3.3 :exc:`WindowsError` used to be raised, which is now an alias of :exc:`OSError`. @@ -1431,14 +1433,17 @@ way is to instantiate one of the following classes: .. class:: WinDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False, winmode=None) - Windows only: Instances of this class represent loaded shared libraries, - functions in these libraries use the ``stdcall`` calling convention, and are - assumed to return :c:expr:`int` by default. + Instances of this class represent loaded shared libraries, functions in these + libraries use the ``stdcall`` calling convention, and are assumed to return + :c:expr:`int` by default. + + .. availability:: Windows .. versionchanged:: 3.12 The *name* parameter can now be a :term:`path-like object`. + The Python :term:`global interpreter lock` is released before calling any function exported by these libraries, and reacquired afterwards. @@ -1574,13 +1579,17 @@ These prefabricated library loaders are available: .. data:: windll :noindex: - Windows only: Creates :class:`WinDLL` instances. + Creates :class:`WinDLL` instances. + + .. availability:: Windows .. data:: oledll :noindex: - Windows only: Creates :class:`OleDLL` instances. + Creates :class:`OleDLL` instances. + + .. availability:: Windows .. data:: pydll @@ -1746,10 +1755,11 @@ See :ref:`ctypes-callback-functions` for examples. .. function:: WINFUNCTYPE(restype, *argtypes, use_errno=False, use_last_error=False) - Windows only: The returned function prototype creates functions that use the - ``stdcall`` calling convention. The function will - release the GIL during the call. *use_errno* and *use_last_error* have the - same meaning as above. + The returned function prototype creates functions that use the ``stdcall`` + calling convention. The function will release the GIL during the call. + *use_errno* and *use_last_error* have the same meaning as above. + + .. availability:: Windows .. function:: PYFUNCTYPE(restype, *argtypes) @@ -1981,16 +1991,20 @@ Utility functions .. function:: DllCanUnloadNow() - Windows only: This function is a hook which allows implementing in-process - COM servers with ctypes. It is called from the DllCanUnloadNow function that - the _ctypes extension dll exports. + This function is a hook which allows implementing in-process COM servers with + ctypes. It is called from the ``DllCanUnloadNow`` function that the + ``_ctypes`` extension dll exports. + + .. availability:: Windows .. function:: DllGetClassObject() - Windows only: This function is a hook which allows implementing in-process - COM servers with ctypes. It is called from the DllGetClassObject function - that the ``_ctypes`` extension dll exports. + This function is a hook which allows implementing in-process COM servers with + ctypes. It is called from the ``DllGetClassObject`` function that the + ``_ctypes`` extension dll exports. + + .. availability:: Windows .. function:: find_library(name) @@ -2007,28 +2021,35 @@ Utility functions .. function:: find_msvcrt() :module: ctypes.util - Windows only: return the filename of the VC runtime library used by Python, - and by the extension modules. If the name of the library cannot be - determined, ``None`` is returned. + Returns the filename of the VC runtime library used by Python, and by the + extension modules. If the name of the library cannot be determined, ``None`` + is returned. If you need to free memory, for example, allocated by an extension module with a call to the ``free(void *)``, it is important that you use the function in the same library that allocated the memory. + .. availability:: Windows + .. function:: FormatError([code]) - Windows only: Returns a textual description of the error code *code*. If no - error code is specified, the last error code is used by calling the Windows - api function GetLastError. + Returns a textual description of the error code *code*. If no error code is + specified, the last error code is used by calling the Windows api function + :func:`GetLastError`. + + .. availability:: Windows .. function:: GetLastError() - Windows only: Returns the last error code set by Windows in the calling thread. + Returns the last error code set by Windows in the calling thread. This function calls the Windows ``GetLastError()`` function directly, it does not return the ctypes-private copy of the error code. + .. availability:: Windows + + .. function:: get_errno() Returns the current value of the ctypes-private copy of the system @@ -2038,11 +2059,14 @@ Utility functions .. function:: get_last_error() - Windows only: returns the current value of the ctypes-private copy of the system + Returns the current value of the ctypes-private copy of the system :data:`!LastError` variable in the calling thread. + .. availability:: Windows + .. audit-event:: ctypes.get_last_error "" ctypes.get_last_error + .. function:: memmove(dst, src, count) Same as the standard C memmove library function: copies *count* bytes from @@ -2091,10 +2115,12 @@ Utility functions .. function:: set_last_error(value) - Windows only: set the current value of the ctypes-private copy of the system + Sets the current value of the ctypes-private copy of the system :data:`!LastError` variable in the calling thread to *value* and return the previous value. + .. availability:: Windows + .. audit-event:: ctypes.set_last_error error ctypes.set_last_error @@ -2115,11 +2141,12 @@ Utility functions .. function:: WinError(code=None, descr=None) - Windows only: this function is probably the worst-named thing in ctypes. It - creates an instance of :exc:`OSError`. If *code* is not specified, - ``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. + This function is probably the worst-named thing in ctypes. It creates an + instance of :exc:`OSError`. If *code* is not specified, ``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. + + .. availability:: Windows .. versionchanged:: 3.3 An instance of :exc:`WindowsError` used to be created, which is now an @@ -2484,8 +2511,10 @@ These are the fundamental ctypes data types: .. class:: HRESULT - Windows only: Represents a :c:type:`!HRESULT` value, which contains success or - error information for a function or method call. + Represents a :c:type:`!HRESULT` value, which contains success or error + information for a function or method call. + + .. availability:: Windows .. class:: py_object @@ -2755,7 +2784,7 @@ Exceptions .. exception:: COMError(hresult, text, details) - Windows only: This exception is raised when a COM method call failed. + This exception is raised when a COM method call failed. .. attribute:: hresult @@ -2775,4 +2804,6 @@ Exceptions identifier. *progid* is the ``ProgID`` of the interface that defined the error. + .. availability:: Windows + .. versionadded:: next From 6975ca600996e6b85e042259eb515e443a34019e Mon Sep 17 00:00:00 2001 From: Jun Komoda <45822440+junkmd@users.noreply.github.com> Date: Thu, 21 Nov 2024 22:57:43 +0000 Subject: [PATCH 2/3] Revert reformating paragraphs. --- Doc/library/ctypes.rst | 48 ++++++++++++++++++++++-------------------- 1 file changed, 25 insertions(+), 23 deletions(-) diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index 3828e89d0c373f..b1f54f5d383a19 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -1413,9 +1413,9 @@ way is to instantiate one of the following classes: .. class:: OleDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False, winmode=None) - Instances of this class represent loaded shared libraries, functions in - these libraries use the ``stdcall`` calling convention, and are assumed - to return the windows specific :class:`HRESULT` code. :class:`HRESULT` + Instances of this class represent loaded shared libraries, + functions in these libraries use the ``stdcall`` calling convention, and are + assumed to return the windows specific :class:`HRESULT` code. :class:`HRESULT` values contain information specifying whether the function call failed or succeeded, together with additional error code. If the return value signals a failure, an :class:`OSError` is automatically raised. @@ -1755,9 +1755,10 @@ See :ref:`ctypes-callback-functions` for examples. .. function:: WINFUNCTYPE(restype, *argtypes, use_errno=False, use_last_error=False) - The returned function prototype creates functions that use the ``stdcall`` - calling convention. The function will release the GIL during the call. - *use_errno* and *use_last_error* have the same meaning as above. + The returned function prototype creates functions that use the + ``stdcall`` calling convention. The function will + release the GIL during the call. *use_errno* and *use_last_error* have the + same meaning as above. .. availability:: Windows @@ -1991,18 +1992,18 @@ Utility functions .. function:: DllCanUnloadNow() - This function is a hook which allows implementing in-process COM servers with - ctypes. It is called from the ``DllCanUnloadNow`` function that the - ``_ctypes`` extension dll exports. + This function is a hook which allows implementing in-process + COM servers with ctypes. It is called from the DllCanUnloadNow function that + the _ctypes extension dll exports. .. availability:: Windows .. function:: DllGetClassObject() - This function is a hook which allows implementing in-process COM servers with - ctypes. It is called from the ``DllGetClassObject`` function that the - ``_ctypes`` extension dll exports. + This function is a hook which allows implementing in-process + COM servers with ctypes. It is called from the DllGetClassObject function + that the ``_ctypes`` extension dll exports. .. availability:: Windows @@ -2021,9 +2022,9 @@ Utility functions .. function:: find_msvcrt() :module: ctypes.util - Returns the filename of the VC runtime library used by Python, and by the - extension modules. If the name of the library cannot be determined, ``None`` - is returned. + Returns the filename of the VC runtime library used by Python, + and by the extension modules. If the name of the library cannot be + determined, ``None`` is returned. If you need to free memory, for example, allocated by an extension module with a call to the ``free(void *)``, it is important that you use the @@ -2035,8 +2036,8 @@ Utility functions .. function:: FormatError([code]) Returns a textual description of the error code *code*. If no error code is - specified, the last error code is used by calling the Windows api function - :func:`GetLastError`. + specified, the last error code is used by calling the Windows + api function GetLastError. .. availability:: Windows @@ -2141,10 +2142,11 @@ Utility functions .. function:: WinError(code=None, descr=None) - This function is probably the worst-named thing in ctypes. It creates an - instance of :exc:`OSError`. If *code* is not specified, ``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. + This function is probably the worst-named thing in ctypes. It + creates an instance of :exc:`OSError`. If *code* is not specified, + ``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. .. availability:: Windows @@ -2511,8 +2513,8 @@ These are the fundamental ctypes data types: .. class:: HRESULT - Represents a :c:type:`!HRESULT` value, which contains success or error - information for a function or method call. + Represents a :c:type:`!HRESULT` value, which contains success or + error information for a function or method call. .. availability:: Windows From da206acbf5e66d57286c0630e88189567f8d68e8 Mon Sep 17 00:00:00 2001 From: Jun Komoda <45822440+junkmd@users.noreply.github.com> Date: Thu, 21 Nov 2024 23:02:13 +0000 Subject: [PATCH 3/3] Revert reformating paragraphs. --- Doc/library/ctypes.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index b1f54f5d383a19..f490f7563b58a5 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -1433,9 +1433,9 @@ way is to instantiate one of the following classes: .. class:: WinDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False, winmode=None) - Instances of this class represent loaded shared libraries, functions in these - libraries use the ``stdcall`` calling convention, and are assumed to return - :c:expr:`int` by default. + Instances of this class represent loaded shared libraries, + functions in these libraries use the ``stdcall`` calling convention, and are + assumed to return :c:expr:`int` by default. .. availability:: Windows @@ -2035,8 +2035,8 @@ Utility functions .. function:: FormatError([code]) - Returns a textual description of the error code *code*. If no error code is - specified, the last error code is used by calling the Windows + Returns a textual description of the error code *code*. If no + error code is specified, the last error code is used by calling the Windows api function GetLastError. .. availability:: Windows