# Copyright (C) 2001-2018, Python Software Foundation # For licence information, see README file. # msgid "" msgstr "" "Project-Id-Version: Python 3\n" "Report-Msgid-Bugs-To: \n" "POT-Creation-Date: 2019-12-05 23:16+0100\n" "PO-Revision-Date: 2018-07-29 19:07+0200\n" "Last-Translator: FULL NAME \n" "Language-Team: FRENCH \n" "Language: fr\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" #: ../Doc/library/ctypes.rst:2 msgid ":mod:`ctypes` --- A foreign function library for Python" msgstr "" #: ../Doc/library/ctypes.rst:11 msgid "" ":mod:`ctypes` is a foreign function library for Python. It provides C " "compatible data types, and allows calling functions in DLLs or shared " "libraries. It can be used to wrap these libraries in pure Python." msgstr "" #: ../Doc/library/ctypes.rst:19 msgid "ctypes tutorial" msgstr "" #: ../Doc/library/ctypes.rst:21 msgid "" "Note: The code samples in this tutorial use :mod:`doctest` to make sure that " "they actually work. Since some code samples behave differently under Linux, " "Windows, or Mac OS X, they contain doctest directives in comments." msgstr "" #: ../Doc/library/ctypes.rst:25 msgid "" "Note: Some code samples reference the ctypes :class:`c_int` type. On " "platforms where ``sizeof(long) == sizeof(int)`` it is an alias to :class:" "`c_long`. So, you should not be confused if :class:`c_long` is printed if " "you would expect :class:`c_int` --- they are actually the same type." msgstr "" #: ../Doc/library/ctypes.rst:33 msgid "Loading dynamic link libraries" msgstr "" #: ../Doc/library/ctypes.rst:35 msgid "" ":mod:`ctypes` exports the *cdll*, and on Windows *windll* and *oledll* " "objects, for loading dynamic link libraries." msgstr "" #: ../Doc/library/ctypes.rst:38 msgid "" "You load libraries by accessing them as attributes of these objects. *cdll* " "loads libraries which export functions using the standard ``cdecl`` calling " "convention, while *windll* libraries call functions using the ``stdcall`` " "calling convention. *oledll* also uses the ``stdcall`` calling convention, " "and 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 function call fails." msgstr "" #: ../Doc/library/ctypes.rst:46 msgid "" "Windows errors used to raise :exc:`WindowsError`, which is now an alias of :" "exc:`OSError`." msgstr "" #: ../Doc/library/ctypes.rst:51 msgid "" "Here are some examples for Windows. Note that ``msvcrt`` is the MS standard " "C library containing most standard C functions, and uses the cdecl calling " "convention::" msgstr "" #: ../Doc/library/ctypes.rst:63 msgid "Windows appends the usual ``.dll`` file suffix automatically." msgstr "" #: ../Doc/library/ctypes.rst:66 msgid "" "Accessing the standard C library through ``cdll.msvcrt`` will use an " "outdated version of the library that may be incompatible with the one being " "used by Python. Where possible, use native Python functionality, or else " "import and use the ``msvcrt`` module." msgstr "" #: ../Doc/library/ctypes.rst:71 msgid "" "On Linux, it is required to specify the filename *including* the extension " "to load a library, so attribute access can not be used to load libraries. " "Either the :meth:`LoadLibrary` method of the dll loaders should be used, or " "you should load the library by creating an instance of CDLL by calling the " "constructor::" msgstr "" #: ../Doc/library/ctypes.rst:89 msgid "Accessing functions from loaded dlls" msgstr "" #: ../Doc/library/ctypes.rst:91 msgid "Functions are accessed as attributes of dll objects::" msgstr "" #: ../Doc/library/ctypes.rst:106 msgid "" "Note that win32 system dlls like ``kernel32`` and ``user32`` often export " "ANSI as well as UNICODE versions of a function. The UNICODE version is " "exported with an ``W`` appended to the name, while the ANSI version is " "exported with an ``A`` appended to the name. The win32 ``GetModuleHandle`` " "function, which returns a *module handle* for a given module name, has the " "following C prototype, and a macro is used to expose one of them as " "``GetModuleHandle`` depending on whether UNICODE is defined or not::" msgstr "" #: ../Doc/library/ctypes.rst:119 msgid "" "*windll* does not try to select one of them by magic, you must access the " "version you need by specifying ``GetModuleHandleA`` or ``GetModuleHandleW`` " "explicitly, and then call it with bytes or string objects respectively." msgstr "" #: ../Doc/library/ctypes.rst:123 msgid "" "Sometimes, dlls export functions with names which aren't valid Python " "identifiers, like ``\"??2@YAPAXI@Z\"``. In this case you have to use :func:" "`getattr` to retrieve the function::" msgstr "" #: ../Doc/library/ctypes.rst:131 msgid "" "On Windows, some dlls export functions not by name but by ordinal. These " "functions can be accessed by indexing the dll object with the ordinal " "number::" msgstr "" #: ../Doc/library/ctypes.rst:148 msgid "Calling functions" msgstr "" #: ../Doc/library/ctypes.rst:150 msgid "" "You can call these functions like any other Python callable. This example " "uses the ``time()`` function, which returns system time in seconds since the " "Unix epoch, and the ``GetModuleHandleA()`` function, which returns a win32 " "module handle." msgstr "" #: ../Doc/library/ctypes.rst:155 msgid "" "This example calls both functions with a ``NULL`` pointer (``None`` should " "be used as the ``NULL`` pointer)::" msgstr "" #: ../Doc/library/ctypes.rst:166 msgid "" ":mod:`ctypes` may raise a :exc:`ValueError` after calling the function, if " "it detects that an invalid number of arguments were passed. This behavior " "should not be relied upon. It is deprecated in 3.6.2, and will be removed " "in 3.7." msgstr "" #: ../Doc/library/ctypes.rst:171 msgid "" ":exc:`ValueError` is raised when you call an ``stdcall`` function with the " "``cdecl`` calling convention, or vice versa::" msgstr "" #: ../Doc/library/ctypes.rst:186 msgid "" "To find out the correct calling convention you have to look into the C " "header file or the documentation for the function you want to call." msgstr "" #: ../Doc/library/ctypes.rst:189 msgid "" "On Windows, :mod:`ctypes` uses win32 structured exception handling to " "prevent crashes from general protection faults when functions are called " "with invalid argument values::" msgstr "" #: ../Doc/library/ctypes.rst:199 msgid "" "There are, however, enough ways to crash Python with :mod:`ctypes`, so you " "should be careful anyway. The :mod:`faulthandler` module can be helpful in " "debugging crashes (e.g. from segmentation faults produced by erroneous C " "library calls)." msgstr "" #: ../Doc/library/ctypes.rst:204 msgid "" "``None``, integers, bytes objects and (unicode) strings are the only native " "Python objects that can directly be used as parameters in these function " "calls. ``None`` is passed as a C ``NULL`` pointer, bytes objects and strings " "are passed as pointer to the memory block that contains their data (:c:type:" "`char *` or :c:type:`wchar_t *`). Python integers are passed as the " "platforms default C :c:type:`int` type, their value is masked to fit into " "the C type." msgstr "" #: ../Doc/library/ctypes.rst:211 msgid "" "Before we move on calling functions with other parameter types, we have to " "learn more about :mod:`ctypes` data types." msgstr "" #: ../Doc/library/ctypes.rst:218 ../Doc/library/ctypes.rst:2135 msgid "Fundamental data types" msgstr "" #: ../Doc/library/ctypes.rst:220 msgid ":mod:`ctypes` defines a number of primitive C compatible data types:" msgstr "" #: ../Doc/library/ctypes.rst:223 msgid "ctypes type" msgstr "Type *ctype*" #: ../Doc/library/ctypes.rst:223 msgid "C type" msgstr "Type C" #: ../Doc/library/ctypes.rst:223 msgid "Python type" msgstr "Type Python" #: ../Doc/library/ctypes.rst:225 msgid ":class:`c_bool`" msgstr ":class:`c_bool`" #: ../Doc/library/ctypes.rst:225 msgid ":c:type:`_Bool`" msgstr ":c:type:`_Bool`" #: ../Doc/library/ctypes.rst:225 msgid "bool (1)" msgstr "bool (1)" #: ../Doc/library/ctypes.rst:227 msgid ":class:`c_char`" msgstr ":class:`c_char`" #: ../Doc/library/ctypes.rst:227 ../Doc/library/ctypes.rst:231 msgid ":c:type:`char`" msgstr ":c:type:`char`" #: ../Doc/library/ctypes.rst:227 msgid "1-character bytes object" msgstr "" #: ../Doc/library/ctypes.rst:229 msgid ":class:`c_wchar`" msgstr ":class:`c_wchar`" #: ../Doc/library/ctypes.rst:229 msgid ":c:type:`wchar_t`" msgstr ":c:type:`wchar_t`" #: ../Doc/library/ctypes.rst:229 msgid "1-character string" msgstr "" #: ../Doc/library/ctypes.rst:231 msgid ":class:`c_byte`" msgstr ":class:`c_byte`" #: ../Doc/library/ctypes.rst:231 ../Doc/library/ctypes.rst:233 #: ../Doc/library/ctypes.rst:235 ../Doc/library/ctypes.rst:237 #: ../Doc/library/ctypes.rst:239 ../Doc/library/ctypes.rst:241 #: ../Doc/library/ctypes.rst:243 ../Doc/library/ctypes.rst:245 #: ../Doc/library/ctypes.rst:247 ../Doc/library/ctypes.rst:249 #: ../Doc/library/ctypes.rst:252 ../Doc/library/ctypes.rst:254 msgid "int" msgstr "*int*" #: ../Doc/library/ctypes.rst:233 msgid ":class:`c_ubyte`" msgstr ":class:`c_ubyte`" #: ../Doc/library/ctypes.rst:233 msgid ":c:type:`unsigned char`" msgstr ":c:type:`unsigned char`" #: ../Doc/library/ctypes.rst:235 msgid ":class:`c_short`" msgstr ":class:`c_short`" #: ../Doc/library/ctypes.rst:235 msgid ":c:type:`short`" msgstr ":c:type:`short`" #: ../Doc/library/ctypes.rst:237 msgid ":class:`c_ushort`" msgstr ":class:`c_ushort`" #: ../Doc/library/ctypes.rst:237 msgid ":c:type:`unsigned short`" msgstr ":c:type:`unsigned short`" #: ../Doc/library/ctypes.rst:239 msgid ":class:`c_int`" msgstr ":class:`c_int`" #: ../Doc/library/ctypes.rst:239 msgid ":c:type:`int`" msgstr ":c:type:`int`" #: ../Doc/library/ctypes.rst:241 msgid ":class:`c_uint`" msgstr ":class:`c_uint`" #: ../Doc/library/ctypes.rst:241 msgid ":c:type:`unsigned int`" msgstr ":c:type:`unsigned int`" #: ../Doc/library/ctypes.rst:243 msgid ":class:`c_long`" msgstr ":class:`c_long`" #: ../Doc/library/ctypes.rst:243 msgid ":c:type:`long`" msgstr ":c:type:`long`" #: ../Doc/library/ctypes.rst:245 msgid ":class:`c_ulong`" msgstr ":class:`c_ulong`" #: ../Doc/library/ctypes.rst:245 msgid ":c:type:`unsigned long`" msgstr ":c:type:`unsigned long`" #: ../Doc/library/ctypes.rst:247 msgid ":class:`c_longlong`" msgstr ":class:`c_longlong`" #: ../Doc/library/ctypes.rst:247 msgid ":c:type:`__int64` or :c:type:`long long`" msgstr ":c:type:`__int64` ou :c:type:`long long`" #: ../Doc/library/ctypes.rst:249 msgid ":class:`c_ulonglong`" msgstr ":class:`c_ulonglong`" #: ../Doc/library/ctypes.rst:249 msgid ":c:type:`unsigned __int64` or :c:type:`unsigned long long`" msgstr "" #: ../Doc/library/ctypes.rst:252 msgid ":class:`c_size_t`" msgstr ":class:`c_size_t`" #: ../Doc/library/ctypes.rst:252 msgid ":c:type:`size_t`" msgstr ":c:type:`size_t`" #: ../Doc/library/ctypes.rst:254 msgid ":class:`c_ssize_t`" msgstr ":class:`c_ssize_t`" #: ../Doc/library/ctypes.rst:254 msgid ":c:type:`ssize_t` or :c:type:`Py_ssize_t`" msgstr ":c:type:`ssize_t` ou :c:type:`Py_ssize_t`" #: ../Doc/library/ctypes.rst:257 msgid ":class:`c_float`" msgstr ":class:`c_float`" #: ../Doc/library/ctypes.rst:257 msgid ":c:type:`float`" msgstr ":c:type:`float`" #: ../Doc/library/ctypes.rst:257 ../Doc/library/ctypes.rst:259 #: ../Doc/library/ctypes.rst:261 msgid "float" msgstr "*float*" #: ../Doc/library/ctypes.rst:259 msgid ":class:`c_double`" msgstr ":class:`c_double`" #: ../Doc/library/ctypes.rst:259 msgid ":c:type:`double`" msgstr ":c:type:`double`" #: ../Doc/library/ctypes.rst:261 msgid ":class:`c_longdouble`" msgstr ":class:`c_longdouble`" #: ../Doc/library/ctypes.rst:261 msgid ":c:type:`long double`" msgstr ":c:type:`long double`" #: ../Doc/library/ctypes.rst:263 msgid ":class:`c_char_p`" msgstr ":class:`c_char_p`" #: ../Doc/library/ctypes.rst:263 msgid ":c:type:`char *` (NUL terminated)" msgstr ":c:type:`char *` (NUL terminated)" #: ../Doc/library/ctypes.rst:263 msgid "bytes object or ``None``" msgstr "objet *bytes* ou ``None``" #: ../Doc/library/ctypes.rst:265 msgid ":class:`c_wchar_p`" msgstr ":class:`c_wchar_p`" #: ../Doc/library/ctypes.rst:265 msgid ":c:type:`wchar_t *` (NUL terminated)" msgstr ":c:type:`wchar_t *` (Terminé par NUL)" #: ../Doc/library/ctypes.rst:265 msgid "string or ``None``" msgstr "string ou ``None``" #: ../Doc/library/ctypes.rst:267 msgid ":class:`c_void_p`" msgstr ":class:`c_void_p`" #: ../Doc/library/ctypes.rst:267 msgid ":c:type:`void *`" msgstr ":c:type:`void *`" #: ../Doc/library/ctypes.rst:267 msgid "int or ``None``" msgstr "``int`` ou ``None``" #: ../Doc/library/ctypes.rst:271 msgid "The constructor accepts any object with a truth value." msgstr "" #: ../Doc/library/ctypes.rst:273 msgid "" "All these types can be created by calling them with an optional initializer " "of the correct type and value::" msgstr "" #: ../Doc/library/ctypes.rst:284 msgid "" "Since these types are mutable, their value can also be changed afterwards::" msgstr "" #: ../Doc/library/ctypes.rst:296 msgid "" "Assigning a new value to instances of the pointer types :class:`c_char_p`, :" "class:`c_wchar_p`, and :class:`c_void_p` changes the *memory location* they " "point to, *not the contents* of the memory block (of course not, because " "Python bytes objects are immutable)::" msgstr "" #: ../Doc/library/ctypes.rst:316 msgid "" "You should be careful, however, not to pass them to functions expecting " "pointers to mutable memory. If you need mutable memory blocks, ctypes has a :" "func:`create_string_buffer` function which creates these in various ways. " "The current memory block contents can be accessed (or changed) with the " "``raw`` property; if you want to access it as NUL terminated string, use the " "``value`` property::" msgstr "" #: ../Doc/library/ctypes.rst:340 msgid "" "The :func:`create_string_buffer` function replaces the :func:`c_buffer` " "function (which is still available as an alias), as well as the :func:" "`c_string` function from earlier ctypes releases. To create a mutable " "memory block containing unicode characters of the C type :c:type:`wchar_t` " "use the :func:`create_unicode_buffer` function." msgstr "" #: ../Doc/library/ctypes.rst:350 msgid "Calling functions, continued" msgstr "" #: ../Doc/library/ctypes.rst:352 msgid "" "Note that printf prints to the real standard output channel, *not* to :data:" "`sys.stdout`, so these examples will only work at the console prompt, not " "from within *IDLE* or *PythonWin*::" msgstr "" #: ../Doc/library/ctypes.rst:372 msgid "" "As has been mentioned before, all Python types except integers, strings, and " "bytes objects have to be wrapped in their corresponding :mod:`ctypes` type, " "so that they can be converted to the required C data type::" msgstr "" #: ../Doc/library/ctypes.rst:385 msgid "Calling functions with your own custom data types" msgstr "" #: ../Doc/library/ctypes.rst:387 msgid "" "You can also customize :mod:`ctypes` argument conversion to allow instances " "of your own classes be used as function arguments. :mod:`ctypes` looks for " "an :attr:`_as_parameter_` attribute and uses this as the function argument. " "Of course, it must be one of integer, string, or bytes::" msgstr "" #: ../Doc/library/ctypes.rst:402 msgid "" "If you don't want to store the instance's data in the :attr:`_as_parameter_` " "instance variable, you could define a :class:`property` which makes the " "attribute available on request." msgstr "" #: ../Doc/library/ctypes.rst:410 msgid "Specifying the required argument types (function prototypes)" msgstr "" #: ../Doc/library/ctypes.rst:412 msgid "" "It is possible to specify the required argument types of functions exported " "from DLLs by setting the :attr:`argtypes` attribute." msgstr "" #: ../Doc/library/ctypes.rst:415 msgid "" ":attr:`argtypes` must be a sequence of C data types (the ``printf`` function " "is probably not a good example here, because it takes a variable number and " "different types of parameters depending on the format string, on the other " "hand this is quite handy to experiment with this feature)::" msgstr "" #: ../Doc/library/ctypes.rst:426 msgid "" "Specifying a format protects against incompatible argument types (just as a " "prototype for a C function), and tries to convert the arguments to valid " "types::" msgstr "" #: ../Doc/library/ctypes.rst:438 msgid "" "If you have defined your own classes which you pass to function calls, you " "have to implement a :meth:`from_param` class method for them to be able to " "use them in the :attr:`argtypes` sequence. The :meth:`from_param` class " "method receives the Python object passed to the function call, it should do " "a typecheck or whatever is needed to make sure this object is acceptable, " "and then return the object itself, its :attr:`_as_parameter_` attribute, or " "whatever you want to pass as the C function argument in this case. Again, " "the result should be an integer, string, bytes, a :mod:`ctypes` instance, or " "an object with an :attr:`_as_parameter_` attribute." msgstr "" #: ../Doc/library/ctypes.rst:452 msgid "Return types" msgstr "" #: ../Doc/library/ctypes.rst:454 msgid "" "By default functions are assumed to return the C :c:type:`int` type. Other " "return types can be specified by setting the :attr:`restype` attribute of " "the function object." msgstr "" #: ../Doc/library/ctypes.rst:458 msgid "" "Here is a more advanced example, it uses the ``strchr`` function, which " "expects a string pointer and a char, and returns a pointer to a string::" msgstr "" #: ../Doc/library/ctypes.rst:471 msgid "" "If you want to avoid the ``ord(\"x\")`` calls above, you can set the :attr:" "`argtypes` attribute, and the second argument will be converted from a " "single character Python bytes object into a C char::" msgstr "" #: ../Doc/library/ctypes.rst:489 msgid "" "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 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 useful to check for error return values and " "automatically raise an exception::" msgstr "" #: ../Doc/library/ctypes.rst:512 msgid "" "``WinError`` is a function which will call Windows ``FormatMessage()`` api " "to get the string representation of an error code, and *returns* an " "exception. ``WinError`` takes an optional error code parameter, if no one is " "used, it calls :func:`GetLastError` to retrieve it." msgstr "" #: ../Doc/library/ctypes.rst:517 msgid "" "Please note that a much more powerful error checking mechanism is available " "through the :attr:`errcheck` attribute; see the reference manual for details." msgstr "" #: ../Doc/library/ctypes.rst:524 msgid "Passing pointers (or: passing parameters by reference)" msgstr "" #: ../Doc/library/ctypes.rst:526 msgid "" "Sometimes a C api function expects a *pointer* to a data type as parameter, " "probably to write into the corresponding location, or if the data is too " "large to be passed by value. This is also known as *passing parameters by " "reference*." msgstr "" #: ../Doc/library/ctypes.rst:530 msgid "" ":mod:`ctypes` exports the :func:`byref` function which is used to pass " "parameters by reference. The same effect can be achieved with the :func:" "`pointer` function, although :func:`pointer` does a lot more work since it " "constructs a real pointer object, so it is faster to use :func:`byref` if " "you don't need the pointer object in Python itself::" msgstr "" #: ../Doc/library/ctypes.rst:552 msgid "Structures and unions" msgstr "" #: ../Doc/library/ctypes.rst:554 msgid "" "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 define a :attr:`_fields_` attribute. :attr:`_fields_` must be " "a list of *2-tuples*, containing a *field name* and a *field type*." msgstr "" #: ../Doc/library/ctypes.rst:559 msgid "" "The field type must be a :mod:`ctypes` type like :class:`c_int`, or any " "other derived :mod:`ctypes` type: structure, union, array, pointer." msgstr "" #: ../Doc/library/ctypes.rst:562 msgid "" "Here is a simple example of a POINT structure, which contains two integers " "named *x* and *y*, and also shows how to initialize a structure in the " "constructor::" msgstr "" #: ../Doc/library/ctypes.rst:582 msgid "" "You can, however, build much more complicated structures. A structure can " "itself contain other structures by using a structure as a field type." msgstr "" #: ../Doc/library/ctypes.rst:585 msgid "" "Here is a RECT structure which contains two POINTs named *upperleft* and " "*lowerright*::" msgstr "" #: ../Doc/library/ctypes.rst:599 msgid "" "Nested structures can also be initialized in the constructor in several " "ways::" msgstr "" #: ../Doc/library/ctypes.rst:604 msgid "" "Field :term:`descriptor`\\s can be retrieved from the *class*, they are " "useful for debugging because they can provide useful information::" msgstr "" #: ../Doc/library/ctypes.rst:618 msgid "" ":mod:`ctypes` does not support passing unions or structures with bit-fields " "to functions by value. While this may work on 32-bit x86, it's not " "guaranteed by the library to work in the general case. Unions and " "structures with bit-fields should always be passed to functions by pointer." msgstr "" #: ../Doc/library/ctypes.rst:624 msgid "Structure/union alignment and byte order" msgstr "" #: ../Doc/library/ctypes.rst:626 msgid "" "By default, Structure and Union fields are aligned in the same way the C " "compiler does it. It is possible to override this behavior be specifying a :" "attr:`_pack_` class attribute in the subclass definition. This must be set " "to a positive integer and specifies the maximum alignment for the fields. " "This is what ``#pragma pack(n)`` also does in MSVC." msgstr "" #: ../Doc/library/ctypes.rst:632 msgid "" ":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 :class:" "`BigEndianStructure`, :class:`LittleEndianStructure`, :class:" "`BigEndianUnion`, and :class:`LittleEndianUnion` base classes. These " "classes cannot contain pointer fields." msgstr "" #: ../Doc/library/ctypes.rst:642 msgid "Bit fields in structures and unions" msgstr "" #: ../Doc/library/ctypes.rst:644 msgid "" "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 item in the :attr:`_fields_` tuples::" msgstr "" #: ../Doc/library/ctypes.rst:662 msgid "Arrays" msgstr "" #: ../Doc/library/ctypes.rst:664 msgid "" "Arrays are sequences, containing a fixed number of instances of the same " "type." msgstr "" #: ../Doc/library/ctypes.rst:666 msgid "" "The recommended way to create array types is by multiplying a data type with " "a positive integer::" msgstr "" #: ../Doc/library/ctypes.rst:671 msgid "" "Here is an example of a somewhat artificial data type, a structure " "containing 4 POINTs among other stuff::" msgstr "" #: ../Doc/library/ctypes.rst:687 msgid "Instances are created in the usual way, by calling the class::" msgstr "" #: ../Doc/library/ctypes.rst:693 msgid "" "The above code print a series of ``0 0`` lines, because the array contents " "is initialized to zeros." msgstr "" #: ../Doc/library/ctypes.rst:696 msgid "Initializers of the correct type can also be specified::" msgstr "" #: ../Doc/library/ctypes.rst:712 msgid "Pointers" msgstr "" #: ../Doc/library/ctypes.rst:714 msgid "" "Pointer instances are created by calling the :func:`pointer` function on a :" "mod:`ctypes` type::" msgstr "" #: ../Doc/library/ctypes.rst:722 msgid "" "Pointer instances have a :attr:`~_Pointer.contents` attribute which returns " "the object to which the pointer points, the ``i`` object above::" msgstr "" #: ../Doc/library/ctypes.rst:729 msgid "" "Note that :mod:`ctypes` does not have OOR (original object return), it " "constructs a new, equivalent object each time you retrieve an attribute::" msgstr "" #: ../Doc/library/ctypes.rst:738 msgid "" "Assigning another :class:`c_int` instance to the pointer's contents " "attribute would cause the pointer to point to the memory location where this " "is stored::" msgstr "" #: ../Doc/library/ctypes.rst:750 msgid "Pointer instances can also be indexed with integers::" msgstr "" #: ../Doc/library/ctypes.rst:756 msgid "Assigning to an integer index changes the pointed to value::" msgstr "" #: ../Doc/library/ctypes.rst:765 msgid "" "It is also possible to use indexes different from 0, but you must know what " "you're doing, just as in C: You can access or change arbitrary memory " "locations. Generally you only use this feature if you receive a pointer from " "a C function, and you *know* that the pointer actually points to an array " "instead of a single item." msgstr "" #: ../Doc/library/ctypes.rst:771 msgid "" "Behind the scenes, the :func:`pointer` function does more than simply create " "pointer instances, it has to create pointer *types* first. This is done with " "the :func:`POINTER` function, which accepts any :mod:`ctypes` type, and " "returns a new type::" msgstr "" #: ../Doc/library/ctypes.rst:787 msgid "" "Calling the pointer type without an argument creates a ``NULL`` pointer. " "``NULL`` pointers have a ``False`` boolean value::" msgstr "" #: ../Doc/library/ctypes.rst:795 msgid "" ":mod:`ctypes` checks for ``NULL`` when dereferencing pointers (but " "dereferencing invalid non-\\ ``NULL`` pointers would crash Python)::" msgstr "" #: ../Doc/library/ctypes.rst:814 msgid "Type conversions" msgstr "" #: ../Doc/library/ctypes.rst:816 msgid "" "Usually, ctypes does strict type checking. This means, if you have " "``POINTER(c_int)`` in the :attr:`argtypes` list of a function or as the type " "of a member field in a structure definition, only instances of exactly the " "same type are accepted. There are some exceptions to this rule, where " "ctypes accepts other objects. For example, you can pass compatible array " "instances instead of pointer types. So, for ``POINTER(c_int)``, ctypes " "accepts an array of c_int::" msgstr "" #: ../Doc/library/ctypes.rst:837 msgid "" "In addition, if a function argument is explicitly declared to be a pointer " "type (such as ``POINTER(c_int)``) in :attr:`argtypes`, an object of the " "pointed type (``c_int`` in this case) can be passed to the function. ctypes " "will apply the required :func:`byref` conversion in this case automatically." msgstr "" #: ../Doc/library/ctypes.rst:842 msgid "To set a POINTER type field to ``NULL``, you can assign ``None``::" msgstr "" #: ../Doc/library/ctypes.rst:849 msgid "" "Sometimes you have instances of incompatible types. In C, you can cast one " "type into another type. :mod:`ctypes` provides a :func:`cast` function " "which can be used in the same way. The ``Bar`` structure defined above " "accepts ``POINTER(c_int)`` pointers or :class:`c_int` arrays for its " "``values`` field, but not instances of other types::" msgstr "" #: ../Doc/library/ctypes.rst:861 msgid "For these cases, the :func:`cast` function is handy." msgstr "" #: ../Doc/library/ctypes.rst:863 msgid "" "The :func:`cast` function can be used to cast a ctypes instance into a " "pointer to a different ctypes data type. :func:`cast` takes two parameters, " "a ctypes object that is or can be converted to a pointer of some kind, and a " "ctypes pointer type. It returns an instance of the second argument, which " "references the same memory block as the first argument::" msgstr "" #: ../Doc/library/ctypes.rst:874 msgid "" "So, :func:`cast` can be used to assign to the ``values`` field of ``Bar`` " "the structure::" msgstr "" #: ../Doc/library/ctypes.rst:887 msgid "Incomplete Types" msgstr "" #: ../Doc/library/ctypes.rst:889 msgid "" "*Incomplete Types* are structures, unions or arrays whose members are not " "yet specified. In C, they are specified by forward declarations, which are " "defined later::" msgstr "" #: ../Doc/library/ctypes.rst:900 msgid "" "The straightforward translation into ctypes code would be this, but it does " "not work::" msgstr "" #: ../Doc/library/ctypes.rst:913 msgid "" "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_` attribute later, after the class statement::" msgstr "" #: ../Doc/library/ctypes.rst:925 msgid "" "Lets try it. We create two instances of ``cell``, and let them point to each " "other, and finally follow the pointer chain a few times::" msgstr "" #: ../Doc/library/ctypes.rst:946 msgid "Callback functions" msgstr "" #: ../Doc/library/ctypes.rst:948 msgid "" ":mod:`ctypes` allows creating C callable function pointers from Python " "callables. These are sometimes called *callback functions*." msgstr "" #: ../Doc/library/ctypes.rst:951 msgid "" "First, you must create a class for the callback function. The class knows " "the calling convention, the return type, and the number and types of " "arguments this function will receive." msgstr "" #: ../Doc/library/ctypes.rst:955 msgid "" "The :func:`CFUNCTYPE` factory function creates types for callback functions " "using the ``cdecl`` calling convention. On Windows, the :func:`WINFUNCTYPE` " "factory function creates types for callback functions using the ``stdcall`` " "calling convention." msgstr "" #: ../Doc/library/ctypes.rst:960 msgid "" "Both of these factory functions are called with the result type as first " "argument, and the callback functions expected argument types as the " "remaining arguments." msgstr "" #: ../Doc/library/ctypes.rst:964 msgid "" "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 " "function. :c:func:`qsort` will be used to sort an array of integers::" msgstr "" #: ../Doc/library/ctypes.rst:974 msgid "" ":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 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 the second, a zero if they are equal, and a positive integer " "otherwise." msgstr "" #: ../Doc/library/ctypes.rst:980 msgid "" "So our callback function receives pointers to integers, and must return an " "integer. First we create the ``type`` for the callback function::" msgstr "" #: ../Doc/library/ctypes.rst:986 msgid "" "To get started, here is a simple callback that shows the values it gets " "passed::" msgstr "" #: ../Doc/library/ctypes.rst:996 msgid "The result::" msgstr "" #: ../Doc/library/ctypes.rst:1006 msgid "Now we can actually compare the two items and return a useful result::" msgstr "" #: ../Doc/library/ctypes.rst:1021 msgid "As we can easily check, our array is sorted now::" msgstr "" #: ../Doc/library/ctypes.rst:1028 msgid "" "The function factories can be used as decorator factories, so we may as well " "write::" msgstr "" #: ../Doc/library/ctypes.rst:1046 msgid "" "Make sure you keep references to :func:`CFUNCTYPE` objects as long as they " "are used from C code. :mod:`ctypes` doesn't, and if you don't, they may be " "garbage collected, crashing your program when a callback is made." msgstr "" #: ../Doc/library/ctypes.rst:1050 msgid "" "Also, note that if the callback function is called in a thread created " "outside of Python's control (e.g. by the foreign code that calls the " "callback), ctypes creates a new dummy Python thread on every invocation. " "This behavior is correct for most purposes, but it means that values stored " "with :class:`threading.local` will *not* survive across different callbacks, " "even when those calls are made from the same C thread." msgstr "" #: ../Doc/library/ctypes.rst:1060 msgid "Accessing values exported from dlls" msgstr "" #: ../Doc/library/ctypes.rst:1062 msgid "" "Some shared libraries not only export functions, they also export variables. " "An example in the Python library itself is the :c:data:`Py_OptimizeFlag`, an " "integer set to 0, 1, or 2, depending on the :option:`-O` or :option:`-OO` " "flag given on startup." msgstr "" #: ../Doc/library/ctypes.rst:1067 msgid "" ":mod:`ctypes` can access values like this with the :meth:`in_dll` class " "methods of the type. *pythonapi* is a predefined symbol giving access to " "the Python C api::" msgstr "" #: ../Doc/library/ctypes.rst:1076 msgid "" "If the interpreter would have been started with :option:`-O`, the sample " "would have printed ``c_long(1)``, or ``c_long(2)`` if :option:`-OO` would " "have been specified." msgstr "" #: ../Doc/library/ctypes.rst:1080 msgid "" "An extended example which also demonstrates the use of pointers accesses " "the :c:data:`PyImport_FrozenModules` pointer exported by Python." msgstr "" #: ../Doc/library/ctypes.rst:1083 msgid "Quoting the docs for that value:" msgstr "" #: ../Doc/library/ctypes.rst:1085 msgid "" "This pointer is initialized to point to an array of :c:type:`struct _frozen` " "records, terminated by one whose members are all ``NULL`` or zero. When a " "frozen module is imported, it is searched in this table. Third-party code " "could play tricks with this to provide a dynamically created collection of " "frozen modules." msgstr "" #: ../Doc/library/ctypes.rst:1090 msgid "" "So manipulating this pointer could even prove useful. To restrict the " "example size, we show only how this table can be read with :mod:`ctypes`::" msgstr "" #: ../Doc/library/ctypes.rst:1102 msgid "" "We have defined the :c:type:`struct _frozen` data type, so we can get the " "pointer to the table::" msgstr "" #: ../Doc/library/ctypes.rst:1109 msgid "" "Since ``table`` is a ``pointer`` to the array of ``struct_frozen`` records, " "we can iterate over it, but we just have to make sure that our loop " "terminates, because pointers have no size. Sooner or later it would probably " "crash with an access violation or whatever, so it's better to break out of " "the loop when we hit the ``NULL`` entry::" msgstr "" #: ../Doc/library/ctypes.rst:1127 msgid "" "The fact that standard Python has a frozen module and a frozen package " "(indicated by the negative size member) is not well known, it is only used " "for testing. Try it out with ``import __hello__`` for example." msgstr "" #: ../Doc/library/ctypes.rst:1135 msgid "Surprises" msgstr "Surprises" #: ../Doc/library/ctypes.rst:1137 msgid "" "There are some edges in :mod:`ctypes` where you might expect something other " "than what actually happens." msgstr "" #: ../Doc/library/ctypes.rst:1140 msgid "Consider the following example::" msgstr "" #: ../Doc/library/ctypes.rst:1160 msgid "" "Hm. We certainly expected the last statement to print ``3 4 1 2``. What " "happened? Here are the steps of the ``rc.a, rc.b = rc.b, rc.a`` line above::" msgstr "" #: ../Doc/library/ctypes.rst:1168 msgid "" "Note that ``temp0`` and ``temp1`` are objects still using the internal " "buffer of the ``rc`` object above. So executing ``rc.a = temp0`` copies the " "buffer contents of ``temp0`` into ``rc`` 's buffer. This, in turn, changes " "the contents of ``temp1``. So, the last assignment ``rc.b = temp1``, doesn't " "have the expected effect." msgstr "" #: ../Doc/library/ctypes.rst:1174 msgid "" "Keep in mind that retrieving sub-objects from Structure, Unions, and Arrays " "doesn't *copy* the sub-object, instead it retrieves a wrapper object " "accessing the root-object's underlying buffer." msgstr "" #: ../Doc/library/ctypes.rst:1178 msgid "" "Another example that may behave differently from what one would expect is " "this::" msgstr "" #: ../Doc/library/ctypes.rst:1190 msgid "" "Objects instantiated from :class:`c_char_p` can only have their value set to " "bytes or integers." msgstr "" #: ../Doc/library/ctypes.rst:1193 msgid "" "Why is it printing ``False``? ctypes instances are objects containing a " "memory block plus some :term:`descriptor`\\s accessing the contents of the " "memory. Storing a Python object in the memory block does not store the " "object itself, instead the ``contents`` of the object is stored. Accessing " "the contents again constructs a new Python object each time!" msgstr "" #: ../Doc/library/ctypes.rst:1203 msgid "Variable-sized data types" msgstr "" #: ../Doc/library/ctypes.rst:1205 msgid "" ":mod:`ctypes` provides some support for variable-sized arrays and structures." msgstr "" #: ../Doc/library/ctypes.rst:1207 msgid "" "The :func:`resize` function can be used to resize the memory buffer of an " "existing ctypes object. The function takes the object as first argument, " "and the requested size in bytes as the second argument. The memory block " "cannot be made smaller than the natural memory block specified by the " "objects type, a :exc:`ValueError` is raised if this is tried::" msgstr "" #: ../Doc/library/ctypes.rst:1227 msgid "" "This is nice and fine, but how would one access the additional elements " "contained in this array? Since the type still only knows about 4 elements, " "we get errors accessing other elements::" msgstr "" #: ../Doc/library/ctypes.rst:1239 msgid "" "Another way to use variable-sized data types with :mod:`ctypes` is to use " "the dynamic nature of Python, and (re-)define the data type after the " "required size is already known, on a case by case basis." msgstr "" #: ../Doc/library/ctypes.rst:1247 msgid "ctypes reference" msgstr "" #: ../Doc/library/ctypes.rst:1253 msgid "Finding shared libraries" msgstr "" #: ../Doc/library/ctypes.rst:1255 msgid "" "When programming in a compiled language, shared libraries are accessed when " "compiling/linking a program, and when the program is run." msgstr "" #: ../Doc/library/ctypes.rst:1258 msgid "" "The purpose of the :func:`find_library` function is to locate a library in a " "way 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 library loaders act like when a program is run, and call " "the runtime loader directly." msgstr "" #: ../Doc/library/ctypes.rst:1264 msgid "" "The :mod:`ctypes.util` module provides a function which can help to " "determine the library to load." msgstr "" #: ../Doc/library/ctypes.rst:1272 msgid "" "Try to find a library and return a pathname. *name* is the library name " "without any prefix like *lib*, suffix like ``.so``, ``.dylib`` or version " "number (this is the form used for the posix linker option :option:`!-l`). " "If no library can be found, returns ``None``." msgstr "" #: ../Doc/library/ctypes.rst:1277 ../Doc/library/ctypes.rst:1910 msgid "The exact functionality is system dependent." msgstr "" #: ../Doc/library/ctypes.rst:1279 msgid "" "On Linux, :func:`find_library` tries to run external programs (``/sbin/" "ldconfig``, ``gcc``, ``objdump`` and ``ld``) to find the library file. It " "returns the filename of the library file." msgstr "" #: ../Doc/library/ctypes.rst:1283 msgid "" "On Linux, the value of the environment variable ``LD_LIBRARY_PATH`` is used " "when searching for libraries, if a library cannot be found by any other " "means." msgstr "" #: ../Doc/library/ctypes.rst:1287 msgid "Here are some examples::" msgstr "" #: ../Doc/library/ctypes.rst:1298 msgid "" "On OS X, :func:`find_library` tries several predefined naming schemes and " "paths to locate the library, and returns a full pathname if successful::" msgstr "" #: ../Doc/library/ctypes.rst:1312 msgid "" "On Windows, :func:`find_library` searches along the system search path, and " "returns the full pathname, but since there is no predefined naming scheme a " "call like ``find_library(\"c\")`` will fail and return ``None``." msgstr "" #: ../Doc/library/ctypes.rst:1316 msgid "" "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 module instead of using :func:`find_library` to locate the " "library at runtime." msgstr "" #: ../Doc/library/ctypes.rst:1324 msgid "Loading shared libraries" msgstr "" #: ../Doc/library/ctypes.rst:1326 msgid "" "There are several ways to load shared libraries into the Python process. " "One way is to instantiate one of the following classes:" msgstr "" #: ../Doc/library/ctypes.rst:1332 msgid "" "Instances of this class represent loaded shared libraries. Functions in " "these libraries use the standard C calling convention, and are assumed to " "return :c:type:`int`." msgstr "" #: ../Doc/library/ctypes.rst:1339 msgid "" "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` 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." msgstr "" #: ../Doc/library/ctypes.rst:1346 msgid ":exc:`WindowsError` used to be raised." msgstr "" #: ../Doc/library/ctypes.rst:1352 msgid "" "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:type:`int` by default." msgstr "" #: ../Doc/library/ctypes.rst:1356 msgid "" "On Windows CE only the standard calling convention is used, for convenience " "the :class:`WinDLL` and :class:`OleDLL` use the standard calling convention " "on this platform." msgstr "" #: ../Doc/library/ctypes.rst:1360 msgid "" "The Python :term:`global interpreter lock` is released before calling any " "function exported by these libraries, and reacquired afterwards." msgstr "" #: ../Doc/library/ctypes.rst:1366 msgid "" "Instances of this class behave like :class:`CDLL` instances, except that the " "Python GIL is *not* released during the function call, and after the " "function execution the Python error flag is checked. If the error flag is " "set, a Python exception is raised." msgstr "" #: ../Doc/library/ctypes.rst:1371 msgid "Thus, this is only useful to call Python C api functions directly." msgstr "" #: ../Doc/library/ctypes.rst:1373 msgid "" "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 an already loaded shared library, it can be passed as the " "``handle`` named parameter, otherwise the underlying platforms ``dlopen`` or " "``LoadLibrary`` function is used to load the library into the process, and " "to get a handle to it." msgstr "" #: ../Doc/library/ctypes.rst:1380 msgid "" "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 " "ignored. On posix systems, RTLD_NOW is always added, and is not " "configurable." msgstr "" #: ../Doc/library/ctypes.rst:1385 msgid "" "The *use_errno* parameter, when set to true, enables a ctypes mechanism that " "allows accessing the system :data:`errno` error number in a safe way. :mod:" "`ctypes` maintains a thread-local copy of the systems :data:`errno` " "variable; if you call foreign functions created with ``use_errno=True`` then " "the :data:`errno` value before the function call is swapped with the ctypes " "private copy, the same happens immediately after the function call." msgstr "" #: ../Doc/library/ctypes.rst:1392 msgid "" "The function :func:`ctypes.get_errno` returns the value of the ctypes " "private copy, and the function :func:`ctypes.set_errno` changes the ctypes " "private copy to a new value and returns the former value." msgstr "" #: ../Doc/library/ctypes.rst:1396 msgid "" "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 :" "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 copy of the windows error code." msgstr "" #: ../Doc/library/ctypes.rst:1402 msgid "" "The *winmode* parameter is used on Windows to specify how the library is " "loaded (since *mode* is ignored). It takes any value that is valid for the " "Win32 API ``LoadLibraryEx`` flags parameter. When omitted, the default is to " "use the flags that result in the most secure DLL load to avoiding issues " "such as DLL hijacking. Passing the full path to the DLL is the safest way to " "ensure the correct library and dependencies are loaded." msgstr "" #: ../Doc/library/ctypes.rst:1409 msgid "Added *winmode* parameter." msgstr "" #: ../Doc/library/ctypes.rst:1416 msgid "" "Flag to use as *mode* parameter. On platforms where this flag is not " "available, it is defined as the integer zero." msgstr "" #: ../Doc/library/ctypes.rst:1423 msgid "" "Flag to use as *mode* parameter. On platforms where this is not available, " "it is the same as *RTLD_GLOBAL*." msgstr "" #: ../Doc/library/ctypes.rst:1430 msgid "" "The default mode which is used to load shared libraries. On OSX 10.3, this " "is *RTLD_GLOBAL*, otherwise it is the same as *RTLD_LOCAL*." msgstr "" #: ../Doc/library/ctypes.rst:1433 msgid "" "Instances of these classes have no public methods. Functions exported by " "the shared library can be accessed as attributes or by index. Please note " "that accessing the function through an attribute caches the result and " "therefore accessing it repeatedly returns the same object each time. On the " "other hand, accessing it through an index returns a new object each time::" msgstr "" #: ../Doc/library/ctypes.rst:1446 msgid "" "The following public attributes are available, their name starts with an " "underscore to not clash with exported function names:" msgstr "" #: ../Doc/library/ctypes.rst:1452 msgid "The system handle used to access the library." msgstr "" #: ../Doc/library/ctypes.rst:1457 msgid "The name of the library passed in the constructor." msgstr "" #: ../Doc/library/ctypes.rst:1459 msgid "" "Shared libraries can also be loaded by using one of the prefabricated " "objects, which are instances of the :class:`LibraryLoader` class, either by " "calling the :meth:`LoadLibrary` method, or by retrieving the library as " "attribute of the loader instance." msgstr "" #: ../Doc/library/ctypes.rst:1467 msgid "" "Class which loads shared libraries. *dlltype* should be one of the :class:" "`CDLL`, :class:`PyDLL`, :class:`WinDLL`, or :class:`OleDLL` types." msgstr "" #: ../Doc/library/ctypes.rst:1470 msgid "" ":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, so repeated attribute accesses return the same library each time." msgstr "" #: ../Doc/library/ctypes.rst:1476 msgid "" "Load a shared library into the process and return it. This method always " "returns a new instance of the library." msgstr "" #: ../Doc/library/ctypes.rst:1480 msgid "These prefabricated library loaders are available:" msgstr "" #: ../Doc/library/ctypes.rst:1485 msgid "Creates :class:`CDLL` instances." msgstr "" #: ../Doc/library/ctypes.rst:1491 msgid "Windows only: Creates :class:`WinDLL` instances." msgstr "" #: ../Doc/library/ctypes.rst:1497 msgid "Windows only: Creates :class:`OleDLL` instances." msgstr "" #: ../Doc/library/ctypes.rst:1503 msgid "Creates :class:`PyDLL` instances." msgstr "" #: ../Doc/library/ctypes.rst:1506 msgid "" "For accessing the C Python api directly, a ready-to-use Python shared " "library object is available:" msgstr "" #: ../Doc/library/ctypes.rst:1512 msgid "" "An instance of :class:`PyDLL` that exposes Python C API functions as " "attributes. Note that all these functions are assumed to return C :c:type:" "`int`, which is of course not always the truth, so you have to assign the " "correct :attr:`restype` attribute to use these functions." msgstr "" #: ../Doc/library/ctypes.rst:None msgid "" "Raises an :ref:`auditing event ` ``ctypes.dlopen`` with argument " "``name``." msgstr "" #: ../Doc/library/ctypes.rst:1519 msgid "" "Loading a library through any of these objects raises an :ref:`auditing " "event ` ``ctypes.dlopen`` with string argument ``name``, the name " "used to load the library." msgstr "" #: ../Doc/library/ctypes.rst:None msgid "" "Raises an :ref:`auditing event ` ``ctypes.dlsym`` with arguments " "``library``, ``name``." msgstr "" #: ../Doc/library/ctypes.rst:1525 msgid "" "Accessing a function on a loaded library raises an auditing event ``ctypes." "dlsym`` with arguments ``library`` (the library object) and ``name`` (the " "symbol's name as a string or integer)." msgstr "" #: ../Doc/library/ctypes.rst:None msgid "" "Raises an :ref:`auditing event ` ``ctypes.dlsym/handle`` with " "arguments ``handle``, ``name``." msgstr "" #: ../Doc/library/ctypes.rst:1531 msgid "" "In cases when only the library handle is available rather than the object, " "accessing a function raises an auditing event ``ctypes.dlsym/handle`` with " "arguments ``handle`` (the raw library handle) and ``name``." msgstr "" #: ../Doc/library/ctypes.rst:1538 msgid "Foreign functions" msgstr "" #: ../Doc/library/ctypes.rst:1540 msgid "" "As explained in the previous section, foreign functions can be accessed as " "attributes of loaded shared libraries. The function objects created in this " "way by default accept any number of arguments, accept any ctypes data " "instances as arguments, and return the default result type specified by the " "library loader. They are instances of a private class:" msgstr "" #: ../Doc/library/ctypes.rst:1549 msgid "Base class for C callable foreign functions." msgstr "" #: ../Doc/library/ctypes.rst:1551 msgid "" "Instances of foreign functions are also C compatible data types; they " "represent C function pointers." msgstr "" #: ../Doc/library/ctypes.rst:1554 msgid "" "This behavior can be customized by assigning to special attributes of the " "foreign function object." msgstr "" #: ../Doc/library/ctypes.rst:1559 msgid "" "Assign a ctypes type to specify the result type of the foreign function. Use " "``None`` for :c:type:`void`, a function not returning anything." msgstr "" #: ../Doc/library/ctypes.rst:1562 msgid "" "It is possible to assign a callable Python object that is not a ctypes type, " "in this case the function is assumed to return a C :c:type:`int`, and the " "callable will be called with this integer, allowing further processing or " "error checking. Using this is deprecated, for more flexible post processing " "or error checking use a ctypes data type as :attr:`restype` and assign a " "callable to the :attr:`errcheck` attribute." msgstr "" #: ../Doc/library/ctypes.rst:1571 msgid "" "Assign a tuple of ctypes types to specify the argument types that the " "function accepts. Functions using the ``stdcall`` calling convention can " "only be called with the same number of arguments as the length of this " "tuple; functions using the C calling convention accept additional, " "unspecified arguments as well." msgstr "" #: ../Doc/library/ctypes.rst:1577 msgid "" "When a foreign function is called, each actual argument is passed to the :" "meth:`from_param` class method of the items in the :attr:`argtypes` tuple, " "this method allows adapting the actual argument to an object that the " "foreign function accepts. For example, a :class:`c_char_p` item in the :" "attr:`argtypes` tuple will convert a string passed as argument into a bytes " "object using ctypes conversion rules." msgstr "" #: ../Doc/library/ctypes.rst:1584 msgid "" "New: It is now possible to put items in argtypes which are not ctypes types, " "but each item must have a :meth:`from_param` method which returns a value " "usable as argument (integer, string, ctypes instance). This allows defining " "adapters that can adapt custom objects as function parameters." msgstr "" #: ../Doc/library/ctypes.rst:1591 msgid "" "Assign a Python function or another callable to this attribute. The callable " "will be called with three or more arguments:" msgstr "" #: ../Doc/library/ctypes.rst:1598 msgid "" "*result* is what the foreign function returns, as specified by the :attr:" "`restype` attribute." msgstr "" #: ../Doc/library/ctypes.rst:1601 msgid "" "*func* is the foreign function object itself, this allows reusing the same " "callable object to check or post process the results of several functions." msgstr "" #: ../Doc/library/ctypes.rst:1605 msgid "" "*arguments* is a tuple containing the parameters originally passed to the " "function call, this allows specializing the behavior on the arguments used." msgstr "" #: ../Doc/library/ctypes.rst:1609 msgid "" "The object that this function returns will be returned from the foreign " "function call, but it can also check the result value and raise an exception " "if the foreign function call failed." msgstr "" #: ../Doc/library/ctypes.rst:1616 msgid "" "This exception is raised when a foreign function call cannot convert one of " "the passed arguments." msgstr "" #: ../Doc/library/ctypes.rst:None msgid "" "Raises an :ref:`auditing event ` ``ctypes.seh_exception`` with " "argument ``code``." msgstr "" #: ../Doc/library/ctypes.rst:1622 msgid "" "On Windows, when a foreign function call raises a system exception (for " "example, due to an access violation), it will be captured and replaced with " "a suitable Python exception. Further, an auditing event ``ctypes." "seh_exception`` with argument ``code`` will be raised, allowing an audit " "hook to replace the exception with its own." msgstr "" #: ../Doc/library/ctypes.rst:None msgid "" "Raises an :ref:`auditing event ` ``ctypes.call_function`` with " "arguments ``func_pointer``, ``arguments``." msgstr "" #: ../Doc/library/ctypes.rst:1630 msgid "" "Some ways to invoke foreign function calls may raise an auditing event " "``ctypes.call_function`` with arguments ``function pointer`` and " "``arguments``." msgstr "" #: ../Doc/library/ctypes.rst:1636 msgid "Function prototypes" msgstr "" #: ../Doc/library/ctypes.rst:1638 msgid "" "Foreign functions can also be created by instantiating function prototypes. " "Function prototypes are similar to function prototypes in C; they describe a " "function (return type, argument types, calling convention) without defining " "an implementation. The factory functions must be called with the desired " "result type and the argument types of the function, and can be used as " "decorator factories, and as such, be applied to functions through the " "``@wrapper`` syntax. See :ref:`ctypes-callback-functions` for examples." msgstr "" #: ../Doc/library/ctypes.rst:1649 msgid "" "The returned function prototype creates functions that use the standard C " "calling convention. The function will release the GIL during the call. If " "*use_errno* is set to true, the ctypes private copy of the system :data:" "`errno` variable is exchanged with the real :data:`errno` value before and " "after the call; *use_last_error* does the same for the Windows error code." msgstr "" #: ../Doc/library/ctypes.rst:1659 msgid "" "Windows only: The returned function prototype creates functions that use the " "``stdcall`` calling convention, except on Windows CE where :func:" "`WINFUNCTYPE` is the same as :func:`CFUNCTYPE`. The function will release " "the GIL during the call. *use_errno* and *use_last_error* have the same " "meaning as above." msgstr "" #: ../Doc/library/ctypes.rst:1668 msgid "" "The returned function prototype creates functions that use the Python " "calling convention. The function will *not* release the GIL during the call." msgstr "" #: ../Doc/library/ctypes.rst:1671 msgid "" "Function prototypes created by these factory functions can be instantiated " "in different ways, depending on the type and number of the parameters in the " "call:" msgstr "" #: ../Doc/library/ctypes.rst:1679 msgid "" "Returns a foreign function at the specified address which must be an integer." msgstr "" #: ../Doc/library/ctypes.rst:1686 msgid "" "Create a C callable function (a callback function) from a Python *callable*." msgstr "" #: ../Doc/library/ctypes.rst:1693 msgid "" "Returns a foreign function exported by a shared library. *func_spec* must be " "a 2-tuple ``(name_or_ordinal, library)``. The first item is the name of the " "exported function as string, or the ordinal of the exported function as " "small integer. The second item is the shared library instance." msgstr "" #: ../Doc/library/ctypes.rst:1703 msgid "" "Returns a foreign function that will call a COM method. *vtbl_index* is the " "index into the virtual function table, a small non-negative integer. *name* " "is name of the COM method. *iid* is an optional pointer to the interface " "identifier which is used in extended error reporting." msgstr "" #: ../Doc/library/ctypes.rst:1708 msgid "" "COM methods use a special calling convention: They require a pointer to the " "COM interface as first argument, in addition to those parameters that are " "specified in the :attr:`argtypes` tuple." msgstr "" #: ../Doc/library/ctypes.rst:1712 msgid "" "The optional *paramflags* parameter creates foreign function wrappers with " "much more functionality than the features described above." msgstr "" #: ../Doc/library/ctypes.rst:1715 msgid "*paramflags* must be a tuple of the same length as :attr:`argtypes`." msgstr "" #: ../Doc/library/ctypes.rst:1717 msgid "" "Each item in this tuple contains further information about a parameter, it " "must be a tuple containing one, two, or three items." msgstr "" #: ../Doc/library/ctypes.rst:1720 msgid "" "The first item is an integer containing a combination of direction flags for " "the parameter:" msgstr "" #: ../Doc/library/ctypes.rst:1724 msgid "1" msgstr "1" #: ../Doc/library/ctypes.rst:1724 msgid "Specifies an input parameter to the function." msgstr "" #: ../Doc/library/ctypes.rst:1727 msgid "2" msgstr "2" #: ../Doc/library/ctypes.rst:1727 msgid "Output parameter. The foreign function fills in a value." msgstr "" #: ../Doc/library/ctypes.rst:1730 msgid "4" msgstr "4" #: ../Doc/library/ctypes.rst:1730 msgid "Input parameter which defaults to the integer zero." msgstr "" #: ../Doc/library/ctypes.rst:1732 msgid "" "The optional second item is the parameter name as string. If this is " "specified, the foreign function can be called with named parameters." msgstr "" #: ../Doc/library/ctypes.rst:1735 msgid "The optional third item is the default value for this parameter." msgstr "" #: ../Doc/library/ctypes.rst:1737 msgid "" "This example demonstrates how to wrap the Windows ``MessageBoxW`` function " "so that it supports default parameters and named arguments. The C " "declaration from the windows header file is this::" msgstr "" #: ../Doc/library/ctypes.rst:1748 ../Doc/library/ctypes.rst:1771 msgid "Here is the wrapping with :mod:`ctypes`::" msgstr "" #: ../Doc/library/ctypes.rst:1756 msgid "The ``MessageBox`` foreign function can now be called in these ways::" msgstr "" #: ../Doc/library/ctypes.rst:1762 msgid "" "A second example demonstrates output parameters. The win32 " "``GetWindowRect`` function retrieves the dimensions of a specified window by " "copying them into ``RECT`` structure that the caller has to supply. Here is " "the C declaration::" msgstr "" #: ../Doc/library/ctypes.rst:1780 msgid "" "Functions with output parameters will automatically return the output " "parameter 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 RECT instance, when called." msgstr "" #: ../Doc/library/ctypes.rst:1785 msgid "" "Output parameters can be combined with the :attr:`errcheck` protocol to do " "further output processing and error checking. The win32 ``GetWindowRect`` " "api 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::" msgstr "" #: ../Doc/library/ctypes.rst:1798 msgid "" "If the :attr:`errcheck` function returns the argument tuple it receives " "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 ``RECT`` instance, you can retrieve the fields in the function " "and return them instead, the normal processing will no longer take place::" msgstr "" #: ../Doc/library/ctypes.rst:1817 msgid "Utility functions" msgstr "" #: ../Doc/library/ctypes.rst:1821 msgid "" "Returns the address of the memory buffer as integer. *obj* must be an " "instance of a ctypes type." msgstr "" #: ../Doc/library/ctypes.rst:1824 msgid "" "Raises an :ref:`auditing event ` ``ctypes.addressof`` with " "argument ``obj``." msgstr "" #: ../Doc/library/ctypes.rst:1829 msgid "" "Returns the alignment requirements of a ctypes type. *obj_or_type* must be a " "ctypes type or instance." msgstr "" #: ../Doc/library/ctypes.rst:1835 msgid "" "Returns a light-weight pointer to *obj*, which must be an instance of a " "ctypes type. *offset* defaults to zero, and must be an integer that will be " "added to the internal pointer value." msgstr "" #: ../Doc/library/ctypes.rst:1839 msgid "``byref(obj, offset)`` corresponds to this C code::" msgstr "" #: ../Doc/library/ctypes.rst:1843 msgid "" "The returned object can only be used as a foreign function call parameter. " "It behaves similar to ``pointer(obj)``, but the construction is a lot faster." msgstr "" #: ../Doc/library/ctypes.rst:1849 msgid "" "This function is similar to the cast operator in C. It returns a new " "instance of *type* which points to the same memory block as *obj*. *type* " "must be a pointer type, and *obj* must be an object that can be interpreted " "as a pointer." msgstr "" #: ../Doc/library/ctypes.rst:1857 msgid "" "This function creates a mutable character buffer. The returned object is a " "ctypes array of :class:`c_char`." msgstr "" #: ../Doc/library/ctypes.rst:1860 msgid "" "*init_or_size* must be an integer which specifies the size of the array, or " "a bytes object which will be used to initialize the array items." msgstr "" #: ../Doc/library/ctypes.rst:1863 msgid "" "If a bytes object is specified as first argument, the buffer is made one " "item larger than its length so that the last element in the array is a NUL " "termination character. An integer can be passed as second argument which " "allows specifying the size of the array if the length of the bytes should " "not be used." msgstr "" #: ../Doc/library/ctypes.rst:1868 msgid "" "Raises an :ref:`auditing event ` ``ctypes.create_string_buffer`` " "with arguments ``init``, ``size``." msgstr "" #: ../Doc/library/ctypes.rst:1873 msgid "" "This function creates a mutable unicode character buffer. The returned " "object is a ctypes array of :class:`c_wchar`." msgstr "" #: ../Doc/library/ctypes.rst:1876 msgid "" "*init_or_size* must be an integer which specifies the size of the array, or " "a string which will be used to initialize the array items." msgstr "" #: ../Doc/library/ctypes.rst:1879 msgid "" "If a string is specified as first argument, the buffer is made one item " "larger than the length of the string so that the last element in the array " "is a NUL termination character. An integer can be passed as second argument " "which allows specifying the size of the array if the length of the string " "should not be used." msgstr "" #: ../Doc/library/ctypes.rst:1885 msgid "" "Raises an :ref:`auditing event ` ``ctypes.create_unicode_buffer`` " "with arguments ``init``, ``size``." msgstr "" #: ../Doc/library/ctypes.rst:1890 msgid "" "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." msgstr "" #: ../Doc/library/ctypes.rst:1897 msgid "" "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." msgstr "" #: ../Doc/library/ctypes.rst:1905 msgid "" "Try to find a library and return a pathname. *name* is the library name " "without any prefix like ``lib``, suffix like ``.so``, ``.dylib`` or version " "number (this is the form used for the posix linker option :option:`!-l`). " "If no library can be found, returns ``None``." msgstr "" #: ../Doc/library/ctypes.rst:1916 msgid "" "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." msgstr "" #: ../Doc/library/ctypes.rst:1920 msgid "" "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." msgstr "" #: ../Doc/library/ctypes.rst:1927 msgid "" "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." msgstr "" #: ../Doc/library/ctypes.rst:1934 msgid "" "Windows only: 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." msgstr "" #: ../Doc/library/ctypes.rst:1940 msgid "" "Returns the current value of the ctypes-private copy of the system :data:" "`errno` variable in the calling thread." msgstr "" #: ../Doc/library/ctypes.rst:1943 msgid "" "Raises an :ref:`auditing event ` ``ctypes.get_errno`` with no " "arguments." msgstr "" #: ../Doc/library/ctypes.rst:1947 msgid "" "Windows only: returns the current value of the ctypes-private copy of the " "system :data:`LastError` variable in the calling thread." msgstr "" #: ../Doc/library/ctypes.rst:1950 msgid "" "Raises an :ref:`auditing event ` ``ctypes.get_last_error`` with no " "arguments." msgstr "" #: ../Doc/library/ctypes.rst:1954 msgid "" "Same as the standard C memmove library function: copies *count* bytes from " "*src* to *dst*. *dst* and *src* must be integers or ctypes instances that " "can be converted to pointers." msgstr "" #: ../Doc/library/ctypes.rst:1961 msgid "" "Same as the standard C memset library function: fills the memory block at " "address *dst* with *count* bytes of value *c*. *dst* must be an integer " "specifying an address, or a ctypes instance." msgstr "" #: ../Doc/library/ctypes.rst:1968 msgid "" "This factory function creates and returns a new ctypes pointer type. Pointer " "types are cached and reused internally, so calling this function repeatedly " "is cheap. *type* must be a ctypes type." msgstr "" #: ../Doc/library/ctypes.rst:1975 msgid "" "This function creates a new pointer instance, pointing to *obj*. The " "returned object is of the type ``POINTER(type(obj))``." msgstr "" #: ../Doc/library/ctypes.rst:1978 msgid "" "Note: If you just want to pass a pointer to an object to a foreign function " "call, you should use ``byref(obj)`` which is much faster." msgstr "" #: ../Doc/library/ctypes.rst:1984 msgid "" "This function resizes the internal memory buffer of *obj*, which must be an " "instance of a ctypes type. It is not possible to make the buffer smaller " "than the native size of the objects type, as given by ``sizeof(type(obj))``, " "but it is possible to enlarge the buffer." msgstr "" #: ../Doc/library/ctypes.rst:1992 msgid "" "Set the current value of the ctypes-private copy of the system :data:`errno` " "variable in the calling thread to *value* and return the previous value." msgstr "" #: ../Doc/library/ctypes.rst:1995 msgid "" "Raises an :ref:`auditing event ` ``ctypes.set_errno`` with " "argument ``errno``." msgstr "" #: ../Doc/library/ctypes.rst:2000 msgid "" "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 previous value." msgstr "" #: ../Doc/library/ctypes.rst:2004 msgid "" "Raises an :ref:`auditing event ` ``ctypes.set_last_error`` with " "argument ``error``." msgstr "" #: ../Doc/library/ctypes.rst:2009 msgid "" "Returns the size in bytes of a ctypes type or instance memory buffer. Does " "the same as the C ``sizeof`` operator." msgstr "" #: ../Doc/library/ctypes.rst:2015 msgid "" "This function returns the C string starting at memory address *address* as a " "bytes object. If size is specified, it is used as size, otherwise the string " "is assumed to be zero-terminated." msgstr "" #: ../Doc/library/ctypes.rst:2019 msgid "" "Raises an :ref:`auditing event ` ``ctypes.string_at`` with " "arguments ``address``, ``size``." msgstr "" #: ../Doc/library/ctypes.rst:2024 msgid "" "Windows only: this function is probably the worst-named thing in ctypes. It " "creates an instance of 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." msgstr "" #: ../Doc/library/ctypes.rst:2030 msgid "An instance of :exc:`WindowsError` used to be created." msgstr "" #: ../Doc/library/ctypes.rst:2036 msgid "" "This function returns the wide character string starting at memory address " "*address* as a string. If *size* is specified, it is used as the number of " "characters of the string, otherwise the string is assumed to be zero-" "terminated." msgstr "" #: ../Doc/library/ctypes.rst:2041 msgid "" "Raises an :ref:`auditing event ` ``ctypes.wstring_at`` with " "arguments ``address``, ``size``." msgstr "" #: ../Doc/library/ctypes.rst:2047 msgid "Data types" msgstr "Types de données" #: ../Doc/library/ctypes.rst:2052 msgid "" "This non-public class is the common base class of all ctypes data types. " "Among other things, all ctypes type instances contain a memory block that " "hold C compatible data; the address of the memory block is returned by the :" "func:`addressof` helper function. Another instance variable is exposed as :" "attr:`_objects`; this contains other Python objects that need to be kept " "alive in case the memory block contains pointers." msgstr "" #: ../Doc/library/ctypes.rst:2059 msgid "" "Common methods of ctypes data types, these are all class methods (to be " "exact, they are methods of the :term:`metaclass`):" msgstr "" #: ../Doc/library/ctypes.rst:2064 msgid "" "This method returns a ctypes instance that shares the buffer of the *source* " "object. The *source* object must support the writeable buffer interface. " "The optional *offset* parameter specifies an offset into the source buffer " "in bytes; the default is zero. If the source buffer is not large enough a :" "exc:`ValueError` is raised." msgstr "" #: ../Doc/library/ctypes.rst:2070 ../Doc/library/ctypes.rst:2080 msgid "" "Raises an :ref:`auditing event ` ``ctypes.cdata/buffer`` with " "arguments ``pointer``, ``size``, ``offset``." msgstr "" #: ../Doc/library/ctypes.rst:2074 msgid "" "This method creates a ctypes instance, copying the buffer from the *source* " "object buffer which must be readable. The optional *offset* parameter " "specifies an offset into the source buffer in bytes; the default is zero. " "If the source buffer is not large enough a :exc:`ValueError` is raised." msgstr "" #: ../Doc/library/ctypes.rst:2084 msgid "" "This method returns a ctypes type instance using the memory specified by " "*address* which must be an integer." msgstr "" #: ../Doc/library/ctypes.rst:None msgid "" "Raises an :ref:`auditing event ` ``ctypes.cdata`` with argument " "``address``." msgstr "" #: ../Doc/library/ctypes.rst:2089 msgid "" "This method, and others that indirectly call this method, raises an :ref:" "`auditing event ` ``ctypes.cdata`` with argument ``address``." msgstr "" #: ../Doc/library/ctypes.rst:2095 msgid "" "This method adapts *obj* to a ctypes type. It is called with the actual " "object used in a foreign function call when the type is present in the " "foreign function's :attr:`argtypes` tuple; it must return an object that can " "be used as a function call parameter." msgstr "" #: ../Doc/library/ctypes.rst:2100 msgid "" "All ctypes data types have a default implementation of this classmethod that " "normally returns *obj* if that is an instance of the type. Some types " "accept other objects as well." msgstr "" #: ../Doc/library/ctypes.rst:2106 msgid "" "This method returns a ctypes type instance exported by a shared library. " "*name* is the name of the symbol that exports the data, *library* is the " "loaded shared library." msgstr "" #: ../Doc/library/ctypes.rst:2110 msgid "Common instance variables of ctypes data types:" msgstr "" #: ../Doc/library/ctypes.rst:2114 msgid "" "Sometimes ctypes data instances do not own the memory block they contain, " "instead they share part of the memory block of a base object. The :attr:" "`_b_base_` read-only member is the root ctypes object that owns the memory " "block." msgstr "" #: ../Doc/library/ctypes.rst:2121 msgid "" "This read-only variable is true when the ctypes data instance has allocated " "the memory block itself, false otherwise." msgstr "" #: ../Doc/library/ctypes.rst:2126 msgid "" "This member is either ``None`` or a dictionary containing Python objects " "that need to be kept alive so that the memory block contents is kept valid. " "This object is only exposed for debugging; never modify the contents of this " "dictionary." msgstr "" #: ../Doc/library/ctypes.rst:2139 msgid "" "This non-public class is the base class of all fundamental ctypes data " "types. It is mentioned here because it contains the common attributes of the " "fundamental ctypes data types. :class:`_SimpleCData` is a subclass of :" "class:`_CData`, so it inherits their methods and attributes. ctypes data " "types that are not and do not contain pointers can now be pickled." msgstr "" #: ../Doc/library/ctypes.rst:2145 msgid "Instances have a single attribute:" msgstr "" #: ../Doc/library/ctypes.rst:2149 msgid "" "This attribute contains the actual value of the instance. For integer and " "pointer types, it is an integer, for character types, it is a single " "character bytes object or string, for character pointer types it is a Python " "bytes object or string." msgstr "" #: ../Doc/library/ctypes.rst:2154 msgid "" "When the ``value`` attribute is retrieved from a ctypes instance, usually a " "new object is returned each time. :mod:`ctypes` does *not* implement " "original object return, always a new object is constructed. The same is " "true for all other ctypes object instances." msgstr "" #: ../Doc/library/ctypes.rst:2160 msgid "" "Fundamental data types, when returned as foreign function call results, or, " "for 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 :attr:`restype` of :class:`c_char_p`, you will always " "receive a Python bytes object, *not* a :class:`c_char_p` instance." msgstr "" #: ../Doc/library/ctypes.rst:2168 msgid "" "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 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." msgstr "" #: ../Doc/library/ctypes.rst:2173 msgid "These are the fundamental ctypes data types:" msgstr "" #: ../Doc/library/ctypes.rst:2177 msgid "" "Represents the C :c:type:`signed char` datatype, and interprets the value as " "small integer. The constructor accepts an optional integer initializer; no " "overflow checking is done." msgstr "" #: ../Doc/library/ctypes.rst:2184 msgid "" "Represents the C :c:type:`char` datatype, and interprets the value as a " "single character. The constructor accepts an optional string initializer, " "the length of the string must be exactly one character." msgstr "" #: ../Doc/library/ctypes.rst:2191 msgid "" "Represents the C :c:type:`char *` datatype when it points to a zero-" "terminated string. For a general character pointer that may also point to " "binary data, ``POINTER(c_char)`` must be used. The constructor accepts an " "integer address, or a bytes object." msgstr "" #: ../Doc/library/ctypes.rst:2199 msgid "" "Represents the C :c:type:`double` datatype. The constructor accepts an " "optional float initializer." msgstr "" #: ../Doc/library/ctypes.rst:2205 msgid "" "Represents the C :c:type:`long double` datatype. The constructor accepts an " "optional float initializer. On platforms where ``sizeof(long double) == " "sizeof(double)`` it is an alias to :class:`c_double`." msgstr "" #: ../Doc/library/ctypes.rst:2211 msgid "" "Represents the C :c:type:`float` datatype. The constructor accepts an " "optional float initializer." msgstr "" #: ../Doc/library/ctypes.rst:2217 msgid "" "Represents the C :c:type:`signed int` datatype. The constructor accepts an " "optional integer initializer; no overflow checking is done. On platforms " "where ``sizeof(int) == sizeof(long)`` it is an alias to :class:`c_long`." msgstr "" #: ../Doc/library/ctypes.rst:2224 msgid "" "Represents the C 8-bit :c:type:`signed int` datatype. Usually an alias for :" "class:`c_byte`." msgstr "" #: ../Doc/library/ctypes.rst:2230 msgid "" "Represents the C 16-bit :c:type:`signed int` datatype. Usually an alias " "for :class:`c_short`." msgstr "" #: ../Doc/library/ctypes.rst:2236 msgid "" "Represents the C 32-bit :c:type:`signed int` datatype. Usually an alias " "for :class:`c_int`." msgstr "" #: ../Doc/library/ctypes.rst:2242 msgid "" "Represents the C 64-bit :c:type:`signed int` datatype. Usually an alias " "for :class:`c_longlong`." msgstr "" #: ../Doc/library/ctypes.rst:2248 msgid "" "Represents the C :c:type:`signed long` datatype. The constructor accepts an " "optional integer initializer; no overflow checking is done." msgstr "" #: ../Doc/library/ctypes.rst:2254 msgid "" "Represents the C :c:type:`signed long long` datatype. The constructor " "accepts an optional integer initializer; no overflow checking is done." msgstr "" #: ../Doc/library/ctypes.rst:2260 msgid "" "Represents the C :c:type:`signed short` datatype. The constructor accepts " "an optional integer initializer; no overflow checking is done." msgstr "" #: ../Doc/library/ctypes.rst:2266 msgid "Represents the C :c:type:`size_t` datatype." msgstr "" #: ../Doc/library/ctypes.rst:2271 msgid "Represents the C :c:type:`ssize_t` datatype." msgstr "" #: ../Doc/library/ctypes.rst:2278 msgid "" "Represents the C :c:type:`unsigned char` datatype, it interprets the value " "as small integer. The constructor accepts an optional integer initializer; " "no overflow checking is done." msgstr "" #: ../Doc/library/ctypes.rst:2285 msgid "" "Represents the C :c:type:`unsigned int` datatype. The constructor accepts " "an optional integer initializer; no overflow checking is done. On platforms " "where ``sizeof(int) == sizeof(long)`` it is an alias for :class:`c_ulong`." msgstr "" #: ../Doc/library/ctypes.rst:2292 msgid "" "Represents the C 8-bit :c:type:`unsigned int` datatype. Usually an alias " "for :class:`c_ubyte`." msgstr "" #: ../Doc/library/ctypes.rst:2298 msgid "" "Represents the C 16-bit :c:type:`unsigned int` datatype. Usually an alias " "for :class:`c_ushort`." msgstr "" #: ../Doc/library/ctypes.rst:2304 msgid "" "Represents the C 32-bit :c:type:`unsigned int` datatype. Usually an alias " "for :class:`c_uint`." msgstr "" #: ../Doc/library/ctypes.rst:2310 msgid "" "Represents the C 64-bit :c:type:`unsigned int` datatype. Usually an alias " "for :class:`c_ulonglong`." msgstr "" #: ../Doc/library/ctypes.rst:2316 msgid "" "Represents the C :c:type:`unsigned long` datatype. The constructor accepts " "an optional integer initializer; no overflow checking is done." msgstr "" #: ../Doc/library/ctypes.rst:2322 msgid "" "Represents the C :c:type:`unsigned long long` datatype. The constructor " "accepts an optional integer initializer; no overflow checking is done." msgstr "" #: ../Doc/library/ctypes.rst:2328 msgid "" "Represents the C :c:type:`unsigned short` datatype. The constructor accepts " "an optional integer initializer; no overflow checking is done." msgstr "" #: ../Doc/library/ctypes.rst:2334 msgid "" "Represents the C :c:type:`void *` type. The value is represented as " "integer. The constructor accepts an optional integer initializer." msgstr "" #: ../Doc/library/ctypes.rst:2340 msgid "" "Represents the C :c:type:`wchar_t` datatype, and interprets the value as a " "single character unicode string. The constructor accepts an optional string " "initializer, the length of the string must be exactly one character." msgstr "" #: ../Doc/library/ctypes.rst:2347 msgid "" "Represents the C :c:type:`wchar_t *` datatype, which must be a pointer to a " "zero-terminated wide character string. The constructor accepts an integer " "address, or a string." msgstr "" #: ../Doc/library/ctypes.rst:2354 msgid "" "Represent the C :c:type:`bool` datatype (more accurately, :c:type:`_Bool` " "from C99). Its value can be ``True`` or ``False``, and the constructor " "accepts any object that has a truth value." msgstr "" #: ../Doc/library/ctypes.rst:2361 msgid "" "Windows only: Represents a :c:type:`HRESULT` value, which contains success " "or error information for a function or method call." msgstr "" #: ../Doc/library/ctypes.rst:2367 msgid "" "Represents the C :c:type:`PyObject *` datatype. Calling this without an " "argument creates a ``NULL`` :c:type:`PyObject *` pointer." msgstr "" #: ../Doc/library/ctypes.rst:2370 msgid "" "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 useful structures like :c:type:`MSG` or :c:type:`RECT` are " "also defined." msgstr "" #: ../Doc/library/ctypes.rst:2378 msgid "Structured data types" msgstr "" #: ../Doc/library/ctypes.rst:2383 msgid "Abstract base class for unions in native byte order." msgstr "" #: ../Doc/library/ctypes.rst:2388 msgid "Abstract base class for structures in *big endian* byte order." msgstr "" #: ../Doc/library/ctypes.rst:2393 msgid "Abstract base class for structures in *little endian* byte order." msgstr "" #: ../Doc/library/ctypes.rst:2395 msgid "" "Structures with non-native byte order cannot contain pointer type fields, or " "any other data types containing pointer type fields." msgstr "" #: ../Doc/library/ctypes.rst:2401 msgid "Abstract base class for structures in *native* byte order." msgstr "" #: ../Doc/library/ctypes.rst:2403 msgid "" "Concrete structure and union types must be created by subclassing one of " "these types, and at least define a :attr:`_fields_` class variable. :mod:" "`ctypes` will create :term:`descriptor`\\s which allow reading and writing " "the fields by direct attribute accesses. These are the" msgstr "" #: ../Doc/library/ctypes.rst:2411 msgid "" "A sequence defining the structure fields. The items must be 2-tuples or 3-" "tuples. The first item is the name of the field, the second item specifies " "the type of the field; it can be any ctypes data type." msgstr "" #: ../Doc/library/ctypes.rst:2415 msgid "" "For integer type fields like :class:`c_int`, a third optional item can be " "given. It must be a small positive integer defining the bit width of the " "field." msgstr "" #: ../Doc/library/ctypes.rst:2419 msgid "" "Field names must be unique within one structure or union. This is not " "checked, only one field can be accessed when names are repeated." msgstr "" #: ../Doc/library/ctypes.rst:2422 msgid "" "It is possible to define the :attr:`_fields_` class variable *after* the " "class statement that defines the Structure subclass, this allows creating " "data types that directly or indirectly reference themselves::" msgstr "" #: ../Doc/library/ctypes.rst:2432 msgid "" "The :attr:`_fields_` class variable must, however, be defined before the " "type is first used (an instance is created, :func:`sizeof` is called on it, " "and so on). Later assignments to the :attr:`_fields_` class variable will " "raise an AttributeError." msgstr "" #: ../Doc/library/ctypes.rst:2437 msgid "" "It is possible to define sub-subclasses of structure types, they inherit the " "fields of the base class plus the :attr:`_fields_` defined in the sub-" "subclass, if any." msgstr "" #: ../Doc/library/ctypes.rst:2444 msgid "" "An optional small integer that allows overriding the alignment of structure " "fields in the instance. :attr:`_pack_` must already be defined when :attr:" "`_fields_` is assigned, otherwise it will have no effect." msgstr "" #: ../Doc/library/ctypes.rst:2451 msgid "" "An optional sequence that lists the names of unnamed (anonymous) fields. :" "attr:`_anonymous_` must be already defined when :attr:`_fields_` is " "assigned, otherwise it will have no effect." msgstr "" #: ../Doc/library/ctypes.rst:2455 msgid "" "The fields listed in this variable must be structure or union type fields. :" "mod:`ctypes` will create descriptors in the structure type that allows " "accessing the nested fields directly, without the need to create the " "structure or union field." msgstr "" #: ../Doc/library/ctypes.rst:2460 msgid "Here is an example type (Windows)::" msgstr "" #: ../Doc/library/ctypes.rst:2473 msgid "" "The ``TYPEDESC`` structure describes a COM data type, the ``vt`` field " "specifies which one of the union fields is valid. Since the ``u`` field is " "defined as anonymous field, it is now possible to access the members " "directly off the TYPEDESC instance. ``td.lptdesc`` and ``td.u.lptdesc`` are " "equivalent, but the former is faster since it does not need to create a " "temporary union instance::" msgstr "" #: ../Doc/library/ctypes.rst:2485 msgid "" "It is possible to define sub-subclasses of structures, they inherit the " "fields of the base class. If the subclass definition has a separate :attr:" "`_fields_` variable, the fields specified in this are appended to the fields " "of the base class." msgstr "" #: ../Doc/library/ctypes.rst:2490 msgid "" "Structure and union constructors accept both positional and keyword " "arguments. Positional arguments are used to initialize member fields in the " "same order as they are appear in :attr:`_fields_`. Keyword arguments in the " "constructor are interpreted as attribute assignments, so they will " "initialize :attr:`_fields_` with the same name, or create new attributes for " "names not present in :attr:`_fields_`." msgstr "" #: ../Doc/library/ctypes.rst:2501 msgid "Arrays and pointers" msgstr "" #: ../Doc/library/ctypes.rst:2505 msgid "Abstract base class for arrays." msgstr "Classe de base abstraite pour les *arrays*." #: ../Doc/library/ctypes.rst:2507 msgid "" "The recommended way to create concrete array types is by multiplying any :" "mod:`ctypes` data type with a positive integer. Alternatively, you can " "subclass this type and define :attr:`_length_` and :attr:`_type_` class " "variables. Array elements can be read and written using standard subscript " "and slice accesses; for slice reads, the resulting object is *not* itself " "an :class:`Array`." msgstr "" #: ../Doc/library/ctypes.rst:2517 msgid "" "A positive integer specifying the number of elements in the array. Out-of-" "range subscripts result in an :exc:`IndexError`. Will be returned by :func:" "`len`." msgstr "" #: ../Doc/library/ctypes.rst:2524 msgid "Specifies the type of each element in the array." msgstr "Spécifie le type de chaque élément de l'*array*." #: ../Doc/library/ctypes.rst:2527 msgid "" "Array subclass constructors accept positional arguments, used to initialize " "the elements in order." msgstr "" #: ../Doc/library/ctypes.rst:2533 msgid "Private, abstract base class for pointers." msgstr "" #: ../Doc/library/ctypes.rst:2535 msgid "" "Concrete pointer types are created by calling :func:`POINTER` with the type " "that will be pointed to; this is done automatically by :func:`pointer`." msgstr "" #: ../Doc/library/ctypes.rst:2539 msgid "" "If a pointer points to an array, its elements can be read and written using " "standard subscript and slice accesses. Pointer objects have no size, so :" "func:`len` will raise :exc:`TypeError`. Negative subscripts will read from " "the memory *before* the pointer (as in C), and out-of-range subscripts will " "probably crash with an access violation (if you're lucky)." msgstr "" #: ../Doc/library/ctypes.rst:2549 msgid "Specifies the type pointed to." msgstr "" #: ../Doc/library/ctypes.rst:2553 msgid "" "Returns the object to which to pointer points. Assigning to this attribute " "changes the pointer to point to the assigned object." msgstr ""