Lightweight Python bindings for zig

py.zig provides a lightweight interface for creating python extensions in zig.

It is intended to be used with setuptools-zig by simply cloning or copying py.zig into your python project, adding an Extension entry in your setup.py, and then using const py = @import("py.zig"); in your extensions source to define the python module.

from setuptools import Extension, setup
setup(
 name='pyzigtest',
 version='0.1.0',
 python_requires='>=3.10',
 build_zig=True,
 ext_modules=[
 Extension(
 'pyzigtest',
 sources=[
 'src/pyzigtest.zig'
 ],
 extra_compile_args=["-ODebug"] # or -OReleaseFast, etc..
 )
 ],
 setup_requires=['setuptools-zig'],
)

See the example for a complete example.

Why

py.zig is designed to be a much lighter alternative to something like ziggy-pydust.

Design

For each builtin python type py.zig defines an equivalent extern struct that embeds a single field impl with the underlying python type. For examle a tuple is defined as:

// c-import Python.hpubconstc=@cImport({@cDefine("PY_SSIZE_T_CLEAN","1");@cInclude("Python.h");});// ... pubconstTuple=externstruct{// The underlying python structureimpl:c.PyTupleObject,// Import the object protocolpubusingnamespaceObjectProtocol(@This());// Import the SequenceProtocolpubusingnamespaceSequenceProtocol(@This());// Some more tuple methods here...};

Since these types have the same memory representation as the c-equivalent you can safetly use @ptrCast and pass them to any functions (C/C++, or whatever) that take a tuple object.

You can also access any members of the python type using impl, directly. For example the Type can get the name like this:

pubconstType=externstruct{// The underlying python structureimpl:c.PyTypeObject,// ... // Return the name of this typepubinlinefnclassName(self:*Type)[:0]constu8{returnstd.mem.span(self.impl.tp_name);}};

However it is generally recommended to use public C-API functions as is done with the wrappers in py.zig.

Status

This is currently very alpha status and is undergoing breaking changes to functions but the basic design concept is unlikely to change.

Plans

Auto generate bindings...