How can I use a DLL file from Python?
Question:
What is the easiest way to use a DLL file from within Python?
Specifically, how can this be done without writing any additional wrapper C++ code to expose the functionality to Python?
Native Python functionality is strongly preferred over using a third-party library.
Answers:
ctypes can be used to access dlls, here’s a tutorial:
ctypes will be the easiest thing to use but (mis)using it makes Python subject to crashing. If you are trying to do something quickly, and you are careful, it’s great.
I would encourage you to check out Boost Python. Yes, it requires that you write some C++ code and have a C++ compiler, but you don’t actually need to learn C++ to use it, and you can get a free (as in beer) C++ compiler from Microsoft.
For ease of use, ctypes is the way to go.
The following example of ctypes is from actual code I’ve written (in Python 2.5). This has been, by far, the easiest way I’ve found for doing what you ask.
import ctypes
# Load DLL into memory.
hllDll = ctypes.WinDLL ("c:\PComm\ehlapi32.dll")
# Set up prototype and parameters for the desired function call.
# HLLAPI
hllApiProto = ctypes.WINFUNCTYPE (
ctypes.c_int, # Return type.
ctypes.c_void_p, # Parameters 1 ...
ctypes.c_void_p,
ctypes.c_void_p,
ctypes.c_void_p) # ... thru 4.
hllApiParams = (1, "p1", 0), (1, "p2", 0), (1, "p3",0), (1, "p4",0),
# Actually map the call ("HLLAPI(...)") to a Python name.
hllApi = hllApiProto (("HLLAPI", hllDll), hllApiParams)
# This is how you can actually call the DLL function.
# Set up the variables and call the Python name with them.
p1 = ctypes.c_int (1)
p2 = ctypes.c_char_p (sessionVar)
p3 = ctypes.c_int (1)
p4 = ctypes.c_int (0)
hllApi (ctypes.byref (p1), p2, ctypes.byref (p3), ctypes.byref (p4))
The ctypes stuff has all the C-type data types (int, char, short, void*, and so on) and can pass by value or reference. It can also return specific data types although my example doesn’t do that (the HLL API returns values by modifying a variable passed by reference).
In terms of the specific example shown above, IBM’s EHLLAPI is a fairly consistent interface.
All calls pass four void pointers (EHLLAPI sends the return code back through the fourth parameter, a pointer to an int so, while I specify int as the return type, I can safely ignore it) as per IBM’s documentation here. In other words, the C variant of the function would be:
int hllApi (void *p1, void *p2, void *p3, void *p4)
This makes for a single, simple ctypes function able to do anything the EHLLAPI library provides, but it’s likely that other libraries will need a separate ctypes function set up per library function.
The return value from WINFUNCTYPE is a function prototype but you still have to set up more parameter information (over and above the types). Each tuple in hllApiParams has a parameter “direction” (1 = input, 2 = output and so on), a parameter name and a default value – see the ctypes doco for details
Once you have the prototype and parameter information, you can create a Python “callable” hllApi with which to call the function. You simply create the needed variable (p1 through p4 in my case) and call the function with them.
This page has a very simple example of calling functions from a DLL file.
Paraphrasing the details here for completeness:
It’s very easy to call a DLL function in Python. I have a self-made DLL file with two functions: add and sub which take two arguments.
add(a, b) returns addition of two numbers
sub(a, b) returns substraction of two numbers
The name of the DLL file will be "demo.dll"
Program:
from ctypes import*
# give location of dll
mydll = cdll.LoadLibrary("C:\demo.dll")
result1= mydll.add(10,1)
result2= mydll.sub(10,1)
print "Addition value:"+result1
print "Substraction:"+result2
Output:
Addition value:11
Substraction:9
Maybe with Dispatch:
from win32com.client import Dispatch
zk = Dispatch("zkemkeeper.ZKEM")
Where zkemkeeper is a registered DLL file on the system…
After that, you can access functions just by calling them:
zk.Connect_Net(IP_address, port)
Building a DLL and linking it under Python using ctypes
I present a fully worked example on how building a shared library and using it under Python by means of ctypes. I consider the Windows case and deal with DLLs. Two steps are needed:
- Build the DLL using Visual Studio’s compiler either from the command line or from the IDE;
- Link the DLL under Python using ctypes.
The shared library
The shared library I consider is the following and is contained in the testDLL.cpp file. The only function testDLL just receives an int and prints it.
#include <stdio.h>
extern "C" {
__declspec(dllexport)
void testDLL(const int i) {
printf("%dn", i);
}
} // extern "C"
Building the DLL from the command line
To build a DLL with Visual Studio from the command line run
"C:Program Files (x86)Microsoft Visual Studio 12.0Common7Toolsvsdevcmd"
to set the include path and then run
cl.exe /D_USRDLL /D_WINDLL testDLL.cpp /MT /link /DLL /OUT:testDLL.dll
to build the DLL.
Building the DLL from the IDE
Alternatively, the DLL can be build using Visual Studio as follows:
- File -> New -> Project;
- Installed -> Templates -> Visual C++ -> Windows -> Win32 -> Win32Project;
- Next;
- Application type -> DLL;
- Additional options -> Empty project (select);
- Additional options -> Precompiled header (unselect);
- Project -> Properties -> Configuration Manager -> Active solution platform: x64;
- Project -> Properties -> Configuration Manager -> Active solution configuration: Release.
Linking the DLL under Python
Under Python, do the following
import os
import sys
from ctypes import *
lib = cdll.LoadLibrary('testDLL.dll')
lib.testDLL(3)
If the DLL is of type COM library, then you can use pythonnet.
pip install pythonnet
Then in your python code, try the following
import clr
clr.AddReference('path_to_your_dll')
# import the namespace and class
from Namespace import Class
# create an object of the class
obj = Class()
# access functions return type using object
value = obj.Function(<arguments>)
then instantiate an object as per the class in the DLL, and access the methods within it.
What is the easiest way to use a DLL file from within Python?
Specifically, how can this be done without writing any additional wrapper C++ code to expose the functionality to Python?
Native Python functionality is strongly preferred over using a third-party library.
ctypes can be used to access dlls, here’s a tutorial:
ctypes will be the easiest thing to use but (mis)using it makes Python subject to crashing. If you are trying to do something quickly, and you are careful, it’s great.
I would encourage you to check out Boost Python. Yes, it requires that you write some C++ code and have a C++ compiler, but you don’t actually need to learn C++ to use it, and you can get a free (as in beer) C++ compiler from Microsoft.
For ease of use, ctypes is the way to go.
The following example of ctypes is from actual code I’ve written (in Python 2.5). This has been, by far, the easiest way I’ve found for doing what you ask.
import ctypes
# Load DLL into memory.
hllDll = ctypes.WinDLL ("c:\PComm\ehlapi32.dll")
# Set up prototype and parameters for the desired function call.
# HLLAPI
hllApiProto = ctypes.WINFUNCTYPE (
ctypes.c_int, # Return type.
ctypes.c_void_p, # Parameters 1 ...
ctypes.c_void_p,
ctypes.c_void_p,
ctypes.c_void_p) # ... thru 4.
hllApiParams = (1, "p1", 0), (1, "p2", 0), (1, "p3",0), (1, "p4",0),
# Actually map the call ("HLLAPI(...)") to a Python name.
hllApi = hllApiProto (("HLLAPI", hllDll), hllApiParams)
# This is how you can actually call the DLL function.
# Set up the variables and call the Python name with them.
p1 = ctypes.c_int (1)
p2 = ctypes.c_char_p (sessionVar)
p3 = ctypes.c_int (1)
p4 = ctypes.c_int (0)
hllApi (ctypes.byref (p1), p2, ctypes.byref (p3), ctypes.byref (p4))
The ctypes stuff has all the C-type data types (int, char, short, void*, and so on) and can pass by value or reference. It can also return specific data types although my example doesn’t do that (the HLL API returns values by modifying a variable passed by reference).
In terms of the specific example shown above, IBM’s EHLLAPI is a fairly consistent interface.
All calls pass four void pointers (EHLLAPI sends the return code back through the fourth parameter, a pointer to an int so, while I specify int as the return type, I can safely ignore it) as per IBM’s documentation here. In other words, the C variant of the function would be:
int hllApi (void *p1, void *p2, void *p3, void *p4)
This makes for a single, simple ctypes function able to do anything the EHLLAPI library provides, but it’s likely that other libraries will need a separate ctypes function set up per library function.
The return value from WINFUNCTYPE is a function prototype but you still have to set up more parameter information (over and above the types). Each tuple in hllApiParams has a parameter “direction” (1 = input, 2 = output and so on), a parameter name and a default value – see the ctypes doco for details
Once you have the prototype and parameter information, you can create a Python “callable” hllApi with which to call the function. You simply create the needed variable (p1 through p4 in my case) and call the function with them.
This page has a very simple example of calling functions from a DLL file.
Paraphrasing the details here for completeness:
It’s very easy to call a DLL function in Python. I have a self-made DLL file with two functions:
addandsubwhich take two arguments.
add(a, b)returns addition of two numbers
sub(a, b)returns substraction of two numbersThe name of the DLL file will be "demo.dll"
Program:
from ctypes import*
# give location of dll
mydll = cdll.LoadLibrary("C:\demo.dll")
result1= mydll.add(10,1)
result2= mydll.sub(10,1)
print "Addition value:"+result1
print "Substraction:"+result2Output:
Addition value:11
Substraction:9
Maybe with Dispatch:
from win32com.client import Dispatch
zk = Dispatch("zkemkeeper.ZKEM")
Where zkemkeeper is a registered DLL file on the system…
After that, you can access functions just by calling them:
zk.Connect_Net(IP_address, port)
Building a DLL and linking it under Python using ctypes
I present a fully worked example on how building a shared library and using it under Python by means of ctypes. I consider the Windows case and deal with DLLs. Two steps are needed:
- Build the DLL using Visual Studio’s compiler either from the command line or from the IDE;
- Link the DLL under Python using ctypes.
The shared library
The shared library I consider is the following and is contained in the testDLL.cpp file. The only function testDLL just receives an int and prints it.
#include <stdio.h>
extern "C" {
__declspec(dllexport)
void testDLL(const int i) {
printf("%dn", i);
}
} // extern "C"
Building the DLL from the command line
To build a DLL with Visual Studio from the command line run
"C:Program Files (x86)Microsoft Visual Studio 12.0Common7Toolsvsdevcmd"
to set the include path and then run
cl.exe /D_USRDLL /D_WINDLL testDLL.cpp /MT /link /DLL /OUT:testDLL.dll
to build the DLL.
Building the DLL from the IDE
Alternatively, the DLL can be build using Visual Studio as follows:
- File -> New -> Project;
- Installed -> Templates -> Visual C++ -> Windows -> Win32 -> Win32Project;
- Next;
- Application type -> DLL;
- Additional options -> Empty project (select);
- Additional options -> Precompiled header (unselect);
- Project -> Properties -> Configuration Manager -> Active solution platform: x64;
- Project -> Properties -> Configuration Manager -> Active solution configuration: Release.
Linking the DLL under Python
Under Python, do the following
import os
import sys
from ctypes import *
lib = cdll.LoadLibrary('testDLL.dll')
lib.testDLL(3)
If the DLL is of type COM library, then you can use pythonnet.
pip install pythonnet
Then in your python code, try the following
import clr
clr.AddReference('path_to_your_dll')
# import the namespace and class
from Namespace import Class
# create an object of the class
obj = Class()
# access functions return type using object
value = obj.Function(<arguments>)
then instantiate an object as per the class in the DLL, and access the methods within it.