Nimpy

https://github.com/yglukhov/nimpy
Admin
Nimpy provides native language integration with Python, allowing easy implementation of Python...
Tokens:2,109
Snippets:14
Trust Score:8.9
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Get NumPy Array Buffer in Nim

Source: https://github.com/yglukhov/nimpy/blob/master/docs/numpy.md

This Nim procedure accesses the underlying data buffer of a Python object (expected to be a NumPy array) using the Python buffer protocol. It requires the array to be C-contiguous for successful buffer export. The `mode` parameter specifies the desired buffer access flags (e.g., read-only).

```Nim
proc asNimArray*[T](arr : PyObject, mode : int = PyBUF_READ) : ptr UncheckedArray[T] =
    var
        buf : RawPyBuffer
    getBuffer(arr, buf, mode.cint)
```

--------------------------------

### Testing Nim Module from Python

Source: https://github.com/yglukhov/nimpy/blob/master/README.md

Demonstrates how to import the compiled Nim module `mymodule` in Python and call the exported `greet` function, verifying its output using assertions.

```py
# test.py
import mymodule
assert mymodule.greet("world") == "Hello, world!"
assert mymodule.greet(name="world") == "Hello, world!"
```

--------------------------------

### Implementing Python Module in Nim

Source: https://github.com/yglukhov/nimpy/blob/master/README.md

Defines a simple Nim module `mymodule` with a function `greet` that can be exported and called from Python using the `exportpy` pragma.

```nim
# 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 & "!"
```

--------------------------------

### Compiling Nim Module for Python

Source: https://github.com/yglukhov/nimpy/blob/master/README.md

Provides command-line instructions to compile the Nim source file `mymodule.nim` into a Python-compatible shared library (`.pyd` on Windows, `.so` elsewhere) using the Nim compiler.

```bash
# 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
```

--------------------------------

### Calling Python Functions from Nim

Source: https://github.com/yglukhov/nimpy/blob/master/README.md

Shows how to import Python modules (`os`, builtins) and call their functions (`getcwd`, `sum`, `range`) directly from Nim using the `nimpy` library, converting results to Nim types.

```nim
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
```

--------------------------------

### Exporting Nim Type with __init__ and __repr__ - Nim

Source: https://github.com/yglukhov/nimpy/blob/master/docs/export_python_type.md

Defines a Nim `SimpleObj` type and exports procedures `initSimpleObj` and `$` as Python's `__init__` and `__repr__` methods respectively, following specific naming and signature conventions. It also demonstrates setting module and type docstrings for Python.

```Nim
# simple.nim
## compile as simple.so

import nimpy
import strformat

pyExportModule("simple") # only needed if your filename is not simple.nim

type
  SimpleObj* = ref object of PyNimObjectExperimental
    a* : int

## if 
##  1) the function name is like `init##TypeName`
##  2) there is at least one argument
##  3) the first argument name is "self"
##  4) the first argument type is `##TypeName`
##  5) there is no return type
## we export this function as a python object method __init__ (tp_init in PyTypeObject)
proc initSimpleObj*(self : SimpleObj, a : int = 1) {.exportpy} =
  echo "Calling initSimpleObj for SimpleObj"
  self.a = a

## if
##  1) the function name is like `$`
##  2) there is only one argument
##  3) the first argument name is "self"
##  4) the first argument type is `##TypeName`
##  5) the return type is `string`
## we export this function as a python object method __repr__ (tp_repr in PyTypeObject) =
proc `$`*(self : SimpleObj): string {.exportpy.} =
   &"SimpleObj : a={self.a}" 


