Embedded Python Template (Cookiecutter)

This repository is a Cookiecutter template that scaffolds a Zig-based project embedding CPython. It generates a ready-to-build runtime, a Zig executable, and a packaging workflow for bundling Python libraries with your application.

Overview

• Generate a Zig project that calls the Python C API safely.
• Build steps for runtime, app binary, and Python packages.
• Ships third-party Python libraries inside site-packages/.
• Cross-platform strategy: Windows bundles CPython; Linux/macOS load system Python.

Prerequisites

• Python 3.8+ and pip (to run Cookiecutter)
• Cookiecutter installed via pip install cookiecutter
• Zig 0.15+ installed and on PATH
• C toolchain:
  • Windows: Visual Studio 2022 (MSBuild, C++ build tools)
  • Linux: GCC
  • macOS: Clang (Xcode Command Line Tools)
• git for dependency fetching (optional but recommended)

Generate a Pr (for optional Rust extensions in packages)oject

You can generate from this local folder or from a git URL.

• Local path (cross-platform):
  • cookiecutter . (run from the repo root)
• From a git URL:
  • cookiecutter https://github.com/krita-frag/embedded-python-template.git

Cookiecutter will prompt you for values. After generation:

• cd <project_slug>
• zig build (runs the full build: runtime → app → packages)
• The built binary and runtime will be placed under dist/.

Cookiecutter Prompts

This template asks for the following values:

• project_name: Human-friendly project name (default Python Embedded Runtime).
• project_slug: Directory and package slug (default embedded_python).
• exe_name: Executable name (defaults to {{ cookiecutter.project_slug }}).
• python_package: Default Python package name under packages/ (default core).
• python_module_artifact: The compiled module artifact name (default _core).
• description: Short description (default Embed CPython into Zig applications).
• author_name: Your author name.
• license: License string (default MIT).

Note: Some directories are copied without Jinja rendering to preserve internal tooling paths.

Project Layout

After generation, you will see a structure similar to:

<project_slug>/
├── build.zig
├── build.zig.zon
├── src/
│   ├── cli.zig
│   ├── main.zig
│   ├── python_runtime.zig
│   ├── root.zig
│   └── runtime_config.zig
├── packages/
│   └── <python_package>/
├── package_builder/
│   ├── README.md
│   └── (packaging tooling)
└── README.md

Build and Run

Common commands from the project root:

• zig build — full build (runtime → app → packages)
• zig build -Dbuild_step=runtime — prepare the embedded runtime only
• zig build -Dbuild_step=app — build the Zig executable to dist/
• zig build -Dbuild_step=packages — package Python libs into site-packages/

Useful options:

• zig build -Dcpython_version=3.12.3
• zig build -Dbuild_dir=build -Ddist_dir=dist
• zig build -Dexe_name=<your-exe-name>

Run the built executable from dist/:

• Windows: dist\<exe_name>.exe
• POSIX: ./dist/<exe_name>

Packaging Python Libraries

• Place your Python code under packages/<python_package>/.
• The packaging workflow uses the embedded interpreter to build and copy artifacts to site-packages/.
• See package_builder/README.md inside the generated project for details and advanced usage.

Configuration

Runtime configuration is controlled by runtime/py_config.txt (generated by the template). Typical fields:

version=3.12.3
site_packages_dir=site-packages;runtime
optimize_level=0
python_malloc=pymalloc
hash_seed=random
gc_enabled=true
gc_thresholds=700,10,10

Adjust these to match your deployment needs. On Windows, the template sets PYTHONHOME to the runtime bundle and uses the CPython standard library zip.

Platform Notes

• Windows bundles headers, import libs, and pythonXY.zip into runtime/.
• Linux/macOS load the system Python dynamically (ensure the correct version is installed).

Troubleshooting

• Ensure zig is on PATH and matches the required version.
• On Windows, install the Visual Studio C++ build tools and restart your shell.
• If package builds fail, verify your Python environment and read package_builder/README.md.
• For verbose build logs, use zig build -Dlog_level=debug (if supported by the template’s build script).

License

This template is provided under the MIT license. Generated projects may use the license you select during Cookiecutter prompts.