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

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

Revision: 7252
          http://sourceforge.net/p/teem/code/7252
Author:   kindlmann
Date:     2025-04-14 11:08:16 +0000 (Mon, 14 Apr 2025)
Log Message:
-----------
tweaks3 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-14 10:53:14 UTC (rev 7251)
+++ teem/trunk/python/cffi/README.md	2025-04-14 11:08:16 UTC (rev 7252)
@@ -22,8 +22,6 @@
 - `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 distinct but connected steps: 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)
 - `lliibb.py` (distributed with Teem source) is the template for all the Python wrappers (around extension modules) that `exult.py` can generate, including `teem.py`. No python code will ever "`import lliibb`"; the text of this is transformed by `exult.py`'s `Tffi.wrap()` to generate things like `teem.py`. `lliibb.py` is the new home for functionality (such as the `Tenum` python wrapper for an airEnum) that started in an earlier version of `build_teem.py`. The biggest text transformation that `Tffi.wrap()` does is to inject a Python dictionary summarizing which C functions use `biff`, and how to interpret their return values as errors.
 - `build_teem.py` (distributed with Teem source, run by user): Running `python3 build_teem.py -gch $TEEM_INSTALL` does a lot of fragile hacking on the headers in `$TEEM_INSTALL/include/teem` to produce restatement of Teem library APIs in `cdef/cdef_*.h`. Without the `-gch` option, `python3 build_teem.py $TEEM_INSTALL` will (with help from class `Tffi` in `exult.py`) produce `_teem.c` and compile it to make the `_teem.cpython....so` shared object (above). Whether `$TEEM_INSTALL` includes the "experimental" Teem libraries will determine the contents of `_teem.c`, which why it is not distributed with the Teem source.
-- `biffdata/*.csv`: these are a repackaging of the `/* Biff: */` annotations of the source code in `$TEEM_SRC/src/*/*.c`, which describe what different return values from a Teem C function indicates that the function has used `biff` to describe an error. The `biffdata/*.csv` files are read in by `exult.py`'s `Tffi.wrap()` to generate a Python dictionary `_BIFF_DICT` that `teem.py` (or other wrapper) uses to generate Exceptions upon errors.
+- `biffdata/*.csv`: these are a repackaging of the `/* Biff: */` annotations of the source code in `$TEEM_SRC/src/*/*.c`, which describe what different return values from a Teem C function indicates that the function has used `biff` to describe an error. The `biffdata/*.csv` files are read in by `exult.py`'s `Tffi.wrap()` to generate a Python dictionary `_BIFF_DICT` that `teem.py` (or other wrapper) uses to generate Exceptions upon errors. The `biffdata/*.csv` files are generated by `$TEEM_SRC/src/_util/gen_biffdata.py`, which scans all the `$TEEM_SRC/src/*/*.c` source code files for "`/* Biff: */`" annotations. The "`/* Biff: */`" annotations are created in turn by `$TEEM_SRC/src/_util/scan-symbols.py`, which is re-run as needed when the API changes, and prior to releases. The format of the annotations is defined in `$TEEM_SRC/biff/README.txt`.
 
-For the curious: `$TEEM_SRC/src/_util/gen_biffdata.py` generates the `biffdata/*.csv` files by scanning the `$TEEM_SRC/src/*/*.c` source code for "`/* Biff: */`" annotations. The "`/* Biff: */`" annotations are created by `$TEEM_SRC/src/_util/scan-symbols.py`, which is run as needed when the API changes, and prior to releases. The format of the annotations is defined in `$TEEM_SRC/biff/README.txt`.
-
 Also: the motivation for centralizing (in `exult.py`) how Teem-related extension modules are compiled and wrapped comes from frustrations arising with trying to connect extensions modules that each had their own CFFI bridges to `libteem`, with error messages like `TypeError: initializer for ctype 'airEnum *' appears indeed to be 'airEnum *', but the types are different (check that you are not e.g. mixing up different ffi instances)`.

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