zig-zon 0.2.4__tar.gz → 0.2.6__tar.gz

{zig-zon-0.2.4 → zig-zon-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zig-zon
-Version: 0.2.4
+Version: 0.2.6
 Summary: a native cpython extension to parse zig object notation strings
 Author-email: Tobias Simetsreiter <dasimmet@gmail.com>
 Maintainer-email: Tobias Simetsreiter <dasimmet@gmail.com>

zig-zon-0.2.6/build.zig

@@ -0,0 +1,119 @@
+const std = @import("std");
+const Build = std.Build;
+const zig_python_sdist = @import("zig_python_sdist");
+const zon = @import("build.zig.zon");
+
+pub fn build(b: *Build) void {
+    const target = b.standardTargetOptions(.{});
+    const optimize = b.standardOptimizeOption(.{});
+
+    // this target and section of our build is used at pip install time
+    const ext_install_step = b.step("bdist-wheel", "build python extension module");
+    ext_install_step.dependOn(
+        &b.addInstallFile(b.path("src/zig_zon.pyi"), "lib/zig_zon.pyi").step,
+    );
+
+    // this generates a python sdist archive
+    const sdist = zig_python_sdist.createSdistStep(b, .{
+        .name = "zig-zon",
+        .version = zon.version,
+        .description = b.path("README.md"),
+        .build = .{
+            .args = &.{
+                ext_install_step.name,
+                b.fmt("-Doptimize={s}", .{@tagName(optimize)}),
+            },
+        },
+        .extra_pkg_info = @import("pkg-info.zon"),
+        .files = &.{
+            .{ .src = b.path("LICENSE"), .dest = "LICENSE" },
+            .{ .src = b.path("pkg-info.zon"), .dest = "pkg-info.zon" },
+            .{ .src = b.path("build.zig.zon"), .dest = "build.zig.zon" },
+            .{ .src = b.path("build.zig"), .dest = "build.zig" },
+            .{ .src = b.path("src/zig_zon.zig"), .dest = "src/zig_zon.zig" },
+            .{ .src = b.path("src/zig_zon.pyi"), .dest = "src/zig_zon.pyi" },
+        },
+        .compression = .best,
+    });
+
+    const sdistfile = b.addInstallFileWithDir(
+        sdist.getEmittedArchive(),
+        .{ .custom = "src" },
+        sdist.basename,
+    );
+    b.getInstallStep().dependOn(&sdistfile.step);
+
+    // we can use a python virtual environment inside
+    // the zig cache to test pip installation
+    const test_pip_install = zig_python_sdist.createVenvInstallTest(
+        b,
+        .{
+            .sdist = sdist.getEmittedArchive(),
+            .unittest_py = &.{b.path("src/test_zig_zon.py")},
+            .twine_check = true,
+            .no_clean = b.option(bool, "pip-no-clean", "dont cleanup pip temp dirs") orelse false,
+        },
+    );
+    b.step("test-pip-install", "").dependOn(test_pip_install.step);
+
+    const cpython = zig_python_sdist.createCPythonModule(b, .{
+        .target = target,
+        .version = zon.version,
+        .optimize = .ReleaseSmall,
+    });
+    const lib = b.addLibrary(.{
+        .name = "zig_zon",
+        .root_module = b.addModule("zig_zon", .{
+            .root_source_file = b.path("src/zig_zon.zig"),
+            .target = target,
+            .optimize = optimize,
+            .imports = &.{
+                .{ .name = "cpython", .module = cpython },
+            },
+        }),
+        .linkage = .dynamic,
+    });
+    const ext_install = zig_python_sdist.installExtLib(b, lib);
+    ext_install_step.dependOn(&ext_install.step);
+
+    ext_install_step.dependOn(&ext_install.step);
+
+    const ext_path = zig_python_sdist.CPython.renameExtLib(b, lib);
+
+    {
+        const ext_tests = ext_path.wf.addCopyFile(b.path("src/test_zig_zon.py"), "test_zig_zon.py");
+        _ = ext_path.wf.addCopyFile(b.path("build.zig.zon"), "build.zig.zon");
+        const test_run = Build.Step.Run.create(b, "unittest");
+        test_run.setCwd(ext_path.wf.getDirectory());
+        test_run.setEnvironmentVariable("PYTHONPATH", ".");
+        test_run.addFileArg(zig_python_sdist.CPython.find(b));
+        if (b.option(bool, "tracetest", "run unittest with tracing") orelse false) {
+            test_run.addArgs(&.{ "-m", "trace", "--trace" });
+        } else {
+            test_run.addArgs(&.{ "-m", "unittest" });
+        }
+        test_run.addDirectoryArg(ext_tests);
+        b.step("test-bdist", "run unittests against the extension").dependOn(&test_run.step);
+    }
+
+    const usf = b.addUpdateSourceFiles();
+    b.step("update-src", "updates the pyi file. needs 'mypy' installed").dependOn(&usf.step);
+
+    {
+        const stubgen_run = Build.Step.Run.create(b, "stubgen");
+        stubgen_run.setCwd(ext_path.wf.getDirectory());
+        stubgen_run.addArgs(&.{
+            "stubgen",
+            "-m",
+            lib.name,
+            "-o",
+        });
+        const stub_dir = stubgen_run.addOutputDirectoryArg("stubgen");
+        stubgen_run.addArg("--search-path");
+        stubgen_run.addDirectoryArg(ext_path.wf.getDirectory());
+        usf.addCopyFileToSource(
+            stub_dir.path(b, b.fmt("{s}.pyi", .{lib.name})),
+            b.fmt("src/{s}.pyi", .{lib.name}),
+        );
+    }
+}

{zig-zon-0.2.4 → zig-zon-0.2.6}/build.zig.zon

@@ -1,12 +1,12 @@
 .{
     .name = .python_zig_zon,
     .fingerprint = 0x3d332656a3644fc9,
-    .version = "0.2.4",
+    .version = "0.2.6",
     .minimum_zig_version = "0.16.0",
     .dependencies = .{
         .zig_python_sdist = .{
-            .url = "git+https://codeberg.org/dasimmet/zig-python-sdist.git#b09744edafe683ae6000a96498cc68e86173dbe7",
-            .hash = "zig_python_sdist-0.0.3-wjgdOlzvAADTtFV1n4xTLUwlgCsiLDcmhebfZ7kWM05z",
+            .url = "git+https://codeberg.org/dasimmet/zig-python-sdist.git?ref=0.0.8#3f06dd8177fbba62a68b7f0894b4a3d26cfb9fcf",
+            .hash = "zig_python_sdist-0.0.8-wjgdOimGAQBiUtyW-KGTUzlNhuwanlP9ealvenf3vcpw",
         },
     },
     .paths = .{
@@ -16,7 +16,5 @@
         "pkg-info.zon",
         "LICENSE",
         "README.md",
-        "setup.py",
-        "pyproject.toml",
     },
 }

zig-zon-0.2.6/setup.py

@@ -0,0 +1,124 @@
+#!/usr/bin/env python
+
+from setuptools import setup
+from setuptools.dist import Distribution
+from setuptools.command.bdist_wheel import bdist_wheel
+import subprocess
+import sys
+import os
+import json
+import glob
+import shutil
+
+with open("setup.zig.json") as fd:
+    setup_json = json.load(fd)
+
+
+def mkversion(v, need_release=False):
+    '''assembles a dict of semantic version to string'''
+    if need_release:
+        assert v.get('pre') is None, "cannot use version with pre: " + str(v)
+        assert v.get(
+            'build') is None, "cannot use version with build: " + str(v)
+    return str(v['major']) + '.' + str(
+        v['minor']) + '.' + str(v['patch'])
+
+
+class ZigDistribution(Distribution):
+    def has_ext_modules(self):
+        return setup_json['has_ext_modules']
+
+
+class ZigBuildWheel(bdist_wheel):
+    def initialize_options(self):
+        super().initialize_options()
+        if 'py_limited_api' in setup_json and setup_json['py_limited_api']:
+            self.py_limited_api = setup_json['py_limited_api']
+
+    def run(self, *args, **kwargs):
+        print("py_limited_api:", self.py_limited_api, file=sys.stderr)
+        print("plat_name:", self.plat_name, file=sys.stderr)
+
+        import ziglang
+        zig_exe = os.path.join(
+            os.path.dirname(ziglang.__file__), "zig")
+
+        cwd = os.getcwd()
+        print("zig build dir:", cwd, file=sys.stderr)
+        print("using zig exe:", zig_exe, file=sys.stderr)
+
+        extra_build_args = setup_json['build']['args']
+        build_cmd = [zig_exe, 'build'] + extra_build_args
+
+        print("zig build:", build_cmd, file=sys.stderr)
+        subprocess.check_call(build_cmd)
+
+        os.makedirs(self.bdist_dir, exist_ok=True)
+        copy_patterns = setup_json['build']['copy_patterns']
+        pkg_name = setup_json['name'].replace('-', '_')
+
+        for item in copy_patterns:
+            pattern = item['pattern']
+            dest = item.get('dest')
+            package_dir = item.get('package_dir', False)
+
+            if package_dir:
+                if dest:
+                    dest = os.path.join(pkg_name, dest)
+                else:
+                    dest = pkg_name
+            elif dest:
+                dest = dest.replace('{name}', pkg_name).replace(
+                    '{package}', pkg_name)
+
+            artifacts = glob.glob(pattern)
+            if len(artifacts) == 0:
+                raise Exception(
+                    'no zig artifacts found in {}/{}'.format(cwd, pattern))
+
+            for it in artifacts:
+                if dest:
+                    is_dir = (
+                        dest.endswith('/') or
+                        dest.endswith('\\') or
+                        any(c in pattern for c in '*?[]') or
+                        (os.path.splitext(dest)[
+                         1] == '' and os.path.splitext(it)[1] != '')
+                    )
+                    if is_dir:
+                        dst = os.path.join(
+                            self.bdist_dir, dest, os.path.basename(it))
+                    else:
+                        dst = os.path.join(self.bdist_dir, dest)
+                else:
+                    dst = os.path.join(self.bdist_dir, os.path.basename(it))
+
+                os.makedirs(os.path.dirname(dst), exist_ok=True)
+                print("cp", it, dst, file=sys.stderr)
+                if os.path.isdir(it):
+                    shutil.copytree(it, dst, dirs_exist_ok=True)
+                else:
+                    shutil.copyfile(it, dst)
+
+        return super().run(*args, **kwargs)
+
+
+options = {}
+if 'py_limited_api' in setup_json and setup_json['py_limited_api']:
+    options['bdist_wheel'] = {'py_limited_api': setup_json['py_limited_api']}
+
+setup(
+    name=setup_json['name'],
+    version=mkversion(setup_json['version']),
+    cmdclass={'bdist_wheel': ZigBuildWheel},
+    options=options,
+    install_requires=setup_json['install_requires'] if 'install_requires' in setup_json else None,
+    entry_points=setup_json['entry_points'] if 'entry_points' in setup_json else None,
+    packages=setup_json['build']['packages'],
+    distclass=ZigDistribution,
+    setup_requires=[
+        "setuptools",
+        "wheel",
+        "ziglang==" + mkversion(setup_json['zig_version'], need_release=True),
+    ] + setup_json['build']['requires'],
+)

zig-zon-0.2.6/setup.zig.json

@@ -0,0 +1 @@
+{"name":"zig_zon","version":{"major":0,"minor":2,"patch":6},"zig_version":{"major":0,"minor":16,"patch":0},"build":{"args":["--fork=zig-pkg/zig_python_sdist-0.0.8","bdist-wheel","-Doptimize=ReleaseSmall"],"requires":[],"packages":[],"copy_patterns":[{"pattern":"zig-out/lib/*","package_dir":false}]},"has_ext_modules":true}

zig-zon-0.2.6/src/zig_zon.pyi

@@ -0,0 +1,5 @@
+__version__: dict
+__version_str__: str
+__zig_builtin__: dict
+
+def parse(*args, **kwargs): ...

{zig-zon-0.2.4 → zig-zon-0.2.6}/src/zig_zon.zig

@@ -8,28 +8,54 @@ const cpython = @import("cpython");
 const c = cpython.c;
 const PyObject = c.PyObject;
 
-pub var methods = [_]c.PyMethodDef{
-    c.PyMethodDef{
-        .ml_name = "parse",
-        .ml_meth = @ptrCast(@alignCast(&parse)),
-        .ml_flags = @as(c_int, 1),
-        .ml_doc = "parse a zon literal to a python object",
-    },
-    c.PyMethodDef{},
-};
-
-pub var zigmodule = c.PyModuleDef{
+pub var zigmodule: c.PyModuleDef = .{
     .m_name = "zig_zon",
-    .m_methods = &methods,
+    .m_methods = @constCast(&[_]c.PyMethodDef{
+        .{
+            .ml_name = "parse",
+            .ml_meth = @ptrCast(@alignCast(&parse)),
+            .ml_flags = 1,
+            .ml_doc = "parse a zon literal to a python object",
+        },
+        .{},
+    }),
 };
 
 pub export fn PyInit_zig_zon() [*c]c.PyObject {
     const mod = c.PyModule_Create(&zigmodule);
+
+    {
+        // const annotations = c.PyDict_New();
+        // defer c.Py_DecRef(annotations);
+        // const builtins = c.PyImport_ImportModule("builtins");
+        // defer c.Py_DecRef(builtins);
+
+        // const str_type = c.PyObject_GetAttrString(builtins, "str") orelse PyErrPanic();
+        // defer c.Py_DecRef(str_type);
+
+        // assert(0 <= c.PyDict_SetItemString(annotations, "value", str_type));
+
+        // const parse_ref = c.PyObject_GetAttrString(mod, "parse") orelse PyErrPanic();
+        // defer c.Py_DecRef(parse_ref);
+
+        //TODO: find another way to set annotations, since a builtin function is immutable.
+
+        // if (0 > c.PyObject_SetAttrString(parse_ref, "__annotations__", annotations)) {
+        //     c.PyErr_Print();
+        //     @panic("WTF");
+        // }
+    }
+
     cpython.addVersion(mod);
     cpython.addZigBuiltin(mod);
     return mod;
 }
 
+pub fn PyErrPanic() noreturn {
+    c.PyErr_Print();
+    @panic("Unexpected PyErr!");
+}
+
 pub fn parse(self: [*]PyObject, args: [*]PyObject) callconv(.c) [*c]PyObject {
     _ = self;
     const zon_slice: [:0]u8 = zon_slice: {
@@ -38,7 +64,7 @@ pub fn parse(self: [*]PyObject, args: [*]PyObject) callconv(.c) [*c]PyObject {
         break :zon_slice std.mem.sliceTo(zon_txt, 0);
     };
 
-    var arena_instance = std.heap.ArenaAllocator.init(std.heap.c_allocator);
+    var arena_instance = std.heap.ArenaAllocator.init(cpython.py_allocator);
     defer arena_instance.deinit();
     const arena = arena_instance.allocator();
 

zig-zon-0.2.6/zig-pkg/zig_python_sdist-0.0.8/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (Expat)
+
+Copyright (c) Zig contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

zig-zon-0.2.6/zig-pkg/zig_python_sdist-0.0.8/README.md

@@ -0,0 +1,275 @@
+# Zig Python Sdist
+
+A toolset to build Python source distributions (`sdist`) and wheels directly with `zig build`. Inspired by Loris Cro's talk [Deinventing the Wheel](https://www.youtube.com/watch?v=HPmefnqirHk).
+
+`zig-python-sdist` packages your Zig project into a standard `.tar.gz` source distribution for PyPI. When a user runs `pip install your-package`, `pip` automatically installs the `ziglang` compiler wheel from PyPI and invokes `zig build` to compile native extensions on the target machine—no manual Python packaging toolchain (C/C++ compilers, CMake, setup.py boilerplate) required.
+
+A complete runnable example is available in the [`example/`](example/) directory.
+
+---
+
+## Installation
+
+Add `zig-python-sdist` to your project's `build.zig.zon` (requires Zig >= 0.16.0):
+
+```bash
+zig fetch --save git+https://codeberg.org/dasimmet/zig-python-sdist
+```
+
+Then import it in `build.zig`:
+
+```zig
+const zig_python_sdist = @import("zig_python_sdist");
+```
+
+---
+
+## Usage Scenarios
+
+`zig-python-sdist` supports two main workflows:
+1. **CPython Native Extension**: A compiled module (`.so` / `.pyd`) using CPython headers and the Python C API (supporting the Python Limited API / `abi3`).
+2. **Ctypes Wrapper**: A standalone shared library accompanied by Python files loaded via `ctypes`.
+
+---
+
+### 1. CPython Extension (Limited API / `abi3`)
+
+#### `build.zig`
+
+```zig
+const std = @import("std");
+const zig_python_sdist = @import("zig_python_sdist");
+const zon = @import("build.zig.zon");
+
+pub fn build(b: *std.Build) void {
+    const target = b.standardTargetOptions(.{});
+    const optimize = b.standardOptimizeOption(.{});
+
+    // 1. Step executed by pip at wheel build time
+    const build_ext_step = b.step("bdist-wheel-cpython", "build the extension module");
+
+    // 2. Generate CPython module and translate Python headers
+    const cpython = zig_python_sdist.createCPythonModule(b, .{
+        .target = target,
+        .optimize = optimize,
+        .version = zon.version,
+        .py_limited_api = "cp39", // sets Py_LIMITED_API for Python 3.9+
+    });
+
+    // 3. Build the dynamic extension module
+    const example_cpython = b.addLibrary(.{
+        .name = "example_cpython",
+        .linkage = .dynamic,
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("example_cpython.zig"),
+            .target = target,
+            .optimize = optimize,
+            .imports = &.{
+                .{ .name = "cpython", .module = cpython },
+            },
+        }),
+    });
+
+    // Install extension to zig-out/lib/
+    const example_cpython_install = zig_python_sdist.installExtLib(b, example_cpython);
+    build_ext_step.dependOn(&example_cpython_install.step);
+
+    // 4. Define the sdist archive
+    const sdist = zig_python_sdist.createSdistStep(b, .{
+        .name = "example-cpython",
+        .version = zon.version,
+        .description = b.path("README.md"),
+        .py_limited_api = "cp39", // tags wheel with cp39-abi3
+        .build = .{
+            .args = &.{
+                build_ext_step.name,
+                b.fmt("-Doptimize={s}", .{@tagName(optimize)}),
+            },
+            .copy_patterns = &.{
+                .{ .pattern = "zig-out/lib/*" },
+                .{ .pattern = "example_cpython.pyi" },
+            },
+        },
+        .files = &.{
+            .{ .src = b.path("build.zig.zon"), .dest = "build.zig.zon" },
+            .{ .src = b.path("build.zig"), .dest = "build.zig" },
+            .{ .src = b.path("example_cpython.zig"), .dest = "example_cpython.zig" },
+            .{ .src = b.path("example_cpython.pyi"), .dest = "example_cpython.pyi" },
+            .{ .src = b.path("README.md"), .dest = "README.md" },
+            .{ .src = b.path("LICENSE"), .dest = "LICENSE" },
+        },
+    });
+
+    // Building the default install step produces the .tar.gz sdist archive
+    const sdist_install = sdist.install();
+    b.getInstallStep().dependOn(&sdist_install.step);
+}
+```
+
+#### `example_cpython.zig`
+
+```zig
+const std = @import("std");
+const python = @import("cpython");
+const c = python.c;
+
+pub export fn PyInit_example_cpython() [*c]c.PyObject {
+    const mod = c.PyModule_Create(&zigmodule);
+    python.addVersion(mod);
+    python.addZigBuiltin(mod);
+    return mod;
+}
+
+pub var zigmodule: c.PyModuleDef = .{
+    .m_name = "example_cpython",
+    .m_methods = @constCast(&[_]c.PyMethodDef{
+        .{
+            .ml_name = "__main__",
+            .ml_meth = @ptrCast(@alignCast(&python.wrapMain(main, .{}))),
+            .ml_flags = @as(c_int, 1),
+            .ml_doc = "main script entrypoint",
+        },
+        .{},
+    }),
+};
+
+pub fn main(init: std.process.Init) !void {
+    const stdout = std.Io.File.stdout();
+    var buf: [4096]u8 = undefined;
+    var w = stdout.writer(init.io, &buf);
+    try w.interface.print("Hello from Zig!\n", .{});
+    try w.interface.flush();
+}
+```
+
+---
+
+### 2. Ctypes Dynamic Library (Pure Wheel)
+
+When distributing a shared library called through Python's `ctypes`, you can set `has_ext_modules = false` so setuptools produces a pure wheel (`py3-none-any.whl`), and use `package_dir = true` to place the library and `__init__.py` inside the package directory.
+
+#### `build.zig`
+
+```zig
+    const example_ctypes = b.addLibrary(.{
+        .name = "example_ctypes",
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("example_ctypes.zig"),
+            .target = target,
+            .optimize = optimize,
+            .link_libc = false,
+        }),
+        .linkage = .dynamic,
+    });
+    example_ctypes.rdynamic = true;
+
+    const build_ctypes_step = b.step("bdist-wheel-ctypes", "build shared library");
+    build_ctypes_step.dependOn(&b.addInstallArtifact(example_ctypes, .{}).step);
+
+    const sdist_ctypes = zig_python_sdist.createSdistStep(b, .{
+        .name = "example-ctypes",
+        .version = zon.version,
+        .description = b.path("README.md"),
+        .has_ext_modules = false, // builds a py3-none-any wheel
+        .build = .{
+            .args = &.{
+                b.fmt("-Doptimize={s}", .{@tagName(optimize)}),
+                build_ctypes_step.name,
+            },
+            .copy_patterns = &.{
+                // places compiled shared library into example_ctypes/
+                .{ .pattern = "zig-out/*/*", .package_dir = true },
+                // renames example_ctypes.py to __init__.py inside example_ctypes/
+                .{ .pattern = "example_ctypes.py", .dest = "__init__.py", .package_dir = true },
+            },
+        },
+        .files = &.{
+            .{ .src = b.path("build.zig.zon"), .dest = "build.zig.zon" },
+            .{ .src = b.path("build.zig"), .dest = "build.zig" },
+            .{ .src = b.path("example_ctypes.zig"), .dest = "example_ctypes.zig" },
+            .{ .src = b.path("example_ctypes.py"), .dest = "example_ctypes.py" },
+        },
+    });
+```
+
+---
+
+## API Reference
+
+### `createCPythonModule(b, options)`
+
+Generates a Zig module linked against CPython headers:
+- `target`: Target architecture and OS.
+- `optimize`: Optimization mode.
+- `version`: Package version string.
+- `py_limited_api`: Python tag (e.g., `"cp39"`, `"cp310"`) or hex version (e.g. `"0x03090000"`). When set, `#define Py_LIMITED_API` is enabled during header translation.
+- `header_file`: Optional custom C header file (defaults to `python-translatec.h`).
+- `python_exe`: Optional path to Python executable used for finding header search paths.
+- `macros`: Additional C macro definitions.
+
+### `createSdistStep(b, options)`
+
+Creates an `SDistStep` that packages source files into an sdist archive:
+- `name`: Distribution name on PyPI.
+- `version`: Package version string.
+- `description`: Path to README file (e.g. `b.path("README.md")`). Added to `PKG-INFO`.
+- `py_limited_api`: Python tag (e.g. `"cp39"`) passed to setuptools to build an `abi3` wheel.
+- `has_ext_modules`: Set to `false` for pure-Python or ctypes packages (defaults to `true`).
+- `build`: Configuration for building wheels:
+  - `args`: Command-line arguments forwarded to `zig build` when `pip` builds the wheel.
+  - `copy_patterns`: Files and directories to copy into the wheel:
+    - `pattern`: Glob pattern (e.g. `"zig-out/lib/*"`).
+    - `dest`: Optional destination path or filename.
+    - `package_dir`: If `true`, prefixes destination with the package name.
+  - `packages`: Python packages to include.
+  - `requires`: Additional Python build dependencies.
+- `files`: Slice of `.{ .src = LazyPath, .dest = []const u8 }` to include in the archive.
+- `directories`: Slice of directory paths to include in the archive.
+- `entry_points`: Command-line scripts, e.g. `.{ .console_scripts = &.{ "my-cli = my_pkg:__main__" } }`.
+- `install_requires`: Slice of runtime dependencies (e.g. `&.{ "requests>=2.28" }`).
+- `extra_pkg_info`: Extra metadata headers added to `PKG-INFO`.
+- `compression`: Compression level (`.default`, `.best`, `.fast`).
+
+> [!TIP]
+> When your package uses dependencies from `build.zig.zon`, package the dependency directory into the sdist and pass `--fork=zig-pkg/<dep>` in `build.args` so `zig build` does not re-download it during pip install. `zig-python-sdist` automatically adds itself this way.
+
+---
+
+## The `cpython` Helper Library
+
+The imported `cpython` module provides:
+- **`c`**: Direct access to translated Python C API headers (`Python.h`).
+- **`py_allocator`**: A `std.mem.Allocator` implementation backed by Python's `PyMem_RawMalloc` / `PyMem_RawFree`.
+- **`wrapMain`**: Wraps a Zig main function (`fn (std.process.Init) !void` or `fn (std.process.Init.Minimal) !void`) into a CPython entrypoint function (`callconv(.c) [*c]PyObject`). CLI arguments and environment variables are automatically populated from Python's `sys.argv` and `os.environ`.
+- **`addVersion`**: Adds `__version__` and `__version_str__` attributes to a Python module.
+- **`addZigBuiltin`**: Adds a `__zig_builtin__` dictionary with Zig compiler target and build information.
+
+---
+
+## Testing Installations (`createVenvInstallTest`)
+
+You can verify the source distribution end-to-end by building and installing it into a temporary virtual environment:
+
+```zig
+    const test_pip = zig_python_sdist.createVenvInstallTest(b, .{
+        .sdist = sdist.getEmittedArchive(),
+        .unittest_py = &.{b.path("test/test_cpython_ext.py")},
+        .twine_check = true, // runs `twine check --strict` on the archive
+        .no_clean = b.option(bool, "pip-no-clean", "keep pip temp dirs") orelse false,
+    });
+    b.step("test-pip-install", "test installing sdist with pip").dependOn(test_pip.step);
+```
+
+Run tests with:
+
+```bash
+zig build test-pip-install
+```
+
+---
+
+## References
+
+- [Deinventing the Wheel - Loris Cro](https://www.youtube.com/watch?v=HPmefnqirHk)
+- [Python C API - Limited API](https://docs.python.org/3/c-api/stable.html)
+- [PEP 384 – Defining a Stable ABI](https://peps.python.org/pep-0384/)