nuwa_export Macro

The {.nuwa_export.} pragma is the primary way to export Nim functions to Python with automatic type stub generation.

Basic 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

proc isPositive(x: int): bool {.nuwa_export.} =
  ## Check if a number is positive
  return x > 0

Docstrings

Use Nim docstring comments (##) - they will be included in the generated .pyi files:

proc calculate(x: float, y: float): float {.nuwa_export.} =
  ## Calculate the hypotenuse of a right triangle
  ##
  ## This function uses the Pythagorean theorem to compute
  ## the length of the hypotenuse given the two other sides.
  return sqrt(x*x + y*y)

How It Works

The nuwa_export macro:

1. Inspects your function at compile time
2. Extracts parameter names and types
3. Extracts return type

4. Extracts docstring comments

5. Maps Nim types to Python types

6. int → int
7. float → float
8. string → str
9. bool → bool

10. void → None

11. Emits metadata for nuwa-build

12. With -d:nuwaStubDir=/path, writes one JSON file per export
13. Otherwise prints NUWA_STUB: lines to stdout
14. Includes function signature and docstring

15. Captured by nuwa develop / nuwa build

16. Generates .pyi files

17. Creates type stub in your package directory
18. Enables IDE autocomplete and type checking
19. Follows PEP 484 type hint standards

Generated Type Stubs

For this Nim code:

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

Nuwa generates this .pyi file:

def add(a: int, b: int) -> int:
    """Add two integers together"""
    ...

Default Parameters

You can use Nim's default parameters:

proc greet(name: string; greeting: string = "Hello"): string {.nuwa_export.} =
  ## Greet someone with a custom greeting
  return greeting & ", " & name

Varargs

For variable arguments, use openArray:

proc sum(numbers: varargs[int]): int {.nuwa_export.} =
  ## Sum all provided numbers
  result = 0
  for n in numbers:
    result += n

Common Patterns

Multiple Return Values

Use tuples to return multiple values:

proc divide(a: float, b: float): tuple[quotient: float, remainder: float] {.nuwa_export.} =
  ## Divide two numbers and return quotient and remainder
  let q = a / b
  let r = a mod b
  return (quotient: q, remainder: r)

Optional Parameters

Use Option from nim's standard library (requires manual handling):

import std/options

proc findUser(id: int): Option[string] {.nuwa_export.} =
  ## Find a user by ID, returns None if not found
  # Implementation here
  if id == 1:
    return some("Alice")
  else:
    return none(string)

Exporting Procedures from Different Modules

When using multi-file projects with include, all included procedures marked with {.nuwa_export.} will be exported:

# nim/my_lib.nim
import nuwa_sdk
include helpers

proc mainFunction(): int {.nuwa_export.} =
  return helperFunction()

# nim/helpers.nim
proc helperFunction(): int {.nuwa_export.} =
  return 42

Both mainFunction and helperFunction will be exported to Python.