pyoz 0.11.2

Python extension modules in Zig, made easy

PyOZ

Zig's power meets Python's simplicity. Build blazing-fast Python extensions with zero boilerplate and zero Python C API headaches.

Documentation | Getting Started | Examples | GitHub

Quick Example

Write normal Zig code -- PyOZ handles all the Python integration automatically:

const pyoz = @import("PyOZ");

const Point = struct {
    x: f64,
    y: f64,

    pub fn magnitude(self: *const Point) f64 {
        return @sqrt(self.x * self.x + self.y * self.y);
    }
};

fn add(a: i64, b: i64) i64 {
    return a + b;
}

const MyModule = pyoz.module(.{
    .name = "mymodule",
    .funcs = &.{
        pyoz.func("add", add, "Add two numbers"),
    },
    .classes = &.{
        pyoz.class("Point", Point),
    },
});

pub export fn PyInit_mymodule() ?*pyoz.PyObject {
    return MyModule.init();
}

import mymodule

print(mymodule.add(2, 3))  # 5

p = mymodule.Point(3.0, 4.0)
print(p.magnitude())  # 5.0
print(p.x, p.y)       # 3.0 4.0

Features

• Declarative API -- Define modules, functions, and classes with simple struct literals
• Automatic type conversion -- Zig i64, f64, []const u8, structs, optionals, error unions all map to Python types automatically
• Full class support -- __init__, __repr__, __add__, __iter__, __getitem__, properties, static/class methods, inheritance
• NumPy integration -- Zero-copy array access via buffer protocol
• Error handling -- Zig errors become Python exceptions; custom exception types supported
• Type stubs -- Automatic .pyi generation for IDE autocomplete and type checking
• GIL management -- Release the GIL for CPU-bound Zig code with pyoz.releaseGIL()
• Cross-class references -- Methods can accept/return instances of other classes in the same module
• Simple tooling -- pyoz init, pyoz build, pyoz develop, pyoz publish

Installation

pip install pyoz

Requires Zig 0.15.0+ and Python 3.8--3.13.

Getting Started

# Create a new project
pyoz init myproject
cd myproject

# Build and install for development
pyoz develop

# Test it
python -c "import myproject; print(myproject.add(1, 2))"

Documentation

Full documentation at pyoz.dev:

• Installation -- Setup and requirements
• Quickstart -- Your first PyOZ module in 5 minutes
• Functions -- Module-level functions, keyword arguments
• Classes -- Full class support with magic methods
• Types -- Type conversion reference
• Properties -- Computed properties and getters/setters
• Error Handling -- Zig errors to Python exceptions
• NumPy -- Zero-copy buffer protocol
• GIL -- Releasing the GIL for parallelism
• CLI Reference -- Build, develop, publish commands
• Complete Example -- Full-featured module walkthrough

License

MIT