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.

See About this document... for information on suggesting changes.