Nim - Python bridge
Native language integration with Python has never been easier!
# mymodule.nim - file name should match the module name you're going to import from python
import nimpy
proc greet(name: string): string {.exportpy.} =
return "Hello, " & name & "!"
# Compile on Windows:
nim c --app:lib --out:mymodule.pyd --threads:on --tlsEmulation:off --passL:-static mymodule
# Compile on everything else:
nim c --app:lib --out:mymodule.so --threads:on mymodule
# test.py
import mymodule
assert mymodule.greet("world") == "Hello, world!"
assert mymodule.greet(name="world") == "Hello, world!"
import nimpy
let os = pyImport("os")
echo "Current dir is: ", os.getcwd().to(string)
# sum(range(1, 5))
let py = pyBuiltinsModule()
let s = py.sum(py.range(0, 5)).to(int)
assert s == 10
Note: here nimpy relies on your local python installation.
For a convenient way to import your Nim extension modules directly, you can use Nimporter.
The library is designed with ABI compatibility in mind. That is the compiled module doesn't depend on particular Python version, it should properly work with any. The C API symbols are loaded in runtime from whichever process has launched your module.
If you're getting ImportError: dynamic module does not define module export function ...
make sure that the module you're importing from Python has exactly the same name as the nim
file which the module is implemented in.
The most reliable way to find libpython is find_libpython
python package:
pip3 install find_libpython
python3 -c 'import find_libpython; print(find_libpython.find_libpython())'
Then you can specify path to libpython using nimpy.py_lib.pyInitLibPath
. Tracking issue: #171.
nimpy converts Nim strings to Python strings usually, but since Nim strings are encoding agnostic and may contain invalid utf8 sequences, nimpy will fallback to Python bytes
in such cases.
nimpy allows manipulating numpy objects just how you would do it in Python, however it is not much more efficient. scinim offers API for performance critical numpy interop, and it is advised to consider it first.
Nimpy also exposes lower level Buffer protocol, see raw_buffers.nim. tpyfromnim.nim contains a very basic test for this.
Yes. nimpy internally does everything needed to run the GC properly (keeps the stack bottom actual, and appropriate nim references alive), and doesn't introduce any special rules on top. So the GC question boils down to proper GC usage in nim shared libraries, you'd better lookup elsewhere. The following guidelines are by no means comprehensive, but should be enough for the quick start:
When compiling with --threads:on
Nim will imply --tlsEmulation:on
(Windows only) which
prevents Nim runtime from initing properly when being called from a foreign thread (which is
always the case in case of Python module).
Adding --tlsEmulation:off
when using MinGW toolchain (Nim's default on Windows) will
introduce a dependency on libgcc_s_seh-*.dll
, that newer python versions are often unable
to find.
One way to overcome this is to link with libgcc statically, by passing -static
to linker,
or --passL:-static
to Nim.
Warning! This is experimental.
PyNimObjectExperimental
directly or indirectly.self
. If the first argument is not called self
, the proc will exported as a global module function.# mymodule.nim
type TestType = ref object of PyNimObjectExperimental
myField: string
proc setMyField(self: TestType, value: string) {.exportpy.} =
self.myField = value
proc getMyField(self: TestType): string {.exportpy.} =
self.myField
# test.py
import mymodule
tt = mymodule.TestType()
tt.setMyField("Hello")
assert(tt.getMyField() == "Hello")