mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-08-10 20:08:47 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 11

[3.12] Docs: Fix more Sphinx annotations in ctypes.rst (GH-107708) (#107717)

Browse source 
Docs: Fix more Sphinx annotations in ctypes.rst (GH-107708)
(cherry picked from commit 8c9af6b9a0)

Co-authored-by: Erlend E. Aasland <erlend@python.org>
This commit is contained in:
Miss Islington (bot) 2023-08-16 05:30:58 -07:00 • committed by GitHub
parent 6fd572f3b3
commit 220d7e3120
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 44 additions and 43 deletions
Download patch file Download diff file Expand all files Collapse all files

1
Doc/conf.py
View file

@ -94,6 +94,7 @@ nitpick_ignore = [
('c:func', 'sprintf'), ('c:func', 'sprintf'),
('c:func', 'stat'), ('c:func', 'stat'),
('c:func', 'system'), ('c:func', 'system'),
('c:func', 'time'),
('c:func', 'vsnprintf'), ('c:func', 'vsnprintf'),
# Standard C types # Standard C types
('c:type', 'FILE'), ('c:type', 'FILE'),

85
Doc/library/ctypes.rst
View file

@ -41,7 +41,7 @@ You load libraries by accessing them as attributes of these objects. *cdll*
loads libraries which export functions using the standard ``cdecl`` calling loads libraries which export functions using the standard ``cdecl`` calling
convention, while *windll* libraries call functions using the ``stdcall`` convention, while *windll* libraries call functions using the ``stdcall``
calling convention. *oledll* also uses the ``stdcall`` calling convention, and calling convention. *oledll* also uses the ``stdcall`` calling convention, and
assumes the functions return a Windows :c:type:`HRESULT` error code. The error assumes the functions return a Windows :c:type:`!HRESULT` error code. The error
code is used to automatically raise an :class:`OSError` exception when the code is used to automatically raise an :class:`OSError` exception when the
function call fails. function call fails.
@ -477,7 +477,7 @@ Return types
By default functions are assumed to return the C :c:expr:`int` type. Other By default functions are assumed to return the C :c:expr:`int` type. Other
return types can be specified by setting the :attr:`restype` attribute of the return types can be specified by setting the :attr:`~_FuncPtr.restype` attribute of the
function object. function object.
The C prototype of :c:func:`time` is ``time_t time(time_t *)``. Because :c:type:`time_t` The C prototype of :c:func:`time` is ``time_t time(time_t *)``. Because :c:type:`time_t`
@ -495,7 +495,7 @@ To call the function with a ``NULL`` pointer as first argument, use ``None``::
>>> print(libc.time(None)) # doctest: +SKIP >>> print(libc.time(None)) # doctest: +SKIP
1150640792 1150640792
Here is a more advanced example, it uses the :func:`strchr` function, which expects Here is a more advanced example, it uses the :func:`!strchr` function, which expects
a string pointer and a char, and returns a pointer to a string:: a string pointer and a char, and returns a pointer to a string::
>>> strchr = libc.strchr >>> strchr = libc.strchr
@ -528,7 +528,7 @@ single character Python bytes object into a C char:
>>> >>>
You can also use a callable Python object (a function or a class for example) as You can also use a callable Python object (a function or a class for example) as
the :attr:`restype` attribute, if the foreign function returns an integer. The the :attr:`~_FuncPtr.restype` attribute, if the foreign function returns an integer. The
callable will be called with the *integer* the C function returns, and the callable will be called with the *integer* the C function returns, and the
result of this call will be used as the result of your function call. This is result of this call will be used as the result of your function call. This is
useful to check for error return values and automatically raise an exception:: useful to check for error return values and automatically raise an exception::
@ -556,7 +556,8 @@ get the string representation of an error code, and *returns* an exception.
:func:`GetLastError` to retrieve it. :func:`GetLastError` to retrieve it.
Please note that a much more powerful error checking mechanism is available Please note that a much more powerful error checking mechanism is available
through the :attr:`errcheck` attribute; see the reference manual for details. through the :attr:`~_FuncPtr.errcheck` attribute;
see the reference manual for details.
.. _ctypes-passing-pointers: .. _ctypes-passing-pointers:
@ -594,7 +595,7 @@ Structures and unions
Structures and unions must derive from the :class:`Structure` and :class:`Union` Structures and unions must derive from the :class:`Structure` and :class:`Union`
base classes which are defined in the :mod:`ctypes` module. Each subclass must base classes which are defined in the :mod:`ctypes` module. Each subclass must
define a :attr:`_fields_` attribute. :attr:`_fields_` must be a list of define a :attr:`~Structure._fields_` attribute. :attr:`!_fields_` must be a list of
*2-tuples*, containing a *field name* and a *field type*. *2-tuples*, containing a *field name* and a *field type*.
The field type must be a :mod:`ctypes` type like :class:`c_int`, or any other The field type must be a :mod:`ctypes` type like :class:`c_int`, or any other
@ -666,9 +667,9 @@ Structure/union alignment and byte order
By default, Structure and Union fields are aligned in the same way the C By default, Structure and Union fields are aligned in the same way the C
compiler does it. It is possible to override this behavior by specifying a compiler does it. It is possible to override this behavior by specifying a
:attr:`_pack_` class attribute in the subclass definition. This must be set to a :attr:`~Structure._pack_` class attribute in the subclass definition.
positive integer and specifies the maximum alignment for the fields. This is This must be set to a positive integer and specifies the maximum alignment for the fields.
what ``#pragma pack(n)`` also does in MSVC. This is what ``#pragma pack(n)`` also does in MSVC.
:mod:`ctypes` uses the native byte order for Structures and Unions. To build :mod:`ctypes` uses the native byte order for Structures and Unions. To build
structures with non-native byte order, you can use one of the structures with non-native byte order, you can use one of the
@ -684,7 +685,7 @@ Bit fields in structures and unions
It is possible to create structures and unions containing bit fields. Bit fields It is possible to create structures and unions containing bit fields. Bit fields
are only possible for integer fields, the bit width is specified as the third are only possible for integer fields, the bit width is specified as the third
item in the :attr:`_fields_` tuples:: item in the :attr:`~Structure._fields_` tuples::
>>> class Int(Structure): >>> class Int(Structure):
... _fields_ = [("first_16", c_int, 16), ... _fields_ = [("first_16", c_int, 16),
@ -876,7 +877,7 @@ pointer types. So, for ``POINTER(c_int)``, ctypes accepts an array of c_int::
>>> >>>
In addition, if a function argument is explicitly declared to be a pointer type In addition, if a function argument is explicitly declared to be a pointer type
(such as ``POINTER(c_int)``) in :attr:`_FuncPtr.argtypes`, an object of the pointed (such as ``POINTER(c_int)``) in :attr:`~_FuncPtr.argtypes`, an object of the pointed
type (``c_int`` in this case) can be passed to the function. ctypes will apply type (``c_int`` in this case) can be passed to the function. ctypes will apply
the required :func:`byref` conversion in this case automatically. the required :func:`byref` conversion in this case automatically.
@ -952,8 +953,8 @@ work::
>>> >>>
because the new ``class cell`` is not available in the class statement itself. because the new ``class cell`` is not available in the class statement itself.
In :mod:`ctypes`, we can define the ``cell`` class and set the :attr:`_fields_` In :mod:`ctypes`, we can define the ``cell`` class and set the
attribute later, after the class statement:: :attr:`~Structure._fields_` attribute later, after the class statement::
>>> from ctypes import * >>> from ctypes import *
>>> class cell(Structure): >>> class cell(Structure):
@ -1003,8 +1004,8 @@ argument, and the callback functions expected argument types as the remaining
arguments. arguments.
I will present an example here which uses the standard C library's I will present an example here which uses the standard C library's
:c:func:`qsort` function, that is used to sort items with the help of a callback :c:func:`!qsort` function, that is used to sort items with the help of a callback
function. :c:func:`qsort` will be used to sort an array of integers:: function. :c:func:`!qsort` will be used to sort an array of integers::
>>> IntArray5 = c_int * 5 >>> IntArray5 = c_int * 5
>>> ia = IntArray5(5, 1, 7, 33, 99) >>> ia = IntArray5(5, 1, 7, 33, 99)
@ -1012,7 +1013,7 @@ function. :c:func:`qsort` will be used to sort an array of integers::
>>> qsort.restype = None >>> qsort.restype = None
>>> >>>
:func:`qsort` must be called with a pointer to the data to sort, the number of :func:`!qsort` must be called with a pointer to the data to sort, the number of
items in the data array, the size of one item, and a pointer to the comparison items in the data array, the size of one item, and a pointer to the comparison
function, the callback. The callback will then be called with two pointers to function, the callback. The callback will then be called with two pointers to
items, and it must return a negative integer if the first item is smaller than items, and it must return a negative integer if the first item is smaller than
@ -1104,7 +1105,7 @@ Some shared libraries not only export functions, they also export variables. An
example in the Python library itself is the :c:data:`Py_Version`, Python example in the Python library itself is the :c:data:`Py_Version`, Python
runtime version number encoded in a single constant integer. runtime version number encoded in a single constant integer.
:mod:`ctypes` can access values like this with the :meth:`in_dll` class methods of :mod:`ctypes` can access values like this with the :meth:`~_CData.in_dll` class methods of
the type. *pythonapi* is a predefined symbol giving access to the Python C the type. *pythonapi* is a predefined symbol giving access to the Python C
api:: api::
@ -1294,13 +1295,13 @@ Finding shared libraries
When programming in a compiled language, shared libraries are accessed when When programming in a compiled language, shared libraries are accessed when
compiling/linking a program, and when the program is run. compiling/linking a program, and when the program is run.
The purpose of the :func:`find_library` function is to locate a library in a way The purpose of the :func:`~ctypes.util.find_library` function is to locate a library in a way
similar to what the compiler or runtime loader does (on platforms with several similar to what the compiler or runtime loader does (on platforms with several
versions of a shared library the most recent should be loaded), while the ctypes versions of a shared library the most recent should be loaded), while the ctypes
library loaders act like when a program is run, and call the runtime loader library loaders act like when a program is run, and call the runtime loader
directly. directly.
The :mod:`ctypes.util` module provides a function which can help to determine The :mod:`!ctypes.util` module provides a function which can help to determine
the library to load. the library to load.
@ -1315,7 +1316,7 @@ the library to load.
The exact functionality is system dependent. The exact functionality is system dependent.
On Linux, :func:`find_library` tries to run external programs On Linux, :func:`~ctypes.util.find_library` tries to run external programs
(``/sbin/ldconfig``, ``gcc``, ``objdump`` and ``ld``) to find the library file. (``/sbin/ldconfig``, ``gcc``, ``objdump`` and ``ld``) to find the library file.
It returns the filename of the library file. It returns the filename of the library file.
@ -1334,7 +1335,7 @@ Here are some examples::
'libbz2.so.1.0' 'libbz2.so.1.0'
>>> >>>
On macOS, :func:`find_library` tries several predefined naming schemes and paths On macOS, :func:`~ctypes.util.find_library` tries several predefined naming schemes and paths
to locate the library, and returns a full pathname if successful:: to locate the library, and returns a full pathname if successful::
>>> from ctypes.util import find_library >>> from ctypes.util import find_library
@ -1348,13 +1349,13 @@ to locate the library, and returns a full pathname if successful::
'/System/Library/Frameworks/AGL.framework/AGL' '/System/Library/Frameworks/AGL.framework/AGL'
>>> >>>
On Windows, :func:`find_library` searches along the system search path, and On Windows, :func:`~ctypes.util.find_library` searches along the system search path, and
returns the full pathname, but since there is no predefined naming scheme a call returns the full pathname, but since there is no predefined naming scheme a call
like ``find_library("c")`` will fail and return ``None``. like ``find_library("c")`` will fail and return ``None``.
If wrapping a shared library with :mod:`ctypes`, it *may* be better to determine If wrapping a shared library with :mod:`ctypes`, it *may* be better to determine
the shared library name at development time, and hardcode that into the wrapper the shared library name at development time, and hardcode that into the wrapper
module instead of using :func:`find_library` to locate the library at runtime. module instead of using :func:`~ctypes.util.find_library` to locate the library at runtime.
.. _ctypes-loading-shared-libraries: .. _ctypes-loading-shared-libraries:
@ -1439,9 +1440,9 @@ function exported by these libraries, and reacquired afterwards.
All these classes can be instantiated by calling them with at least one All these classes can be instantiated by calling them with at least one
argument, the pathname of the shared library. If you have an existing handle to argument, the pathname of the shared library. If you have an existing handle to
an already loaded shared library, it can be passed as the ``handle`` named an already loaded shared library, it can be passed as the ``handle`` named
parameter, otherwise the underlying platforms :c:func:`!dlopen` or :c:func:`LoadLibrary` parameter, otherwise the underlying platforms :c:func:`!dlopen` or
function is used to load the library into the process, and to get a handle to :c:func:`!LoadLibrary` function is used to load the library into
it. the process, and to get a handle to it.
The *mode* parameter can be used to specify how the library is loaded. For The *mode* parameter can be used to specify how the library is loaded. For
details, consult the :manpage:`dlopen(3)` manpage. On Windows, *mode* is details, consult the :manpage:`dlopen(3)` manpage. On Windows, *mode* is
@ -1461,7 +1462,7 @@ to a new value and returns the former value.
The *use_last_error* parameter, when set to true, enables the same mechanism for The *use_last_error* parameter, when set to true, enables the same mechanism for
the Windows error code which is managed by the :func:`GetLastError` and the Windows error code which is managed by the :func:`GetLastError` and
:func:`SetLastError` Windows API functions; :func:`ctypes.get_last_error` and :func:`!SetLastError` Windows API functions; :func:`ctypes.get_last_error` and
:func:`ctypes.set_last_error` are used to request and change the ctypes private :func:`ctypes.set_last_error` are used to request and change the ctypes private
copy of the windows error code. copy of the windows error code.
@ -1533,7 +1534,7 @@ attribute of the loader instance.
Class which loads shared libraries. *dlltype* should be one of the Class which loads shared libraries. *dlltype* should be one of the
:class:`CDLL`, :class:`PyDLL`, :class:`WinDLL`, or :class:`OleDLL` types. :class:`CDLL`, :class:`PyDLL`, :class:`WinDLL`, or :class:`OleDLL` types.
:meth:`__getattr__` has special behavior: It allows loading a shared library by :meth:`!__getattr__` has special behavior: It allows loading a shared library by
accessing it as attribute of a library loader instance. The result is cached, accessing it as attribute of a library loader instance. The result is cached,
so repeated attribute accesses return the same library each time. so repeated attribute accesses return the same library each time.
@ -1578,7 +1579,7 @@ object is available:
An instance of :class:`PyDLL` that exposes Python C API functions as An instance of :class:`PyDLL` that exposes Python C API functions as
attributes. Note that all these functions are assumed to return C attributes. Note that all these functions are assumed to return C
:c:expr:`int`, which is of course not always the truth, so you have to assign :c:expr:`int`, which is of course not always the truth, so you have to assign
the correct :attr:`restype` attribute to use these functions. the correct :attr:`!restype` attribute to use these functions.
.. audit-event:: ctypes.dlopen name ctypes.LibraryLoader .. audit-event:: ctypes.dlopen name ctypes.LibraryLoader
@ -1630,7 +1631,7 @@ They are instances of a private class:
the callable will be called with this integer, allowing further the callable will be called with this integer, allowing further
processing or error checking. Using this is deprecated, for more flexible processing or error checking. Using this is deprecated, for more flexible
post processing or error checking use a ctypes data type as post processing or error checking use a ctypes data type as
:attr:`restype` and assign a callable to the :attr:`errcheck` attribute. :attr:`!restype` and assign a callable to the :attr:`errcheck` attribute.
.. attribute:: argtypes .. attribute:: argtypes
@ -1662,7 +1663,7 @@ They are instances of a private class:
:module: :module:
*result* is what the foreign function returns, as specified by the *result* is what the foreign function returns, as specified by the
:attr:`restype` attribute. :attr:`!restype` attribute.
*func* is the foreign function object itself, this allows reusing the *func* is the foreign function object itself, this allows reusing the
same callable object to check or post process the results of several same callable object to check or post process the results of several
@ -1772,7 +1773,7 @@ different ways, depending on the type and number of the parameters in the call:
COM methods use a special calling convention: They require a pointer to COM methods use a special calling convention: They require a pointer to
the COM interface as first argument, in addition to those parameters that the COM interface as first argument, in addition to those parameters that
are specified in the :attr:`~_FuncPtr.argtypes` tuple. are specified in the :attr:`!argtypes` tuple.
The optional *paramflags* parameter creates foreign function wrappers with much The optional *paramflags* parameter creates foreign function wrappers with much
more functionality than the features described above. more functionality than the features described above.
@ -1847,7 +1848,7 @@ value if there is a single one, or a tuple containing the output parameter
values when there are more than one, so the GetWindowRect function now returns a values when there are more than one, so the GetWindowRect function now returns a
RECT instance, when called. RECT instance, when called.
Output parameters can be combined with the :attr:`errcheck` protocol to do Output parameters can be combined with the :attr:`~_FuncPtr.errcheck` protocol to do
further output processing and error checking. The win32 ``GetWindowRect`` api further output processing and error checking. The win32 ``GetWindowRect`` api
function returns a ``BOOL`` to signal success or failure, so this function could function returns a ``BOOL`` to signal success or failure, so this function could
do the error checking, and raises an exception when the api call failed:: do the error checking, and raises an exception when the api call failed::
@ -1860,7 +1861,7 @@ do the error checking, and raises an exception when the api call failed::
>>> GetWindowRect.errcheck = errcheck >>> GetWindowRect.errcheck = errcheck
>>> >>>
If the :attr:`errcheck` function returns the argument tuple it receives If the :attr:`~_FuncPtr.errcheck` function returns the argument tuple it receives
unchanged, :mod:`ctypes` continues the normal processing it does on the output unchanged, :mod:`ctypes` continues the normal processing it does on the output
parameters. If you want to return a tuple of window coordinates instead of a parameters. If you want to return a tuple of window coordinates instead of a
``RECT`` instance, you can retrieve the fields in the function and return them ``RECT`` instance, you can retrieve the fields in the function and return them
@ -2010,7 +2011,7 @@ Utility functions
.. function:: get_last_error() .. function:: get_last_error()
Windows only: returns the current value of the ctypes-private copy of the system Windows only: returns the current value of the ctypes-private copy of the system
:data:`LastError` variable in the calling thread. :data:`!LastError` variable in the calling thread.
.. audit-event:: ctypes.get_last_error "" ctypes.get_last_error .. audit-event:: ctypes.get_last_error "" ctypes.get_last_error
@ -2063,7 +2064,7 @@ Utility functions
.. function:: set_last_error(value) .. function:: set_last_error(value)
Windows only: set the current value of the ctypes-private copy of the system Windows only: set the current value of the ctypes-private copy of the system
:data:`LastError` variable in the calling thread to *value* and return the :data:`!LastError` variable in the calling thread to *value* and return the
previous value. previous value.
.. audit-event:: ctypes.set_last_error error ctypes.set_last_error .. audit-event:: ctypes.set_last_error error ctypes.set_last_error
@ -2225,13 +2226,13 @@ Fundamental data types
Fundamental data types, when returned as foreign function call results, or, for Fundamental data types, when returned as foreign function call results, or, for
example, by retrieving structure field members or array items, are transparently example, by retrieving structure field members or array items, are transparently
converted to native Python types. In other words, if a foreign function has a converted to native Python types. In other words, if a foreign function has a
:attr:`restype` of :class:`c_char_p`, you will always receive a Python bytes :attr:`~_FuncPtr.restype` of :class:`c_char_p`, you will always receive a Python bytes
object, *not* a :class:`c_char_p` instance. object, *not* a :class:`c_char_p` instance.
.. XXX above is false, it actually returns a Unicode string .. XXX above is false, it actually returns a Unicode string
Subclasses of fundamental data types do *not* inherit this behavior. So, if a Subclasses of fundamental data types do *not* inherit this behavior. So, if a
foreign functions :attr:`restype` is a subclass of :class:`c_void_p`, you will foreign functions :attr:`!restype` is a subclass of :class:`c_void_p`, you will
receive an instance of this subclass from the function call. Of course, you can receive an instance of this subclass from the function call. Of course, you can
get the value of the pointer by accessing the ``value`` attribute. get the value of the pointer by accessing the ``value`` attribute.
@ -2430,7 +2431,7 @@ These are the fundamental ctypes data types:
.. class:: HRESULT .. class:: HRESULT
Windows only: Represents a :c:type:`HRESULT` value, which contains success or Windows only: Represents a :c:type:`!HRESULT` value, which contains success or
error information for a function or method call. error information for a function or method call.
@ -2439,9 +2440,9 @@ These are the fundamental ctypes data types:
Represents the C :c:expr:`PyObject *` datatype. Calling this without an Represents the C :c:expr:`PyObject *` datatype. Calling this without an
argument creates a ``NULL`` :c:expr:`PyObject *` pointer. argument creates a ``NULL`` :c:expr:`PyObject *` pointer.
The :mod:`ctypes.wintypes` module provides quite some other Windows specific The :mod:`!ctypes.wintypes` module provides quite some other Windows specific
data types, for example :c:type:`HWND`, :c:type:`WPARAM`, or :c:type:`DWORD`. Some data types, for example :c:type:`!HWND`, :c:type:`!WPARAM`, or :c:type:`!DWORD`.
useful structures like :c:type:`MSG` or :c:type:`RECT` are also defined. Some useful structures like :c:type:`!MSG` or :c:type:`!RECT` are also defined.
.. _ctypes-structured-data-types: .. _ctypes-structured-data-types:

1
Doc/tools/.nitignore
View file

@ -69,7 +69,6 @@ Doc/library/configparser.rst
Doc/library/contextlib.rst Doc/library/contextlib.rst
Doc/library/copy.rst Doc/library/copy.rst
Doc/library/csv.rst Doc/library/csv.rst
Doc/library/ctypes.rst
Doc/library/datetime.rst Doc/library/datetime.rst
Doc/library/dbm.rst Doc/library/dbm.rst
Doc/library/decimal.rst Doc/library/decimal.rst