Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commit220d7e3

Browse files
[3.12] Docs: Fix more Sphinx annotations in ctypes.rst (GH-107708) (#107717)
Docs: Fix more Sphinx annotations in ctypes.rst (GH-107708)(cherry picked from commit8c9af6b)Co-authored-by: Erlend E. Aasland <erlend@python.org>
1 parent6fd572f commit220d7e3

File tree

3 files changed

+44
-43
lines changed

3 files changed

+44
-43
lines changed

‎Doc/conf.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -94,6 +94,7 @@
9494
('c:func','sprintf'),
9595
('c:func','stat'),
9696
('c:func','system'),
97+
('c:func','time'),
9798
('c:func','vsnprintf'),
9899
# Standard C types
99100
('c:type','FILE'),

‎Doc/library/ctypes.rst‎

Lines changed: 43 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ You load libraries by accessing them as attributes of these objects. *cdll*
4141
loads libraries which export functions using the standard ``cdecl`` calling
4242
convention, while *windll* libraries call functions using the ``stdcall``
4343
calling convention. *oledll* also uses the ``stdcall`` calling convention, and
44-
assumes the functions return a Windows:c:type:`HRESULT` error code. The error
44+
assumes the functions return a Windows:c:type:`!HRESULT` error code. The error
4545
code is used to automatically raise an:class:`OSError` exception when the
4646
function call fails.
4747

@@ -477,7 +477,7 @@ Return types
477477

478478

479479
By default functions are assumed to return the C:c:expr:`int` type. Other
480-
return types can be specified by setting the:attr:`restype` attribute of the
480+
return types can be specified by setting the:attr:`~_FuncPtr.restype` attribute of the
481481
function object.
482482

483483
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``::
495495
>>> print(libc.time(None)) # doctest: +SKIP
496496
1150640792
497497

498-
Here is a more advanced example, it uses the:func:`strchr` function, which expects
498+
Here is a more advanced example, it uses the:func:`!strchr` function, which expects
499499
a string pointer and a char, and returns a pointer to a string::
500500

501501
>>> strchr = libc.strchr
@@ -528,7 +528,7 @@ single character Python bytes object into a C char:
528528
>>>
529529

530530
You can also use a callable Python object (a function or a class for example) as
531-
the:attr:`restype` attribute, if the foreign function returns an integer. The
531+
the:attr:`~_FuncPtr.restype` attribute, if the foreign function returns an integer. The
532532
callable will be called with the *integer* the C function returns, and the
533533
result of this call will be used as the result of your function call. This is
534534
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.
556556
:func:`GetLastError` to retrieve it.
557557

558558
Please note that a much more powerful error checking mechanism is available
559-
through the:attr:`errcheck` attribute; see the reference manual for details.
559+
through the:attr:`~_FuncPtr.errcheck` attribute;
560+
see the reference manual for details.
560561

561562

562563
.. _ctypes-passing-pointers:
@@ -594,7 +595,7 @@ Structures and unions
594595

595596
Structures and unions must derive from the:class:`Structure` and:class:`Union`
596597
base classes which are defined in the:mod:`ctypes` module. Each subclass must
597-
define a:attr:`_fields_` attribute.:attr:`_fields_` must be a list of
598+
define a:attr:`~Structure._fields_` attribute.:attr:`!_fields_` must be a list of
598599
*2-tuples*, containing a *field name* and a *field type*.
599600

600601
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
666667

667668
By default, Structure and Union fields are aligned in the same way the C
668669
compiler does it. It is possible to override this behavior by specifying a
669-
:attr:`_pack_` class attribute in the subclass definition. This must be set to a
670-
positive integer and specifies the maximum alignment for the fields. This is
671-
what ``#pragma pack(n)`` also does in MSVC.
670+
:attr:`~Structure._pack_` class attribute in the subclass definition.
671+
This must be set to apositive integer and specifies the maximum alignment for the fields.
672+
This iswhat ``#pragma pack(n)`` also does in MSVC.
672673

673674
:mod:`ctypes` uses the native byte order for Structures and Unions. To build
674675
structures with non-native byte order, you can use one of the
@@ -684,7 +685,7 @@ Bit fields in structures and unions
684685

685686
It is possible to create structures and unions containing bit fields. Bit fields
686687
are only possible for integer fields, the bit width is specified as the third
687-
item in the:attr:`_fields_` tuples::
688+
item in the:attr:`~Structure._fields_` tuples::
688689

689690
>>> class Int(Structure):
690691
... _fields_ = [("first_16", c_int, 16),
@@ -876,7 +877,7 @@ pointer types. So, for ``POINTER(c_int)``, ctypes accepts an array of c_int::
876877
>>>
877878

878879
In addition, if a function argument is explicitly declared to be a pointer type
879-
(such as ``POINTER(c_int)``) in:attr:`_FuncPtr.argtypes`, an object of the pointed
880+
(such as ``POINTER(c_int)``) in:attr:`~_FuncPtr.argtypes`, an object of the pointed
880881
type (``c_int`` in this case) can be passed to the function. ctypes will apply
881882
the required:func:`byref` conversion in this case automatically.
882883

@@ -952,8 +953,8 @@ work::
952953
>>>
953954

954955
because the new ``class cell`` is not available in the class statement itself.
955-
In:mod:`ctypes`, we can define the ``cell`` class and set the:attr:`_fields_`
956-
attribute later, after the class statement::
956+
In:mod:`ctypes`, we can define the ``cell`` class and set the
957+
:attr:`~Structure._fields_`attribute later, after the class statement::
957958

958959
>>> from ctypes import *
959960
>>> class cell(Structure):
@@ -1003,16 +1004,16 @@ argument, and the callback functions expected argument types as the remaining
10031004
arguments.
10041005

10051006
I will present an example here which uses the standard C library's
1006-
:c:func:`qsort` function, that is used to sort items with the help of a callback
1007-
function.:c:func:`qsort` will be used to sort an array of integers::
1007+
:c:func:`!qsort` function, that is used to sort items with the help of a callback
1008+
function.:c:func:`!qsort` will be used to sort an array of integers::
10081009

10091010
>>> IntArray5 = c_int * 5
10101011
>>> ia = IntArray5(5, 1, 7, 33, 99)
10111012
>>> qsort = libc.qsort
10121013
>>> qsort.restype = None
10131014
>>>
10141015

1015-
:func:`qsort` must be called with a pointer to the data to sort, the number of
1016+
:func:`!qsort` must be called with a pointer to the data to sort, the number of
10161017
items in the data array, the size of one item, and a pointer to the comparison
10171018
function, the callback. The callback will then be called with two pointers to
10181019
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
11041105
example in the Python library itself is the:c:data:`Py_Version`, Python
11051106
runtime version number encoded in a single constant integer.
11061107

1107-
:mod:`ctypes` can access values like this with the:meth:`in_dll` class methods of
1108+
:mod:`ctypes` can access values like this with the:meth:`~_CData.in_dll` class methods of
11081109
the type. *pythonapi* is a predefined symbol giving access to the Python C
11091110
api::
11101111

@@ -1294,13 +1295,13 @@ Finding shared libraries
12941295
When programming in a compiled language, shared libraries are accessed when
12951296
compiling/linking a program, and when the program is run.
12961297

1297-
The purpose of the:func:`find_library` function is to locate a library in a way
1298+
The purpose of the:func:`~ctypes.util.find_library` function is to locate a library in a way
12981299
similar to what the compiler or runtime loader does (on platforms with several
12991300
versions of a shared library the most recent should be loaded), while the ctypes
13001301
library loaders act like when a program is run, and call the runtime loader
13011302
directly.
13021303

1303-
The:mod:`ctypes.util` module provides a function which can help to determine
1304+
The:mod:`!ctypes.util` module provides a function which can help to determine
13041305
the library to load.
13051306

13061307

@@ -1315,7 +1316,7 @@ the library to load.
13151316

13161317
The exact functionality is system dependent.
13171318

1318-
On Linux,:func:`find_library` tries to run external programs
1319+
On Linux,:func:`~ctypes.util.find_library` tries to run external programs
13191320
(``/sbin/ldconfig``, ``gcc``, ``objdump`` and ``ld``) to find the library file.
13201321
It returns the filename of the library file.
13211322

@@ -1334,7 +1335,7 @@ Here are some examples::
13341335
'libbz2.so.1.0'
13351336
>>>
13361337

1337-
On macOS,:func:`find_library` tries several predefined naming schemes and paths
1338+
On macOS,:func:`~ctypes.util.find_library` tries several predefined naming schemes and paths
13381339
to locate the library, and returns a full pathname if successful::
13391340

13401341
>>> from ctypes.util import find_library
@@ -1348,13 +1349,13 @@ to locate the library, and returns a full pathname if successful::
13481349
'/System/Library/Frameworks/AGL.framework/AGL'
13491350
>>>
13501351

1351-
On Windows,:func:`find_library` searches along the system search path, and
1352+
On Windows,:func:`~ctypes.util.find_library` searches along the system search path, and
13521353
returns the full pathname, but since there is no predefined naming scheme a call
13531354
like ``find_library("c")`` will fail and return ``None``.
13541355

13551356
If wrapping a shared library with:mod:`ctypes`, it *may* be better to determine
13561357
the shared library name at development time, and hardcode that into the wrapper
1357-
module instead of using:func:`find_library` to locate the library at runtime.
1358+
module instead of using:func:`~ctypes.util.find_library` to locate the library at runtime.
13581359

13591360

13601361
.. _ctypes-loading-shared-libraries:
@@ -1439,9 +1440,9 @@ function exported by these libraries, and reacquired afterwards.
14391440
All these classes can be instantiated by calling them with at least one
14401441
argument, the pathname of the shared library. If you have an existing handle to
14411442
an already loaded shared library, it can be passed as the ``handle`` named
1442-
parameter, otherwise the underlying platforms:c:func:`!dlopen` or:c:func:`LoadLibrary`
1443-
function is used to load the library into the process, and to get a handle to
1444-
it.
1443+
parameter, otherwise the underlying platforms:c:func:`!dlopen` or
1444+
:c:func:`!LoadLibrary`function is used to load the library into
1445+
the process, and to get a handle toit.
14451446

14461447
The *mode* parameter can be used to specify how the library is loaded. For
14471448
details, consult the:manpage:`dlopen(3)` manpage. On Windows, *mode* is
@@ -1461,7 +1462,7 @@ to a new value and returns the former value.
14611462

14621463
The *use_last_error* parameter, when set to true, enables the same mechanism for
14631464
the Windows error code which is managed by the:func:`GetLastError` and
1464-
:func:`SetLastError` Windows API functions;:func:`ctypes.get_last_error` and
1465+
:func:`!SetLastError` Windows API functions;:func:`ctypes.get_last_error` and
14651466
:func:`ctypes.set_last_error` are used to request and change the ctypes private
14661467
copy of the windows error code.
14671468

@@ -1533,7 +1534,7 @@ attribute of the loader instance.
15331534
Class which loads shared libraries. *dlltype* should be one of the
15341535
:class:`CDLL`,:class:`PyDLL`,:class:`WinDLL`, or:class:`OleDLL` types.
15351536

1536-
:meth:`__getattr__` has special behavior: It allows loading a shared library by
1537+
:meth:`!__getattr__` has special behavior: It allows loading a shared library by
15371538
accessing it as attribute of a library loader instance. The result is cached,
15381539
so repeated attribute accesses return the same library each time.
15391540

@@ -1578,7 +1579,7 @@ object is available:
15781579
An instance of:class:`PyDLL` that exposes Python C API functions as
15791580
attributes. Note that all these functions are assumed to return C
15801581
:c:expr:`int`, which is of course not always the truth, so you have to assign
1581-
the correct:attr:`restype` attribute to use these functions.
1582+
the correct:attr:`!restype` attribute to use these functions.
15821583

15831584
..audit-event::ctypes.dlopen name ctypes.LibraryLoader
15841585

@@ -1630,7 +1631,7 @@ They are instances of a private class:
16301631
the callable will be called with this integer, allowing further
16311632
processing or error checking. Using this is deprecated, for more flexible
16321633
post processing or error checking use a ctypes data type as
1633-
:attr:`restype` and assign a callable to the:attr:`errcheck` attribute.
1634+
:attr:`!restype` and assign a callable to the:attr:`errcheck` attribute.
16341635

16351636
..attribute::argtypes
16361637

@@ -1662,7 +1663,7 @@ They are instances of a private class:
16621663
:module:
16631664

16641665
*result* is what the foreign function returns, as specified by the
1665-
:attr:`restype` attribute.
1666+
:attr:`!restype` attribute.
16661667

16671668
*func* is the foreign function object itself, this allows reusing the
16681669
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:
17721773

17731774
COM methods use a special calling convention: They require a pointer to
17741775
the COM interface as first argument, in addition to those parameters that
1775-
are specified in the:attr:`~_FuncPtr.argtypes` tuple.
1776+
are specified in the:attr:`!argtypes` tuple.
17761777

17771778
The optional *paramflags* parameter creates foreign function wrappers with much
17781779
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
18471848
values when there are more than one, so the GetWindowRect function now returns a
18481849
RECT instance, when called.
18491850

1850-
Output parameters can be combined with the:attr:`errcheck` protocol to do
1851+
Output parameters can be combined with the:attr:`~_FuncPtr.errcheck` protocol to do
18511852
further output processing and error checking. The win32 ``GetWindowRect`` api
18521853
function returns a ``BOOL`` to signal success or failure, so this function could
18531854
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::
18601861
>>> GetWindowRect.errcheck = errcheck
18611862
>>>
18621863

1863-
If the:attr:`errcheck` function returns the argument tuple it receives
1864+
If the:attr:`~_FuncPtr.errcheck` function returns the argument tuple it receives
18641865
unchanged,:mod:`ctypes` continues the normal processing it does on the output
18651866
parameters. If you want to return a tuple of window coordinates instead of a
18661867
``RECT`` instance, you can retrieve the fields in the function and return them
@@ -2010,7 +2011,7 @@ Utility functions
20102011
..function::get_last_error()
20112012

20122013
Windows only: returns the current value of the ctypes-private copy of the system
2013-
:data:`LastError` variable in the calling thread.
2014+
:data:`!LastError` variable in the calling thread.
20142015

20152016
..audit-event::ctypes.get_last_error "" ctypes.get_last_error
20162017

@@ -2063,7 +2064,7 @@ Utility functions
20632064
..function::set_last_error(value)
20642065

20652066
Windows only: set the current value of the ctypes-private copy of the system
2066-
:data:`LastError` variable in the calling thread to *value* and return the
2067+
:data:`!LastError` variable in the calling thread to *value* and return the
20672068
previous value.
20682069

20692070
..audit-event::ctypes.set_last_error error ctypes.set_last_error
@@ -2225,13 +2226,13 @@ Fundamental data types
22252226
Fundamental data types, when returned as foreign function call results, or, for
22262227
example, by retrieving structure field members or array items, are transparently
22272228
converted to native Python types. In other words, if a foreign function has a
2228-
:attr:`restype` of:class:`c_char_p`, you will always receive a Python bytes
2229+
:attr:`~_FuncPtr.restype` of:class:`c_char_p`, you will always receive a Python bytes
22292230
object, *not* a:class:`c_char_p` instance.
22302231

22312232
.. XXX above is false, it actually returns a Unicode string
22322233
22332234
Subclasses of fundamental data types do *not* inherit this behavior. So, if a
2234-
foreign functions:attr:`restype` is a subclass of:class:`c_void_p`, you will
2235+
foreign functions:attr:`!restype` is a subclass of:class:`c_void_p`, you will
22352236
receive an instance of this subclass from the function call. Of course, you can
22362237
get the value of the pointer by accessing the ``value`` attribute.
22372238

@@ -2430,7 +2431,7 @@ These are the fundamental ctypes data types:
24302431

24312432
..class::HRESULT
24322433

2433-
Windows only: Represents a:c:type:`HRESULT` value, which contains success or
2434+
Windows only: Represents a:c:type:`!HRESULT` value, which contains success or
24342435
error information for a function or method call.
24352436

24362437

@@ -2439,9 +2440,9 @@ These are the fundamental ctypes data types:
24392440
Represents the C:c:expr:`PyObject *` datatype. Calling this without an
24402441
argument creates a ``NULL``:c:expr:`PyObject *` pointer.
24412442

2442-
The:mod:`ctypes.wintypes` module provides quite some other Windows specific
2443-
data types, for example:c:type:`HWND`,:c:type:`WPARAM`, or:c:type:`DWORD`. Some
2444-
useful structures like:c:type:`MSG` or:c:type:`RECT` are also defined.
2443+
The:mod:`!ctypes.wintypes` module provides quite some other Windows specific
2444+
data types, for example:c:type:`!HWND`,:c:type:`!WPARAM`, or:c:type:`!DWORD`.
2445+
Someuseful structures like:c:type:`!MSG` or:c:type:`!RECT` are also defined.
24452446

24462447

24472448
.. _ctypes-structured-data-types:

‎Doc/tools/.nitignore‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,6 @@ Doc/library/configparser.rst
6969
Doc/library/contextlib.rst
7070
Doc/library/copy.rst
7171
Doc/library/csv.rst
72-
Doc/library/ctypes.rst
7372
Doc/library/datetime.rst
7473
Doc/library/dbm.rst
7574
Doc/library/decimal.rst

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp