john/McRogueFace
1
0
Fork 0
Code Issues 32 Pull requests Projects Releases Wiki Activity

Update Adding Python Bindings

John McCardle 2026-02-07 23:47:56 +00:00
commit d65242a074
1 changed files with 378 additions and 378 deletions
Download patch file Download diff file Expand all files Collapse all files

756
Adding-Python-Bindings.-.md → Adding-Python-Bindings.md

@ -1,379 +1,379 @@
# Adding Python Bindings # Adding Python Bindings
Step-by-step guide for exposing C++ functionality to Python in McRogueFace. Step-by-step guide for exposing C++ functionality to Python in McRogueFace.
## Prerequisites ## Prerequisites
- Understanding of [[Python-Binding-Layer]] system architecture - Understanding of [[Python-Binding-Layer]] system architecture
- Familiarity with C++ class or function to expose - Familiarity with C++ class or function to expose
- McRogueFace builds from project root with `make` - McRogueFace builds from project root with `make`
## Quick Reference ## Quick Reference
**Related Systems:** [[Python-Binding-Layer]], [[UI-Component-Hierarchy]] **Related Systems:** [[Python-Binding-Layer]], [[UI-Component-Hierarchy]]
**Key Files:** **Key Files:**
- `src/McRFPy_API.cpp` - Module definition and type registration - `src/McRFPy_API.cpp` - Module definition and type registration
- `src/McRFPy_Doc.h` - Documentation macros (MCRF_METHOD, MCRF_PROPERTY, etc.) - `src/McRFPy_Doc.h` - Documentation macros (MCRF_METHOD, MCRF_PROPERTY, etc.)
- `src/PyObjectUtils.h` - Helper utilities - `src/PyObjectUtils.h` - Helper utilities
- Individual `src/Py*.cpp` files - Type bindings - Individual `src/Py*.cpp` files - Type bindings
--- ---
## Workflow 1: Adding a Property to Existing Class ## Workflow 1: Adding a Property to Existing Class
### Step 1: Add to PyGetSetDef Array ### Step 1: Add to PyGetSetDef Array
Find the class's `getsetters` array: Find the class's `getsetters` array:
```cpp ```cpp
PyGetSetDef UISprite::getsetters[] = { PyGetSetDef UISprite::getsetters[] = {
// Existing properties... // Existing properties...
// Add new property with doc macro // Add new property with doc macro
{"rotation", (getter)UISprite::get_rotation, (setter)UISprite::set_rotation, {"rotation", (getter)UISprite::get_rotation, (setter)UISprite::set_rotation,
MCRF_PROPERTY(rotation, MCRF_PROPERTY(rotation,
"Sprite rotation angle in degrees. Range: 0-360." "Sprite rotation angle in degrees. Range: 0-360."
), NULL}, ), NULL},
{NULL} // Sentinel - always last! {NULL} // Sentinel - always last!
}; };
``` ```
### Step 2: Implement Getter Function ### Step 2: Implement Getter Function
```cpp ```cpp
PyObject* UISprite::get_rotation(PyUISpriteObject* self, void* closure) { PyObject* UISprite::get_rotation(PyUISpriteObject* self, void* closure) {
if (!self->data) { if (!self->data) {
PyErr_SetString(PyExc_RuntimeError, "UISprite data is null"); PyErr_SetString(PyExc_RuntimeError, "UISprite data is null");
return NULL; return NULL;
} }
return PyFloat_FromDouble(self->data->rotation); return PyFloat_FromDouble(self->data->rotation);
} }
``` ```
### Step 3: Implement Setter Function ### Step 3: Implement Setter Function
```cpp ```cpp
int UISprite::set_rotation(PyUISpriteObject* self, PyObject* value, void* closure) { int UISprite::set_rotation(PyUISpriteObject* self, PyObject* value, void* closure) {
if (!self->data) { if (!self->data) {
PyErr_SetString(PyExc_RuntimeError, "UISprite data is null"); PyErr_SetString(PyExc_RuntimeError, "UISprite data is null");
return -1; return -1;
} }
if (!PyFloat_Check(value) && !PyLong_Check(value)) { if (!PyFloat_Check(value) && !PyLong_Check(value)) {
PyErr_SetString(PyExc_TypeError, "rotation must be a number"); PyErr_SetString(PyExc_TypeError, "rotation must be a number");
return -1; return -1;
} }
double rotation = PyFloat_AsDouble(value); double rotation = PyFloat_AsDouble(value);
if (rotation < 0 || rotation > 360) { if (rotation < 0 || rotation > 360) {
PyErr_SetString(PyExc_ValueError, "rotation must be 0-360"); PyErr_SetString(PyExc_ValueError, "rotation must be 0-360");
return -1; return -1;
} }
self->data->rotation = rotation; self->data->rotation = rotation;
return 0; return 0;
} }
``` ```
### Step 4: Rebuild and Test ### Step 4: Rebuild and Test
```bash ```bash
# From project root # From project root
make clean && make make clean && make
cd build cd build
./mcrogueface --headless -c " ./mcrogueface --headless -c "
import mcrfpy, sys import mcrfpy, sys
s = mcrfpy.Sprite(x=0, y=0, sprite_index=0) s = mcrfpy.Sprite(x=0, y=0, sprite_index=0)
s.rotation = 45 s.rotation = 45
assert s.rotation == 45 assert s.rotation == 45
print('PASS') print('PASS')
sys.exit(0) sys.exit(0)
" "
``` ```
--- ---
## Workflow 2: Adding a Method to Existing Class ## Workflow 2: Adding a Method to Existing Class
### Step 1: Add to PyMethodDef Array ### Step 1: Add to PyMethodDef Array
```cpp ```cpp
PyMethodDef UIGrid::methods[] = { PyMethodDef UIGrid::methods[] = {
// Existing methods... // Existing methods...
{"fill_walkable", (PyCFunction)UIGrid::fill_walkable, METH_VARARGS | METH_KEYWORDS, {"fill_walkable", (PyCFunction)UIGrid::fill_walkable, METH_VARARGS | METH_KEYWORDS,
MCRF_METHOD(Grid, fill_walkable, MCRF_METHOD(Grid, fill_walkable,
MCRF_SIG("(walkable: bool)", "None"), MCRF_SIG("(walkable: bool)", "None"),
MCRF_DESC("Set walkable property for all cells."), MCRF_DESC("Set walkable property for all cells."),
MCRF_ARGS_START MCRF_ARGS_START
MCRF_ARG("walkable", "Whether cells should be walkable") MCRF_ARG("walkable", "Whether cells should be walkable")
)}, )},
{NULL} // Sentinel {NULL} // Sentinel
}; };
``` ```
### Step 2: Implement Method ### Step 2: Implement Method
```cpp ```cpp
PyObject* UIGrid::fill_walkable(PyUIGridObject* self, PyObject* args, PyObject* kwds) { PyObject* UIGrid::fill_walkable(PyUIGridObject* self, PyObject* args, PyObject* kwds) {
if (!self->data) { if (!self->data) {
PyErr_SetString(PyExc_RuntimeError, "Grid data is null"); PyErr_SetString(PyExc_RuntimeError, "Grid data is null");
return NULL; return NULL;
} }
int walkable; int walkable;
static char* kwlist[] = {"walkable", NULL}; static char* kwlist[] = {"walkable", NULL};
if (!PyArg_ParseTupleAndKeywords(args, kwds, "p", kwlist, &walkable)) { if (!PyArg_ParseTupleAndKeywords(args, kwds, "p", kwlist, &walkable)) {
return NULL; return NULL;
} }
for (int x = 0; x < self->data->grid_x; x++) { for (int x = 0; x < self->data->grid_x; x++) {
for (int y = 0; y < self->data->grid_y; y++) { for (int y = 0; y < self->data->grid_y; y++) {
self->data->at(x, y).walkable = walkable; self->data->at(x, y).walkable = walkable;
} }
} }
Py_RETURN_NONE; Py_RETURN_NONE;
} }
``` ```
### Step 3: Test ### Step 3: Test
```python ```python
import mcrfpy import mcrfpy
import sys import sys
grid = mcrfpy.Grid(grid_size=(10, 10), pos=(0, 0), size=(160, 160)) grid = mcrfpy.Grid(grid_size=(10, 10), pos=(0, 0), size=(160, 160))
grid.fill_walkable(True) grid.fill_walkable(True)
assert grid.at(5, 5).walkable == True assert grid.at(5, 5).walkable == True
print("PASS") print("PASS")
sys.exit(0) sys.exit(0)
``` ```
--- ---
## Workflow 3: Creating New Python Type ## Workflow 3: Creating New Python Type
### Step 1: Define Type Structure ### Step 1: Define Type Structure
In new header file (e.g., `src/PyMyType.h`): In new header file (e.g., `src/PyMyType.h`):
```cpp ```cpp
typedef struct { typedef struct {
PyObject_HEAD PyObject_HEAD
std::shared_ptr<MyType> data; std::shared_ptr<MyType> data;
} PyMyTypeObject; } PyMyTypeObject;
namespace mcrfpydef { namespace mcrfpydef {
static PyTypeObject PyMyTypeType = { static PyTypeObject PyMyTypeType = {
.tp_name = "mcrfpy.MyType", .tp_name = "mcrfpy.MyType",
.tp_basicsize = sizeof(PyMyTypeObject), .tp_basicsize = sizeof(PyMyTypeObject),
// ... filled in during init // ... filled in during init
}; };
} }
class PyMyType { class PyMyType {
public: public:
static PyGetSetDef getsetters[]; static PyGetSetDef getsetters[];
static PyMethodDef methods[]; static PyMethodDef methods[];
static int init(PyMyTypeObject* self, PyObject* args, PyObject* kwds); static int init(PyMyTypeObject* self, PyObject* args, PyObject* kwds);
static PyObject* pynew(PyTypeObject* type, PyObject* args, PyObject* kwds); static PyObject* pynew(PyTypeObject* type, PyObject* args, PyObject* kwds);
static void dealloc(PyMyTypeObject* self); static void dealloc(PyMyTypeObject* self);
}; };
``` ```
### Step 2: Implement (in `src/PyMyType.cpp`) ### Step 2: Implement (in `src/PyMyType.cpp`)
```cpp ```cpp
#include "PyMyType.h" #include "PyMyType.h"
#include "McRFPy_Doc.h" #include "McRFPy_Doc.h"
int PyMyType::init(PyMyTypeObject* self, PyObject* args, PyObject* kwds) { int PyMyType::init(PyMyTypeObject* self, PyObject* args, PyObject* kwds) {
// Parse arguments, initialize self->data // Parse arguments, initialize self->data
self->data = std::make_shared<MyType>(); self->data = std::make_shared<MyType>();
return 0; return 0;
} }
PyObject* PyMyType::pynew(PyTypeObject* type, PyObject* args, PyObject* kwds) { PyObject* PyMyType::pynew(PyTypeObject* type, PyObject* args, PyObject* kwds) {
auto* self = (PyMyTypeObject*)type->tp_alloc(type, 0); auto* self = (PyMyTypeObject*)type->tp_alloc(type, 0);
if (self) self->data = nullptr; if (self) self->data = nullptr;
return (PyObject*)self; return (PyObject*)self;
} }
void PyMyType::dealloc(PyMyTypeObject* self) { void PyMyType::dealloc(PyMyTypeObject* self) {
self->data.reset(); self->data.reset();
Py_TYPE(self)->tp_free((PyObject*)self); Py_TYPE(self)->tp_free((PyObject*)self);
} }
PyGetSetDef PyMyType::getsetters[] = { PyGetSetDef PyMyType::getsetters[] = {
{"name", (getter)get_name, (setter)set_name, {"name", (getter)get_name, (setter)set_name,
MCRF_PROPERTY(name, "Object name."), NULL}, MCRF_PROPERTY(name, "Object name."), NULL},
{NULL} {NULL}
}; };
PyMethodDef PyMyType::methods[] = { PyMethodDef PyMyType::methods[] = {
{NULL} {NULL}
}; };
``` ```
### Step 3: Register in Module ### Step 3: Register in Module
In `src/McRFPy_API.cpp`: In `src/McRFPy_API.cpp`:
```cpp ```cpp
#include "PyMyType.h" #include "PyMyType.h"
// In the exported_types or internal_types array: // In the exported_types or internal_types array:
static PyTypeObject* exported_types[] = { static PyTypeObject* exported_types[] = {
// ... existing types ... // ... existing types ...
&mcrfpydef::PyMyTypeType, &mcrfpydef::PyMyTypeType,
}; };
// Before PyType_Ready calls: // Before PyType_Ready calls:
mcrfpydef::PyMyTypeType.tp_methods = PyMyType::methods; mcrfpydef::PyMyTypeType.tp_methods = PyMyType::methods;
mcrfpydef::PyMyTypeType.tp_getset = PyMyType::getsetters; mcrfpydef::PyMyTypeType.tp_getset = PyMyType::getsetters;
mcrfpydef::PyMyTypeType.tp_init = (initproc)PyMyType::init; mcrfpydef::PyMyTypeType.tp_init = (initproc)PyMyType::init;
mcrfpydef::PyMyTypeType.tp_new = PyMyType::pynew; mcrfpydef::PyMyTypeType.tp_new = PyMyType::pynew;
mcrfpydef::PyMyTypeType.tp_dealloc = (destructor)PyMyType::dealloc; mcrfpydef::PyMyTypeType.tp_dealloc = (destructor)PyMyType::dealloc;
``` ```
CMake auto-discovers new `.cpp` files via GLOB_RECURSE, so no CMakeLists.txt changes needed. CMake auto-discovers new `.cpp` files via GLOB_RECURSE, so no CMakeLists.txt changes needed.
--- ---
## Documentation Macros ## Documentation Macros
Use macros from `src/McRFPy_Doc.h` for all Python-facing documentation: Use macros from `src/McRFPy_Doc.h` for all Python-facing documentation:
| Macro | Purpose | | Macro | Purpose |
|-------|---------| |-------|---------|
| `MCRF_METHOD(cls, name, ...)` | Method docstring | | `MCRF_METHOD(cls, name, ...)` | Method docstring |
| `MCRF_PROPERTY(name, desc)` | Property docstring | | `MCRF_PROPERTY(name, desc)` | Property docstring |
| `MCRF_SIG(params, ret)` | Method signature | | `MCRF_SIG(params, ret)` | Method signature |
| `MCRF_DESC(text)` | Description paragraph | | `MCRF_DESC(text)` | Description paragraph |
| `MCRF_ARGS_START` | Begin arguments section | | `MCRF_ARGS_START` | Begin arguments section |
| `MCRF_ARG(name, desc)` | Individual argument | | `MCRF_ARG(name, desc)` | Individual argument |
| `MCRF_RETURNS(text)` | Return value description | | `MCRF_RETURNS(text)` | Return value description |
| `MCRF_RAISES(exc, cond)` | Exception documentation | | `MCRF_RAISES(exc, cond)` | Exception documentation |
| `MCRF_NOTE(text)` | Important notes | | `MCRF_NOTE(text)` | Important notes |
| `MCRF_LINK(path, text)` | External documentation link | | `MCRF_LINK(path, text)` | External documentation link |
--- ---
## Testing Your Bindings ## Testing Your Bindings
### Direct Execution Test ### Direct Execution Test
```python ```python
import mcrfpy import mcrfpy
import sys import sys
# Test property # Test property
s = mcrfpy.Sprite(x=0, y=0, sprite_index=0) s = mcrfpy.Sprite(x=0, y=0, sprite_index=0)
s.rotation = 45 s.rotation = 45
assert s.rotation == 45 assert s.rotation == 45
# Test method # Test method
grid = mcrfpy.Grid(grid_size=(10, 10), pos=(0, 0), size=(160, 160)) grid = mcrfpy.Grid(grid_size=(10, 10), pos=(0, 0), size=(160, 160))
grid.fill_walkable(True) grid.fill_walkable(True)
assert grid.at(5, 5).walkable == True assert grid.at(5, 5).walkable == True
print("PASS") print("PASS")
sys.exit(0) sys.exit(0)
``` ```
### Run ### Run
```bash ```bash
cd build cd build
./mcrogueface --headless --exec ../tests/unit/my_binding_test.py ./mcrogueface --headless --exec ../tests/unit/my_binding_test.py
``` ```
--- ---
## Regenerating Documentation ## Regenerating Documentation
After adding bindings: After adding bindings:
```bash ```bash
# From project root # From project root
make make
# Generate all docs (recommended) # Generate all docs (recommended)
./tools/generate_all_docs.sh ./tools/generate_all_docs.sh
# Or individually: # Or individually:
cd build cd build
./mcrogueface --headless --exec ../tools/generate_dynamic_docs.py ./mcrogueface --headless --exec ../tools/generate_dynamic_docs.py
./mcrogueface --headless --exec ../tools/generate_stubs_v2.py ./mcrogueface --headless --exec ../tools/generate_stubs_v2.py
``` ```
--- ---
## Common Pitfalls ## Common Pitfalls
### Pitfall 1: Forgetting NULL Sentinel ### Pitfall 1: Forgetting NULL Sentinel
```cpp ```cpp
// WRONG - missing sentinel causes crash // WRONG - missing sentinel causes crash
PyGetSetDef getsetters[] = { PyGetSetDef getsetters[] = {
{"x", get_x, set_x, "X position", NULL} {"x", get_x, set_x, "X position", NULL}
}; };
// CORRECT // CORRECT
PyGetSetDef getsetters[] = { PyGetSetDef getsetters[] = {
{"x", get_x, set_x, "X position", NULL}, {"x", get_x, set_x, "X position", NULL},
{NULL} // Must have this! {NULL} // Must have this!
}; };
``` ```
### Pitfall 2: Type Preservation in Collections ### Pitfall 2: Type Preservation in Collections
When returning from collections, use `RET_PY_INSTANCE`: When returning from collections, use `RET_PY_INSTANCE`:
```cpp ```cpp
// WRONG - returns base UIDrawable wrapper // WRONG - returns base UIDrawable wrapper
return generic_wrap(item->data); return generic_wrap(item->data);
// CORRECT - preserves derived type (Frame, Caption, etc.) // CORRECT - preserves derived type (Frame, Caption, etc.)
RET_PY_INSTANCE(item->data); RET_PY_INSTANCE(item->data);
``` ```
### Pitfall 3: Missing Error Checks ### Pitfall 3: Missing Error Checks
```cpp ```cpp
// WRONG - no type check // WRONG - no type check
double value = PyFloat_AsDouble(obj); double value = PyFloat_AsDouble(obj);
// CORRECT // CORRECT
if (!PyFloat_Check(obj) && !PyLong_Check(obj)) { if (!PyFloat_Check(obj) && !PyLong_Check(obj)) {
PyErr_SetString(PyExc_TypeError, "Expected number"); PyErr_SetString(PyExc_TypeError, "Expected number");
return NULL; return NULL;
} }
double value = PyFloat_AsDouble(obj); double value = PyFloat_AsDouble(obj);
``` ```
### Pitfall 4: Not Setting tp_methods/tp_getset Before PyType_Ready ### Pitfall 4: Not Setting tp_methods/tp_getset Before PyType_Ready
```cpp ```cpp
// WRONG - setting after PyType_Ready has no effect // WRONG - setting after PyType_Ready has no effect
PyType_Ready(&MyType); PyType_Ready(&MyType);
MyType.tp_methods = methods; MyType.tp_methods = methods;
// CORRECT - set before PyType_Ready // CORRECT - set before PyType_Ready
MyType.tp_methods = methods; MyType.tp_methods = methods;
MyType.tp_getset = getsetters; MyType.tp_getset = getsetters;
PyType_Ready(&MyType); PyType_Ready(&MyType);
``` ```
--- ---
## Related Documentation ## Related Documentation
- [[Python-Binding-Layer]] - System architecture - [[Python-Binding-Layer]] - System architecture
- [[UI-Component-Hierarchy]] - Classes exposed to Python - [[UI-Component-Hierarchy]] - Classes exposed to Python
- `src/McRFPy_Doc.h` - Documentation macro reference - `src/McRFPy_Doc.h` - Documentation macro reference
- [Python C API Reference](https://docs.python.org/3/c-api/) - [Python C API Reference](https://docs.python.org/3/c-api/)