https://github.com/python/cpython/commit/af00c586525f6018c7ecd877cddeb936f9b2aedf
commit: af00c586525f6018c7ecd877cddeb936f9b2aedf
branch: 3.13
author: Jun Komoda <[email protected]>
committer: vstinner <[email protected]>
date: 2024-11-22T14:09:53+01:00
summary:
[3.13] gh-127082: Replace "Windows only" with the `availability: Windows` in
`ctypes` doc (GH-127099) (#127144)
(cherry picked from commit 3c770e3f0978d825c5ebea98fcd654660e7e135f)
files:
M Doc/library/ctypes.rst
diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst
index 83d43b209f7ca0..f96cfeb5796cfe 100644
--- a/Doc/library/ctypes.rst
+++ b/Doc/library/ctypes.rst
@@ -1395,13 +1395,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,
+ 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`.
@@ -1413,14 +1415,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,
+ 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.
@@ -1556,13 +1561,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
@@ -1734,11 +1743,13 @@ 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
+ 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)
@@ -1964,17 +1975,21 @@ Utility functions
.. function:: DllCanUnloadNow()
- Windows only: This function is a hook which allows implementing in-process
+ 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
+ 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)
:module: ctypes.util
@@ -1990,7 +2005,7 @@ Utility functions
.. function:: find_msvcrt()
:module: ctypes.util
- Windows only: return the filename of the VC runtime library used by Python,
+ 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.
@@ -1998,20 +2013,27 @@ Utility functions
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
+ 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
+
.. 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
@@ -2021,11 +2043,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
@@ -2074,10 +2099,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
@@ -2098,12 +2125,14 @@ Utility functions
.. function:: WinError(code=None, descr=None)
- Windows only: this function is probably the worst-named thing in ctypes. It
+ 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
alias of :exc:`OSError`.
@@ -2443,9 +2472,11 @@ These are the fundamental ctypes data types:
.. class:: HRESULT
- Windows only: Represents a :c:type:`!HRESULT` value, which contains success
or
+ Represents a :c:type:`!HRESULT` value, which contains success or
error information for a function or method call.
+ .. availability:: Windows
+
.. class:: py_object
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-checkins.python.org/
Member address: [email protected]
