orkcore-python

What problem does it solve?

Orkid's C++ engine exposes a rich but complex Python binding surface that requires consistent type conversion, safe callback handling across threads and interpreters, and repeatable module initialization patterns so developers can reliably interact with engine objects from Python.

Core Features & Use Cases

• Type Codec: Centralized encode/decode layer for converting between Orkid C++ types and Python objects, and registering custom pointer codecs.
• GIL-Safe Wrapper: A gil_safe_pyobj construct for storing Python callbacks in C++ and ensuring the GIL is acquired on destruction and invocation.
• Dual Adapter System: Support for both pybind11 (main interpreter) and nanobind (subinterpreters) via adapter templates and shared binding code.
• VarMap and Bindings: Dynamic attribute access and common bindings for math, crc strings, and VarMap semantics.
• Factory & Callback Patterns: Standard wfactory/uifactory statics for UI widget creation and recommended callback binding patterns for safety.
• Use Cases: Bind a new engine class to Python with proper type codec registration, expose UI widgets with wfactory/uifactory, and store long-lived Python callbacks safely from non-GIL threads.

Quick Start

Show me how to implement a pybind11 module initializer that registers a custom type codec, binds a widget with wfactory and uifactory statics, and uses gil_safe_pyobj for thread-safe callbacks.