Ziggy Pydust

Ziggy Pydust is a framework designed for writing and packaging native Python extension modules using the Zig programming language. It provides tools for seamless interop between Zig and Python, including:

• Packaging: Tools to package Zig-based Python extensions.
• Testing: A Pytest plugin that allows you to discover and run Zig tests within your Python test suite.
• Comptime Interop: Uses Zig's comptime capabilities to automatically wrap and unwrap arguments, enabling direct interop with native Zig types.

By default, Pydust generates pydust.build.zig (for bootstrapping) and build.zig (based on your pyproject.toml).

If you need full control over your build logic, enable Self-managed Mode. In this mode, Pydust only generates pydust.build.zig, and you are responsible for managing your own build.zig file.

To enable this:

1. Set self_managed = true under [tool.pydust] in pyproject.toml.
2. Remove all [[tool.pydust.ext_module]] entries from pyproject.toml.

You can define a subclass of a Zig Pydust class by including the parent class struct as a field within the subclass struct.

Limitations:

• It is currently not possible to create a subclass of a Python class.

To invoke methods from the parent class, use py.super(Type, self), which returns a proxy py.PyObject similar to Python's built-in super().

const SubClass = py.class(struct {
    parent: ParentClass, // Include parent as a field

    pub fn some_method(self: *Self) void {
        // Use super to call parent methods
        _ = py.super(ParentClass, self);
    }
});

Instance attributes allow storing state without custom getters/setters. In Pydust, attributes wrap the type in a struct definition: struct { value: T }.

Important:

• In Zig, you must access the attribute via the .value field (e.g., instance.my_attr.value).
• Attributes are currently read-only.

Python objects that implement the Buffer Protocol can be used with zero-copy in Ziggy Pydust. This allows functions to accept Python array.array objects, NumPy arrays, or any other object implementing the protocol without the overhead of copying data. When working with buffers, ensure you understand request types; common request types are represented in Pydust via py.PyBuffer.Flags (for example, py.PyBuffer.Flags.FULL_RO).

--8<-- "example/buffers.zig:sum"

--8<-- "test/test_buffers.py:sum"

When working with slices (e.g., []const u8) in Pydust functions, observe these memory safety rules:

1. Returning Slices: You cannot return slices from Pydust functions. Pydust cannot manage the deallocation of these slices once they are copied into Python.
2. Receiving Slices: You can accept slices as function arguments. However, the underlying bytes are only guaranteed to live for the duration of the function call. If you need the data to persist, you must copy it.

Dunder methods allow you to override Python built-in operators.

Key Concepts

• object: Refers to a pointer to a Pydust type, a py.PyObject(root), or other Pydust types like py.PyString.
• CallArgs(root): A Zig struct used for args and kwargs. Fields with default values are treated as keyword arguments.

Shorthand Signatures

For convenience, you can use these shorthand signatures:

• binaryfunc: fn(*Self, object) !object
• unaryfunc: fn(*Self) !object
• inquiry: fn(*Self) !bool

The PyString.appendSlice method is designed for performance and ergonomics when chaining multiple append operations. Unlike many other methods, appendSlice steals a reference to the string it is called on.

To use it safely in a chain, you must re-assign the result of the call to your variable, as the method returns the updated reference. If you are working with a borrowed reference from Python, you must call .incref() before calling .appendSlice to prevent the reference from being lost during the 'steal'.

var s = py.PyString.fromSlice("Hello ");
s = s.appendSlice("1, ");
s = s.appendSlice("2, ");
s = s.appendSlice("3");
return s;

To support Python's variadic arguments (*args and **kwargs) in a Zig function, include py.Args and py.Kwargs attributes within your function's argument struct.

```zig
const py = @import(