## Change doc string
setModuleDocString("This is a test module")
setDocStringForType(SimpleObj, "This is a test type")
```

--------------------------------

### Using Exported Nim Type with __init__ and __repr__ - Python

Source: https://github.com/yglukhov/nimpy/blob/master/docs/export_python_type.md

Imports the compiled `simple` module, prints the module and type docstrings, creates an instance of `SimpleObj` using the exported `__init__` (passing an argument), and prints the object, which implicitly calls the exported `__repr__` method.

```Python
import simple
print(simple.__doc__)
print(simple.SimpleObj.__doc__)
obj = simple.SimpleObj(a = 2)
print(obj)
```

--------------------------------

### Using Exported Nim Type in Python (Python)

Source: https://github.com/yglukhov/nimpy/blob/master/README.md

Shows how to import a Nim module that exports a type as a Python class, instantiate the class, and call its exported methods from Python.

```Python
# test.py
import mymodule
tt = mymodule.TestType()
tt.setMyField("Hello")
assert(tt.getMyField() == "Hello")
```

--------------------------------

### Compiling Nim Code to Shared Library - Bash

Source: https://github.com/yglukhov/nimpy/blob/master/docs/export_python_type.md

Compiles the `simple.nim` Nim source file into a shared library named `simple.so` using the Nim compiler, specifying the application type as `lib` for creating a library.

```Bash
nim c --app:lib -o:./simple.so ./simple.nim
```

--------------------------------

### Finding libpython using find_libpython (Shell)

Source: https://github.com/yglukhov/nimpy/blob/master/README.md

Provides a command-line method using the `find_libpython` Python package to locate the path of the Python shared library, which can be used to resolve issues where nimpy fails to find it.

```Shell
pip3 install find_libpython
python3 -c 'import find_libpython; print(find_libpython.find_libpython())'
```

--------------------------------

### Defining Exportable Nim Type with Methods (Nim)

Source: https://github.com/yglukhov/nimpy/blob/master/README.md

Demonstrates how to define a Nim `ref object` that inherits from `PyNimObjectExperimental` and includes procs (methods) marked with `{.exportpy.}` to make them available when the Nim type is exported as a Python class.

```Nim
# 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
```

--------------------------------

### Using Exported Nim Type - Python

Source: https://github.com/yglukhov/nimpy/blob/master/docs/export_python_type.md

Imports the `mymodule` compiled from Nim, creates an instance of the exported `TestType`, calls the exported `setMyField` method to set a value, and then calls `getMyField` to retrieve and assert the value.

```Python
# test.py
import mymodule
tt = mymodule.TestType()
tt.setMyField("Hello")
assert(tt.getMyField() == "Hello")
```

--------------------------------

### Exporting Nim Type with Methods - Nim

Source: https://github.com/yglukhov/nimpy/blob/master/docs/export_python_type.md

Defines a Nim `ref object` type `TestType` inheriting from `PyNimObjectExperimental` and exports `setMyField` and `getMyField` procedures as Python methods using the `.exportpy` pragma. These procedures operate on an instance of `TestType` passed as the `self` argument.

```Nim
# 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
```

--------------------------------

### Represent and Access NumPy Array in Nim

Source: https://github.com/yglukhov/nimpy/blob/master/docs/numpy.md

Defines a `NimNumpyArray` object in Nim to hold references and metadata (buffer pointer, shape, strides, contiguity flags) for a Python NumPy array. Includes a procedure `asNimNumpyArray` to populate this object from a `PyObject` and `accessNumpyMatrix` to access elements of a 2D matrix using strides.

```Nim
type
    NimNumpyArray*[T] = object
        originalPtr*   : PyObject
        buf*           : ptr UncheckedArray[T]
        shape*         : seq[int]
        strides*       : seq[int]
        c_contiguous*  : bool
        f_contiguous*  : bool

proc asNimNumpyArray*[T](arr : PyObject, mode : int = PyBUF_READ) : NimNumpyArray[T] =
    #[
        Function to translate numpy array into an object in Nim to represent the data for convinience.
    ]#
    result.originalPtr        = arr
    result.buf                = asNimArray[T](arr, mode)
    result.shape              = getAttr(arr, "shape").to(seq[int])
    result.strides            = getAttr(arr, "strides").to(seq[int])
    result.c_contiguous       = arr.flags["C_CONTIGUOUS"].to(bool)
    result.f_contiguous       = arr.flags["F_CONTIGUOUS"].to(bool)

proc accessNumpyMatrix*[T](matrix : NimNumpyArray[T], row, col : int): T =
    doAssert matrix.shape == 2 and matrix.strides == 2
    return matrix.buf[
        row * matrix.strides[0] + col * matrix.strides[1]
    ]
```
Tokens:
Raw