14.14.2.2 Loading shared libraries

###
14.14.2.2 Loading shared libraries

There are several ways to loaded shared libraries into the Python process. One way is to instantiate one of the following classes:

class `CDLL`( | name, mode=DEFAULT_MODE, handle=None)

  Instances of this class represent loaded shared libraries. Functions in these libraries use the standard C calling convention, and are assumed to return `int`.

class `OleDLL`( | name, mode=DEFAULT_MODE, handle=None)

  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 `HRESULT` code. `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 `WindowsError` is automatically raised.

class `WinDLL`( | name, mode=DEFAULT_MODE, handle=None)

  Windows only: Instances of this class represent loaded shared libraries, functions in these libraries use the `stdcall` calling convention, and are assumed to return `int` by default.

  On Windows CE only the standard calling convention is used, for convenience the `WinDLL` and `OleDLL` use the standard calling convention on this platform.

The Python GIL is released before calling any function exported by these libraries, and reaquired afterwards.

class `PyDLL`( | name, mode=DEFAULT_MODE, handle=None)

  Instances of this class behave like `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.

  Thus, this is only useful to call Python C api functions directly.

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 shard 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.

The mode parameter can be used to specify how the library is loaded. For details, consult the `dlopen(3)` manpage, on Windows, mode is ignored.

`RTLD_GLOBAL`
  Flag to use as mode parameter. On platforms where this flag is not available, it is defined as the integer zero.

`RTLD_LOCAL`
  Flag to use as mode parameter. On platforms where this is not available, it is the same as RTLD_GLOBAL.

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

Instances of these classes have no public methods, however `__getattr__` and `__getitem__` have special behaviour: functions exported by the shared library can be accessed as attributes of by index. Please note that both `__getattr__` and `__getitem__` cache their result, so calling them repeatedly returns the same object each time.

The following public attributes are available, their name starts with an underscore to not clash with exported function names:

`_handle`
  The system handle used to access the library.

`_name`
  The name of the library passed in the contructor.

Shared libraries can also be loaded by using one of the prefabricated objects, which are instances of the `LibraryLoader` class, either by calling the `LoadLibrary` method, or by retrieving the library as attribute of the loader instance.

class `LibraryLoader`( | dlltype)

  Class which loads shared libraries. `dlltype` should be one of the `CDLL`, `PyDLL`, `WinDLL`, or `OleDLL` types.

  `__getattr__` has special behaviour: It allows to load 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.

`LoadLibrary`( | name)

  Load a shared library into the process and return it. This method always returns a new instance of the library.

These prefabricated library loaders are available:

`cdll`
  Creates `CDLL` instances.

`windll`
  Windows only: Creates `WinDLL` instances.

`oledll`
  Windows only: Creates `OleDLL` instances.

`pydll`
  Creates `PyDLL` instances.

For accessing the C Python api directly, a ready-to-use Python shared library object is available:

`pythonapi`
  An instance of `PyDLL` that exposes Python C api functions as attributes. Note that all these functions are assumed to return C `int`, which is of course not always the truth, so you have to assign the correct `restype` attribute to use these functions.