nuwa-sdk

Python interoperability utilities for Nuwa Build

This package provides utilities for building high-performance Python extensions with Nim:

• nuwa_export - Macro for automatic generation of Python type stubs (.pyi files)
• withNogil - Template for releasing the Python GIL during pure Nim code execution
• asNumpyArray / asNumpyArrayWrite - Zero-copy views of existing NumPy (or other PEP 3118) buffers. This does not allocate ndarrays.

Usage

import nuwa_sdk

proc add(a: int, b: int): int {.nuwa_export.} =
  ## Add two integers together
  return a + b

proc greet(name: string): string {.nuwa_export.} =
  ## Greet a person by name
  return "Hello, " & name

When you build your project with nuwa develop or nuwa build, this macro will:

1. Export the function to Python (via nimpy)
2. Write compile-time metadata about function signatures (JSON files when -d:nuwaStubDir= is set, otherwise NUWA_STUB: lines on stdout)
3. Let nuwa-build generate .pyi stub files from that metadata

GIL Release with withNogil

The withNogil template allows you to release Python's Global Interpreter Lock (GIL) during performance-critical Nim code. This enables true parallelism when your extension is used from multi-threaded Python code.

import nuwa_sdk

proc computePi(iterations: int): float {.nuwa_export.} =
  ## Compute Pi using Monte Carlo method (GIL-released)
  var count = 0
  withNogil:
    # Pure Nim code runs without Python interpreter interference
    # Other Python threads can run concurrently
    for i in 0..<iterations:
      let x = rand(1.0)
      let y = rand(1.0)
      if x*x + y*y <= 1.0:
        count += 1
  return 4.0 * float(count) / float(iterations)

When to use withNogil

• CPU-bound computations: Mathematical operations, numeric algorithms
• Batch processing: Processing large datasets without Python interaction
• Parallel workloads: Allow other Python threads to run while Nim computes

When NOT to use withNogil

• Python API calls: Any code that calls Python objects or nimpy functions
• Data transfer: Converting between Nim and Python types
• I/O operations: File/network operations that release GIL automatically

How it works

1. PyEval_SaveThread() releases the GIL
2. Pure Nim code executes without Python interference
3. PyEval_RestoreThread() reacquires the GIL before returning to Python

Equivalent to Cython's with nogil: block or CPython's Py_BEGIN_ALLOW_THREADS.

NumPy / buffer views

asNumpyArray wraps an existing Python object that exports the buffer protocol (typically a NumPy array). It does not create arrays or copy data.

import nuwa_sdk

proc sumInt64(arr: PyObject): int64 {.nuwa_export.} =
  var view = asNumpyArray(arr, int64)
  result = 0
  for x in view:
    result += x

proc scaleInPlace(arr: PyObject, s: float64) {.nuwa_export.} =
  var view = asNumpyArrayWrite(arr, float64)
  for x in mitems(view):
    x = x * s

• Use a concrete element type (int64, float64, …), not a generic ndarray.
• isContiguous means C-order. Fortran-contiguous arrays still expose data (memory order is column-major).
• arr[i] is only for 1D arrays. Use arr[i, j] for 2D.
• items walks logical C-order even when storage is Fortran.
• Read-only arrays (setflags(write=False)) work with asNumpyArray and fail with asNumpyArrayWrite.
• close() is optional (RAII releases the buffer) and requires var, not let.

See NumPy buffers.

How It Works

nuwa_export macro

• Inspects your Nim functions at compile time
• Extracts parameter names, types, return types, and docstrings
• Maps Nim types to Python type annotations
• Writes JSON metadata to -d:nuwaStubDir= when nuwa-build provides that path
• Falls back to NUWA_STUB: lines on stdout
• nuwa-build reads that metadata and generates .pyi files

withNogil template

The withNogil template: - Wraps a block of Nim code with GIL release/reacquire calls - Dynamically loads Python C API functions (lazy initialization) - Ensures GIL is always reacquired even if an exception occurs - Allows multiple Python threads to execute Nim code concurrently

Supported Type Mappings

Installation

This package is automatically installed as a dependency when you use nuwa new to create a new project.

You can also install it manually:

nimble install nuwa_sdk

License

MIT