orkid: Skill for Claude Code

Orkid Python Binding System Reference

When answering questions about Python bindings in orkid, consult these files.

Key Files

Component	Location
Type Codec Header	ork.core/inc/ork/python/pycodec.h
Type Codec Impl	ork.core/inc/ork/python/pycodec.inl
pybind11 Adapter	ork.core/inc/ork/python/pycodec_pybind11.inl
GIL-Safe Wrapper	ork.core/inc/ork/python/gil_safe_pyobj.h
Unmanaged Pointers	ork.core/inc/ork/python/wraprawpointer.inl
VarMap Bindings	ork.core/inc/ork/python/common_bindings/pyext_varmap.inl
Math Bindings	ork.core/inc/ork/python/common_bindings/pyext_math_la.inl
CrcString Bindings	ork.core/inc/ork/python/common_bindings/pyext_crcstring.inl
Core pyext.h	ork.core/pyext/pyext.h
Lev2 pyext.h	ork.lev2/pyext/src/pyext.h
Module Init (lev2)	ork.lev2/pyext/src/pyext.cpp
UI Bindings	ork.lev2/pyext/src/pyext_ui.cpp
Toolbar Bindings	ork.lev2/pyext/src/pyext_ui_toolbar.cpp

Architecture Overview

Type Codec (pb11_typecodec_t)

Central type conversion between C++ and Python:

auto type_codec = python::pb11_typecodec_t::instance();

// Encode C++ → Python
py::object py_val = type_codec->encode(svar128_value);

// Decode Python → C++
svar128_t cpp_val = type_codec->decode(py_object);

// Register custom type
type_codec->registerStdCodec<my_ptr_t>(my_pybind_type);

Module Initialization Pattern

void pyinit_my_module(py::module& parent_module) {
  auto type_codec = python::pb11_typecodec_t::instance();
  
  auto my_type = py::class_<MyClass, myclass_ptr_t>(parent_module, "MyClass")
    .def(py::init<>())
    .def("method", ...)
    .def_property("prop", getter, setter);
  
  type_codec->registerStdCodec<myclass_ptr_t>(my_type);
}

Factory Patterns (Widget Creation)

Three standard factories on UI widget types:

// wfactory — standalone widget (for overlays, manual composition)
.def_static("wfactory", [type_codec](py::list py_args) -> widget_ptr_t {
  auto decoded_args = type_codec->decodeList(py_args);
  auto name = decoded_args[0].get<std::string>();
  return std::make_shared<MyWidget>(name);
})

// uifactory — add to layout group (returns layout item)
.def_static("uifactory", [type_codec](uilayoutgroup_ptr_t lg, py::list py_args) -> uilayoutitem_ptr_t {
  auto decoded_args = type_codec->decodeList(py_args);
  auto name = decoded_args[0].get<std::string>();
  return lg->makeChild<MyWidget>(name).as_shared();
})