[Teem-commit] SF.net SVN: teem:[7250] teem/trunk/python/cffi/README .md

[<kin...@us...>]

Revision: 7250
          http://sourceforge.net/p/teem/code/7250
Author:   kindlmann
Date:     2025-04-14 10:50:44 +0000 (Mon, 14 Apr 2025)
Log Message:
-----------
tweaks as GLK revisits this and gets it working on new laptop

Modified Paths:
--------------
    teem/trunk/python/cffi/README.md

Modified: teem/trunk/python/cffi/README.md
===================================================================
--- teem/trunk/python/cffi/README.md	2025-04-06 16:10:35 UTC (rev 7249)
+++ teem/trunk/python/cffi/README.md	2025-04-14 10:50:44 UTC (rev 7250)
@@ -1,6 +1,6 @@
 # CFFI-based Python wrappers for Teem
 
-The `teem.py` in this directory is a new (as of Teem v2 in 2024? 2025?) Python wrapper for all of Teem, built via CFFI. It does useful error handling, and has one or more helper/wrappers (including a Python object "foo" wrapping of "const airEnum \*const foo").
+The `teem.py` in this directory is a new (as of Teem v2 in 2024? 2025?) Python wrapper for all of Teem, built via CFFI. It does useful error handling (automatically turning `biff` errors into Python Exceptions), and has one or more pythonic helper/wrappers (including a Python object "foo" wrapping of "const airEnum \*const foo").
 
 These notes by GLK are mostly to document for future GLK what's involved in creating teem.py, but also for anyone else who is in a position to improve how Python users can access and benefit from Teem.
 
@@ -9,14 +9,14 @@
 - The previous Python wrapping method, using [ctypes](https://docs.python.org/3/library/ctypes.html) (in `../ctypes`) is stalled because the automated generation of ctypes description of the API depended on a patched version of [gccxml](https://gccxml.github.io/HTML/Index.html), which is no longer maintained. A new [llvm-based ctypeslib](https://github.com/trolldbois/ctypeslib) is the likely basis of any future ctypes Teem wrapper.
 - The current approach uses [CFFI](https://cffi.readthedocs.io/), specifically the ["API, out-of-line" mode](https://cffi.readthedocs.io/en/latest/overview.html#other-cffi-modes), which includes a C compilation step to produce a platform-specific bridge between the Python run-time and symbols in the Teem library. This should be faster than ctypes, which CFFI would call "ABI, in-line"
 - Teem is written in C as a collection of libraries (`air`, `biff`, `hest`, `nrrd`, etc), but compiling and installing with CMake produces a single `libteem` library to link with. CFFI can call into either a static or shared library, but additional dependencies (png, zlib) currently -- for the sake of this wrapping -- require a shared library: `libteem.so` or `libteem.dylib` for Linux or Mac, respectively. Windows should be possible but hasn't been tried.
-- Teem's `biff` library is for human-readable error message accumulation. Handling an error in a Teem function like `nrrdLoad()` sometimes involves subsequent calls like `biffGetDone()` to retrieve the error message. Work on this Python wrapper has led to a new systematic way of documenting which functions use biff, and what return values indicate an error. This information is now stored in `/* Biff: */` annotations at the start of function definitions in Teem's C source code.
+- Teem's `biff` library is for human-readable error message accumulation. Handling an error in a Teem function like `nrrdLoad()` sometimes involves subsequent calls like `biffGetDone()` to retrieve the error message. Work on this Python wrapper has led to a new systematic way of documenting which functions use biff, and what return values indicate an error. This information is now stored in `/* Biff: */` annotations at the start of function definitions in Teem's C source code.  See `teem/src/biff/README.txt` for details on the syntax of these annotations.
 - The following description will use:
   - `$TEEM_INSTALL` to refer to whatever directory in which (as the result of a `make install`) CMake installed Teem, with a `lib` subdir containing `libteem{.so,.dylib}`, an `include` subdir containing all the Teem headers (`teem/air.h`, `teem/biff.h`, etc). There's also a `bin` subdir for executables but they aren't relevant for Python wrapping.
-  - `$TEEM_SRC` to refer to whatever directory has the source checkout of Teem (from this file, `../..`), with a `src` subdir for all sources, and a `python` subdir for python wrappings, and `python/cffi` containing this file.
+  - `$TEEM_SRC` to refer to whatever directory has the source checkout of Teem (from this file, `../..`), with a `src` subdir for all sources, and a `python` subdir for python wrappings, and `python/cffi` containing this file.   For example, `$TEEM_SRC/src/_util/gen_biffdata.py` is the utility that scans for and parses "Biff:" anntations in Teem's .c files (`$TEEM_SRC/src/*/*.c`) to generate `$TEEM_SRC/python/cffi/biffdata/*.csv`.
 
 The various files in this directory (`$TEEM_SRC/python/cffi`), where they come from, and their role:
 
-- `teem.py` (distributed with Teem source): enables "import teem" from python3, and provides access to the entire Teem API, with some added benefits (mainly biff errors turning into Python exceptions). `teem.py` is generated by `build_teem.py` in its final "wrap" step. At runtime,`teem.py` relies on an `import _teem` which dynamically loads and links in:
+- `teem.py` (distributed with Teem source): enables "import teem" from python3, and provides access to the entire Teem API, with some added benefits (mainly `biff` errors turning into Python exceptions). `teem.py` is generated by `build_teem.py` in its final "wrap" step. At runtime,`teem.py` relies on an `import _teem` which dynamically loads and links in:
 - `_teem.cpython-`_platformspecifics_`.so` (created by user, because it is specific to the local OS and the local version of Python): This platform-specific shared library is the bridge between Python and the symbols in `$TEEM_INSTALL/lib/libteem`. Linking regular C code with `libteem` requires declarations from the .h headers in `$TEEM_INSTALL/include/teem`, but the work of describing the Teem API to CFFI, so as to mirror it all in Python, is done by:
 - `cdef/cdef_air.h`, `cdef/cdef_biff.h`, `cdef/cdef_nrrd.h`, etc (distributed with Teem source): these are restatements of the API of each library in Teem in a form digestable to the meagre C header parser inside `cffi.FFI()`: basically removing all pre-processor logic and all `#define` macros, keeping only the `#define`s around integers (which can be parsed). Some subset of these are read by `Tffi.cdef()` in `exult.py` to tell CFFI what bridge code to generate when creating the extension module. Including these files in the Teem source (as opposed to requiring users to regenerate them) may not be wise, but they are there to be used as part of creating extension module for other non-Teem libraries.
 - `exult.py` (distributed with Teem source) is CFFI **EX**tension module **U**tilities for **L**ibraries depending on **T**eem, which arose with the recognition that knowledge of Teem's organization and contents matter for two things: compiling extension modules that depend on Teem (or are Teem), and wrapping those extension modules in Pythonic ways. `exult.py` defines a `Tffi` object is used to compile extension modules (via its `.cdef()`, `.set_source()`, and `.compile()` methods) and then generate a Python wrapper around the extension module (the `Tffi.wrap()` method). `exult.py` has become home for functionality that started in an earlier version of `teem.py` (such as knowledge of the inter-dependencies of Teem libraries)

This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.