Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

gh-127082: Replace "Windows only: ..." with the .. availability:: Windows directive in ctypes doc. #127099

Merged
merged 4 commits into from
Nov 22, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 48 additions & 15 deletions Doc/library/ctypes.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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,
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`.
Expand All @@ -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,
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.

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -1746,11 +1755,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)

Expand Down Expand Up @@ -1981,17 +1992,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
Expand All @@ -2007,28 +2022,35 @@ 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.

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
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
Expand All @@ -2038,11 +2060,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
Expand Down Expand Up @@ -2091,10 +2116,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


Expand All @@ -2115,12 +2142,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`.
Expand Down Expand Up @@ -2484,9 +2513,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

Expand Down Expand Up @@ -2755,7 +2786,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

Expand All @@ -2775,4 +2806,6 @@ Exceptions
identifier. *progid* is the ``ProgID`` of the interface that defined the
error.

.. availability:: Windows

.. versionadded:: next
Loading