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 --threads:on --app:lib --tlsEmulation:off --out:mymodule.pyd mymodule
# Compile on everything else:
nim c --threads:on --app:lib --out:mymodule.so 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.
Question:
Importing the compiled module from Python fails with ImportError: dynamic module does not define module export function ...
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.
Question:
Nim strings are converted to Python bytes
instead of string
bytes
instead of string
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.
Question:
Is there any numpy compatibility?
nimpy allows manipulating numpy objects just how you would do it in Python,
however it is not much more efficient. To get the maximum performance nimpy
exposes Buffer protocol, see
raw_buffers.nim.
tpyfromnim.nim
contains a very basic test for this (grep numpy
).
This issue demonstrates possible
higher level concepts that could be built on top. Higher level API might
be considered in the future, PRs are welcome.
Question:
Does nim default garbage collector (GC) work?
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:
- If it's known there will be only one nimpy module in the process, you should be fine.
- If there is more than one nimpy module, it is recommended to move nim runtime out to a separate shared library. However it might not be needed if nim references are known to never travel between nim shared libraries.
- If you hit any GC problems with nimpy, whether you followed these guidelines or not, please report them to nimpy tracker :)
Warning! This is experimental.
- An exported type should be a ref object and inherit
PyNimObjectExperimental
directly or indirectly. - The type will only be exported if at least one exported "method" is defined.
- A proc will be exported as python type method only if it's first argument is of the corresponding type and is called
self
. If the first argument is not calledself
, 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")
- High level buffer API