14.14.2.3 Foreign functions

###
14.14.2.3 Foreign functions

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:

class `_FuncPtr`
  Base class for C callable foreign functions.

Instances of foreign functions are also C compatible data types; they represent C function pointers.

This behaviour can be customized by assigning to special attributes of the foreign function object.

`restype`
  Assign a ctypes type to specify the result type of the foreign function. Use `None` for `void` a function not returning anything.

  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 `int`, and the callable will be called with this integer, allowing to do further processing or error checking. Using this is deprecated, for more flexible postprocessing or error checking use a ctypes data type as `restype` and assign a callable to the `errcheck` attribute.

`argtypes`
  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.

  When a foreign function is called, each actual argument is passed to the `from_param` class method of the items in the `argtypes` tuple, this method allows to adapt the actual argument to an object that the foreign function accepts. For example, a `c_char_p` item in the `argtypes` tuple will convert a unicode string passed as argument into an byte string using ctypes conversion rules.

  New: It is now possible to put items in argtypes which are not ctypes types, but each item must have a `from_param` method which returns a value usable as argument (integer, string, ctypes instance). This allows to define adapters that can adapt custom objects as function parameters.

`errcheck`
  Assign a Python function or another callable to this attribute. The callable will be called with three or more arguments:

`callable`( | result, func, arguments)

  `result` is what the foreign function returns, as specified by the `restype` attribute.

  `func` is the foreign function object itself, this allows to reuse the same callable object to check or postprocess the results of several functions.

  `arguments` is a tuple containing the parameters originally passed to the function call, this allows to specialize the behaviour on the arguments used.

  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.

exception `ArgumentError()`
  This exception is raised when a foreign function call cannot convert one of the passed arguments.