tinycwrap 0.0.7__tar.gz → 0.1.1__tar.gz

tinycwrap-0.1.1/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: tinycwrap
+Version: 0.1.1
+Summary: Lightweight C-to-Python wrapper generator using CFFI and NumPy
+Author: TinyCWrap Contributors
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.24
+Requires-Dist: cffi>=1.15
+
+# tinycwrap
+
+TinyCWrap is a lightweight helper around CFFI that:
+
+- compiles one or more C sources into a shared library,
+- auto-generates the `cdef` from your function/struct declarations,
+- builds NumPy-friendly Python wrappers that take/return arrays and structs,
+- optionally hot-reloads when the C file changes (inside IPython).
+
+## Quick start
+
+```bash
+pip install tinycwrap
+```
+
+Write a small C file (only non-`static` functions are exported):
+
+```c
+/* kernels.c */
+double dot(const double *x, const double *y, int len_x)
+/* Return dot product between x and y
+   Contract: len_x=len(x);
+*/
+{
+    double acc = 0.0;
+    for (int i = 0; i < len_x; ++i)
+        acc += x[i] * y[i];
+    return acc;
+}
+```
+
+Wrap and call it from Python:
+
+```python
+import numpy as np
+from tinycwrap import CModule
+
+cm = CModule("kernels.c")  # builds the shared library, creates wrappers
+
+x = np.arange(5, dtype=np.float64)
+y = np.ones_like(x)
+
+cm.dot(x, y)           # -> 10.0, len_x auto-filled by the contract
+print(cm.dot.__doc__)  # docstring comes from the C comment
+```
+
+See `examples/` and `tests/` for more involved cases.
+
+## C coding conventions
+
+TinyCWrap infers how to build wrappers from simple C conventions:
+
+- **Inputs vs outputs**
+  - `const T *arg` -> input NumPy array.
+  - `T *arg` -> output/in-place array (prefer naming it `out_*` when possible).
+  - `T arg[N]` in the signature -> fixed-size array (input if `const`, otherwise output).
+  - Plain scalars (`double`, `int`, ...) -> Python scalars.
+- **Length parameters**: integers such as `len_x`, `n`, `size_x` can be auto-filled if you declare a contract (see below). Otherwise pass them explicitly from Python.
+- **Docstrings**: the block comment immediately after the function header becomes the Python docstring.
+- **Structs**: `typedef struct { ... } Name;` definitions in your headers/sources become Python classes with a `.dtype` and NumPy-backed storage.
+- **Compilation**: extra sources can be passed (`CModule("main.c", "helper.c")`), and extra include dirs via `include_dirs=[...]`. Default compiler flags are `-O3 -shared -fPIC -march=native -mtune=native` plus the NumPy include path.
+
+## Contracts: tell the wrapper how to size things
+
+Contracts are declared inside the doc comment with `Contract:` (or `Contracts:`). Separate multiple rules with semicolons. Supported forms:
+
+- `len_x=len(x)` — mark `len_x` as the length of array `x`. If you omit `len_x` in Python, the wrapper fills it.
+- `shape(out)=n,m` — allocate `out` with shape `(n, m)`. You can define `n,m=shape(a)` to capture the shape of an input first.
+- `len(out)=len_x` — allocate a 1D output array.
+- `postlen(out)=out_len` — slice the output after the call using an integer pointer result `out_len` (useful when the C code writes less than the allocated length).
+- `own(return)` — the returned pointer is owned by the caller; the wrapper will `free` it after copying to NumPy (requires a `len(return)=...` contract).
+
+Examples pulled from the test suite:
+
+```c
+void mat_add(const double *a, const double *b, int n, int m, double *out)
+/* Elementwise addition
+   Contract: n,m=shape(a); shape(out)=n,m;
+*/
+```
+
+```c
+void merge_sorted(const double *a, const double *b, int len_a, int len_b,
+                  double *out, int *out_len)
+/* Merge unique sorted values
+   Contract: len_a=len(a); len_b=len(b);
+             len(out)=len_a+len_b; postlen(out)=out_len;
+*/
+```
+
+```c
+double *alloc_random_array(int *out_len)
+/* Return a freshly malloc'ed array
+   Contract: len(return)=out_len; own(return);
+*/
+```
+
+Rules are parsed case-insensitively; whitespace does not matter.
+
+## Python wrapper behavior
+
+- **Automatic allocation**: any `out_*` argument defaults to `None` in Python; TinyCWrap allocates it based on contracts, fixed array sizes, or by matching the shape of a related input (`out_x` matches `x` when no contract is present).
+- **Struct pointer outputs**: non-const struct pointers are treated as in/out; when you pass an object/array explicitly, it is mutated in place and not returned. When you pass `None`, TinyCWrap allocates and returns the struct (or struct array).
+- **Optional length arguments**: integer length parameters inferred from contracts default to `None` in the wrapper signature. If you pass them, they are cast to `int`; if not, the expression from the contract is evaluated.
+- **Post contracts**: when a contract uses `postlen(...)` or `post shape(...)`, the wrapper slices/reshapes outputs after the C call using the values written by the C function.
+- **Scalar pointer outputs**: pointers to integer-like types (e.g., `int *out_len`) are returned as plain Python integers alongside other outputs.
+- **Structs**: for `typedef struct` declarations TinyCWrap generates a Python class:
+  - fields are accessible as properties backed by a NumPy structured dtype (`Name.dtype`);
+  - scalar struct outputs return `Name` objects;
+  - struct-array outputs return compact `NameArray` wrappers, with field arrays as properties (`points.x`), scalar items as `Name` objects (`points[0]`), and Python construction as `NameArray(array_like)` or `NameArray(x=..., y=...)`;
+  - pointer fields paired with `len_<field>` automatically allocate NumPy arrays when you instantiate the struct with `len_field` or when you pass an array for that field;
+  - `_data` holds the underlying structured array, `Name.zeros(n)` returns a raw array of that dtype, and `NameArray.zeros(n)` returns the typed wrapper.
+- **Reloading**: inside IPython, pass `reload=True` (default) to auto-recompile before each cell if the C sources changed.
+
+## Worked examples
+
+### Two outputs and automatic lengths
+
+```c
+void split_vectors(const double *inp, int len_inp,
+                   double *out_even, double *out_odd)
+/* Split even/odd elements
+   Contract: len_inp=len(inp); len(out_even)=len_inp/2; len(out_odd)=len_inp/2;
+*/
+```
+
+```python
+data = np.array([0, 1, 2, 3, 4, 5], dtype=np.float64)
+out_even, out_odd = cm.split_vectors(data)  # lengths inferred, arrays allocated
+```
+
+### Structs and struct arrays
+
+```c
+typedef struct {
+    double real;
+    double imag;
+} ComplexPair;
+
+double complex_magnitude(const ComplexPair *z);
+```
+
+```python
+cp = cm.ComplexPair(real=3.0, imag=4.0)
+cm.complex_magnitude(cp)  # -> 5.0
+
+# struct arrays are NumPy dtypes; useful when C expects pointers to arrays of structs
+pairs = cm.ComplexPair.zeros(2)
+pairs["real"] = [1.0, 2.0]
+pairs["imag"] = [0.0, -1.0]
+```
+
+### Owned return value
+
+```c
+double *alloc_random_array(int *out_len)
+/* Contract: len(return)=out_len; own(return); */
+```
+
+```python
+arr, n = cm.alloc_random_array()  # returns NumPy array, frees the C buffer
+```
+
+## Tips
+
+- Keep function declarations (or headers) visible at the top level; TinyCWrap scans the C files and headers you pass.
+- If a length cannot be inferred from a contract, you must pass it explicitly from Python.
+- Use `cm.<func>.__source__` to inspect the wrapper code if something behaves unexpectedly.
+- For debugging parsed signatures/contracts call `cm._debug_specs()`.
+
+That is all you need to start turning small C helpers into ergonomic Python callables.

tinycwrap-0.1.1/README.md

@@ -0,0 +1,171 @@
+# tinycwrap
+
+TinyCWrap is a lightweight helper around CFFI that:
+
+- compiles one or more C sources into a shared library,
+- auto-generates the `cdef` from your function/struct declarations,
+- builds NumPy-friendly Python wrappers that take/return arrays and structs,
+- optionally hot-reloads when the C file changes (inside IPython).
+
+## Quick start
+
+```bash
+pip install tinycwrap
+```
+
+Write a small C file (only non-`static` functions are exported):
+
+```c
+/* kernels.c */
+double dot(const double *x, const double *y, int len_x)
+/* Return dot product between x and y
+   Contract: len_x=len(x);
+*/
+{
+    double acc = 0.0;
+    for (int i = 0; i < len_x; ++i)
+        acc += x[i] * y[i];
+    return acc;
+}
+```
+
+Wrap and call it from Python:
+
+```python
+import numpy as np
+from tinycwrap import CModule
+
+cm = CModule("kernels.c")  # builds the shared library, creates wrappers
+
+x = np.arange(5, dtype=np.float64)
+y = np.ones_like(x)
+
+cm.dot(x, y)           # -> 10.0, len_x auto-filled by the contract
+print(cm.dot.__doc__)  # docstring comes from the C comment
+```
+
+See `examples/` and `tests/` for more involved cases.
+
+## C coding conventions
+
+TinyCWrap infers how to build wrappers from simple C conventions:
+
+- **Inputs vs outputs**
+  - `const T *arg` -> input NumPy array.
+  - `T *arg` -> output/in-place array (prefer naming it `out_*` when possible).
+  - `T arg[N]` in the signature -> fixed-size array (input if `const`, otherwise output).
+  - Plain scalars (`double`, `int`, ...) -> Python scalars.
+- **Length parameters**: integers such as `len_x`, `n`, `size_x` can be auto-filled if you declare a contract (see below). Otherwise pass them explicitly from Python.
+- **Docstrings**: the block comment immediately after the function header becomes the Python docstring.
+- **Structs**: `typedef struct { ... } Name;` definitions in your headers/sources become Python classes with a `.dtype` and NumPy-backed storage.
+- **Compilation**: extra sources can be passed (`CModule("main.c", "helper.c")`), and extra include dirs via `include_dirs=[...]`. Default compiler flags are `-O3 -shared -fPIC -march=native -mtune=native` plus the NumPy include path.
+
+## Contracts: tell the wrapper how to size things
+
+Contracts are declared inside the doc comment with `Contract:` (or `Contracts:`). Separate multiple rules with semicolons. Supported forms:
+
+- `len_x=len(x)` — mark `len_x` as the length of array `x`. If you omit `len_x` in Python, the wrapper fills it.
+- `shape(out)=n,m` — allocate `out` with shape `(n, m)`. You can define `n,m=shape(a)` to capture the shape of an input first.
+- `len(out)=len_x` — allocate a 1D output array.
+- `postlen(out)=out_len` — slice the output after the call using an integer pointer result `out_len` (useful when the C code writes less than the allocated length).
+- `own(return)` — the returned pointer is owned by the caller; the wrapper will `free` it after copying to NumPy (requires a `len(return)=...` contract).
+
+Examples pulled from the test suite:
+
+```c
+void mat_add(const double *a, const double *b, int n, int m, double *out)
+/* Elementwise addition
+   Contract: n,m=shape(a); shape(out)=n,m;
+*/
+```
+
+```c
+void merge_sorted(const double *a, const double *b, int len_a, int len_b,
+                  double *out, int *out_len)
+/* Merge unique sorted values
+   Contract: len_a=len(a); len_b=len(b);
+             len(out)=len_a+len_b; postlen(out)=out_len;
+*/
+```
+
+```c
+double *alloc_random_array(int *out_len)
+/* Return a freshly malloc'ed array
+   Contract: len(return)=out_len; own(return);
+*/
+```
+
+Rules are parsed case-insensitively; whitespace does not matter.
+
+## Python wrapper behavior
+
+- **Automatic allocation**: any `out_*` argument defaults to `None` in Python; TinyCWrap allocates it based on contracts, fixed array sizes, or by matching the shape of a related input (`out_x` matches `x` when no contract is present).
+- **Struct pointer outputs**: non-const struct pointers are treated as in/out; when you pass an object/array explicitly, it is mutated in place and not returned. When you pass `None`, TinyCWrap allocates and returns the struct (or struct array).
+- **Optional length arguments**: integer length parameters inferred from contracts default to `None` in the wrapper signature. If you pass them, they are cast to `int`; if not, the expression from the contract is evaluated.
+- **Post contracts**: when a contract uses `postlen(...)` or `post shape(...)`, the wrapper slices/reshapes outputs after the C call using the values written by the C function.
+- **Scalar pointer outputs**: pointers to integer-like types (e.g., `int *out_len`) are returned as plain Python integers alongside other outputs.
+- **Structs**: for `typedef struct` declarations TinyCWrap generates a Python class:
+  - fields are accessible as properties backed by a NumPy structured dtype (`Name.dtype`);
+  - scalar struct outputs return `Name` objects;
+  - struct-array outputs return compact `NameArray` wrappers, with field arrays as properties (`points.x`), scalar items as `Name` objects (`points[0]`), and Python construction as `NameArray(array_like)` or `NameArray(x=..., y=...)`;
+  - pointer fields paired with `len_<field>` automatically allocate NumPy arrays when you instantiate the struct with `len_field` or when you pass an array for that field;
+  - `_data` holds the underlying structured array, `Name.zeros(n)` returns a raw array of that dtype, and `NameArray.zeros(n)` returns the typed wrapper.
+- **Reloading**: inside IPython, pass `reload=True` (default) to auto-recompile before each cell if the C sources changed.
+
+## Worked examples
+
+### Two outputs and automatic lengths
+
+```c
+void split_vectors(const double *inp, int len_inp,
+                   double *out_even, double *out_odd)
+/* Split even/odd elements
+   Contract: len_inp=len(inp); len(out_even)=len_inp/2; len(out_odd)=len_inp/2;
+*/
+```
+
+```python
+data = np.array([0, 1, 2, 3, 4, 5], dtype=np.float64)
+out_even, out_odd = cm.split_vectors(data)  # lengths inferred, arrays allocated
+```
+
+### Structs and struct arrays
+
+```c
+typedef struct {
+    double real;
+    double imag;
+} ComplexPair;
+
+double complex_magnitude(const ComplexPair *z);
+```
+
+```python
+cp = cm.ComplexPair(real=3.0, imag=4.0)
+cm.complex_magnitude(cp)  # -> 5.0
+
+# struct arrays are NumPy dtypes; useful when C expects pointers to arrays of structs
+pairs = cm.ComplexPair.zeros(2)
+pairs["real"] = [1.0, 2.0]
+pairs["imag"] = [0.0, -1.0]
+```
+
+### Owned return value
+
+```c
+double *alloc_random_array(int *out_len)
+/* Contract: len(return)=out_len; own(return); */
+```
+
+```python
+arr, n = cm.alloc_random_array()  # returns NumPy array, frees the C buffer
+```
+
+## Tips
+
+- Keep function declarations (or headers) visible at the top level; TinyCWrap scans the C files and headers you pass.
+- If a length cannot be inferred from a contract, you must pass it explicitly from Python.
+- Use `cm.<func>.__source__` to inspect the wrapper code if something behaves unexpectedly.
+- For debugging parsed signatures/contracts call `cm._debug_specs()`.
+
+That is all you need to start turning small C helpers into ergonomic Python callables.

{tinycwrap-0.0.7 → tinycwrap-0.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tinycwrap"
-version = "0.0.7"
+version = "0.1.1"
 description = "Lightweight C-to-Python wrapper generator using CFFI and NumPy"
 readme = "README.md"
 requires-python = ">=3.9"

{tinycwrap-0.0.7 → tinycwrap-0.1.1}/tests/test_kernels.py

@@ -33,6 +33,20 @@ def test_scale_explicit_output(cm):
     np.testing.assert_allclose(scaled_explicit, x * 2.0)
 
 
+def test_mat_add_shape_contract(cm):
+    a = np.arange(6, dtype=np.float64).reshape(2, 3)
+    b = np.ones_like(a)
+    out = cm.mat_add(a, b)
+    assert out.shape == (2, 3)
+    np.testing.assert_allclose(out, a + b)
+
+    flat = np.zeros(a.size, dtype=np.float64)
+    reshaped = cm.mat_add(a, b, out=flat)
+    assert reshaped.shape == (2, 3)
+    np.testing.assert_allclose(reshaped, a + b)
+    np.testing.assert_allclose(flat.reshape(a.shape), a + b)
+
+
 def test_struct_wrapper(cm):
     cp = cm.ComplexPair(real=1.5, imag=-2.5)
     assert repr(cp) == "ComplexPair(real=1.5, imag=-2.5)"
@@ -52,6 +66,53 @@ def test_struct_argument(cm):
     assert np.isclose(mag_sq, 5.0)
 
 
+def test_struct_pointer_inplace_no_return(cm):
+    cp = cm.ComplexPair(real=2.0, imag=-3.0)
+    res = cm.scale_complex(cp, 2.0)
+    assert res is None
+    assert cp.real == 4.0
+    assert cp.imag == -6.0
+
+
+def test_struct_scalar_output_returns_struct_object(cm):
+    a = cm.ComplexPair(real=2.0, imag=4.0)
+    b = cm.ComplexPair(real=6.0, imag=10.0)
+    mid = cm.midpoint_complex(a, b)
+    assert isinstance(mid, cm.ComplexPair)
+    assert mid.real == 4.0
+    assert mid.imag == 7.0
+
+    out = cm.ComplexPair()
+    res = cm.midpoint_complex(a, b, out_z=out)
+    assert res is None
+    assert out.real == 4.0
+    assert out.imag == 7.0
+
+
+def test_struct_array_output_returns_array_wrapper(cm):
+    pairs = cm.make_complex_pairs()
+    assert isinstance(pairs, cm.ComplexPairArray)
+    assert repr(pairs) == "<Array ComplexPair[3]>"
+    assert pairs.shape == (3,)
+    np.testing.assert_allclose(pairs.real, np.array([0.0, 1.0, 2.0]))
+    np.testing.assert_allclose(pairs.imag, np.array([0.0, -1.0, -2.0]))
+    np.testing.assert_allclose(pairs["real"], pairs.real)
+    assert isinstance(pairs[1], cm.ComplexPair)
+    assert pairs[1].real == 1.0
+    assert pairs[1].imag == -1.0
+
+
+def test_struct_array_initialization(cm):
+    from_array_like = cm.ComplexPairArray([(1.0, 2.0), (3.0, 4.0)])
+    assert isinstance(from_array_like[0], cm.ComplexPair)
+    np.testing.assert_allclose(from_array_like.real, [1.0, 3.0])
+    np.testing.assert_allclose(from_array_like.imag, [2.0, 4.0])
+
+    from_fields = cm.ComplexPairArray(real=[5.0, 6.0], imag=-1.0)
+    np.testing.assert_allclose(from_fields.real, [5.0, 6.0])
+    np.testing.assert_allclose(from_fields.imag, [-1.0, -1.0])
+
+
 def test_struct_array_member(cm):
     p = cm.Particle()
     p.pos = [1.0, 2.0, 3.0]
@@ -98,7 +159,14 @@ def test_owned_array(cm):
 def test_struct_output_array(cm):
     n = 4
     particles = cm.Particle.zeros(n)
-    out_particles = cm.make_particles(3.0, out_p=particles, len_p=n)
-    np.testing.assert_array_equal(out_particles, particles)
+    res = cm.make_particles(3.0, out_p=particles, len_p=n)
+    assert res is None
     np.testing.assert_allclose(particles["pos"], np.ones((n, 3)))
     np.testing.assert_allclose(particles["vel"], np.array([[3.0, 0.0, 0.0]] * n))
+
+
+def test_struct_output_array_auto_return(cm):
+    n = 3
+    particles = cm.make_particles(2.5, len_p=n)
+    np.testing.assert_allclose(particles["pos"], np.ones((n, 3)))
+    np.testing.assert_allclose(particles["vel"], np.array([[2.5, 0.0, 0.0]] * n))

{tinycwrap-0.0.7 → tinycwrap-0.1.1}/tinycwrap/__init__.py

@@ -6,6 +6,6 @@ from .cmodule import CModule
 try:
     __version__ = version("tinycwrap")
 except PackageNotFoundError:
-    __version__ = "0.0.7"
+    __version__ = "0.1.1"
 
 __all__ = ["CModule", "__version__"]

{tinycwrap-0.0.7 → tinycwrap-0.1.1}/tinycwrap/cmodule.py

@@ -97,6 +97,7 @@ class CModule:
         self._struct_specs: dict[str, StructSpec] = {}
         self._struct_dtypes: dict[str, np.dtype] = {}
         self._struct_classes: dict[str, type] = {}
+        self._struct_array_classes: dict[str, type] = {}
         self._ipython_hook = None
         self._cdef: str | None = None
 
@@ -187,10 +188,18 @@ class CModule:
                         delattr(self, sname)
                     except Exception:
                         pass
+            for sname in list(self._struct_array_classes.keys()):
+                aname = f"{sname}Array"
+                if hasattr(self, aname):
+                    try:
+                        delattr(self, aname)
+                    except Exception:
+                        pass
             self._func_specs.clear()
             self._struct_specs.clear()
             self._struct_dtypes.clear()
             self._struct_classes.clear()
+            self._struct_array_classes.clear()
             self._ffi = None
             self._lib = None
             self._so_path = None
@@ -439,29 +448,71 @@ class CModule:
             fspec.doc = doc
             contracts = []
             owns: list[str] = []
+
+            def _normalize_shape_expr(expr: str) -> str:
+                expr = expr.strip()
+                if "," in expr and not expr.startswith("("):
+                    expr = f"({expr})"
+                return expr
+
+            contract_items: list[str] = []
             for line in doc.splitlines():
-                m_contract = re.search(r"(post-)?contract:\s*(.*)", line, flags=re.IGNORECASE)
-                if not m_contract:
-                    m_own = re.search(r"own:\s*(.*)", line, flags=re.IGNORECASE)
-                    if m_own:
-                        for name in m_own.group(1).split(","):
-                            n = name.strip()
-                            if n:
-                                owns.append(n)
+                m_contract = re.search(r"contracts?\s*:\s*(.*)", line, flags=re.IGNORECASE)
+                if m_contract:
+                    after = m_contract.group(1)
+                    for part in after.split(";"):
+                        part = part.strip()
+                        if part:
+                            contract_items.append(part)
                     continue
-                is_post = m_contract.group(1) is not None
-                after = m_contract.group(2)
-                for part in after.split(";"):
-                    part = part.strip()
-                    if not part:
-                        continue
-                    mlen = re.match(r"len\((\w+)\)\s*=\s*(.+)", part)
-                    if not mlen:
-                        mlen = re.match(r"(\w+)\s*=\s*(.+)", part)
-                    if mlen:
-                        target = mlen.group(1)
-                        expr = mlen.group(2).strip()
-                        contracts.append((target, expr, is_post))
+                m_own = re.search(r"own:\s*(.*)", line, flags=re.IGNORECASE)
+                if m_own:
+                    for name in m_own.group(1).split(","):
+                        n = name.strip()
+                        if n:
+                            owns.append(n)
+
+            for item in contract_items:
+                entry = item.strip()
+                if not entry:
+                    continue
+                m_own_call = re.match(r"own\s*\(\s*([^)]+)\s*\)\s*$", entry, flags=re.IGNORECASE)
+                if m_own_call:
+                    for name in m_own_call.group(1).split(","):
+                        n = name.strip()
+                        if n:
+                            owns.append(n)
+                    continue
+                is_post = False
+                m_post = re.match(r"post\s*(.+)", entry, flags=re.IGNORECASE)
+                if m_post and (m_post.group(1).strip().lower().startswith("len(") or m_post.group(1).strip().lower().startswith("shape(")):
+                    is_post = True
+                    entry = m_post.group(1).strip()
+                mshape_out = re.match(r"shape\((\w+)\)\s*=\s*(.+)", entry, flags=re.IGNORECASE)
+                if mshape_out:
+                    target = f"shape({mshape_out.group(1)})"
+                    expr = _normalize_shape_expr(mshape_out.group(2))
+                    contracts.append((target, expr, is_post))
+                    continue
+                mshape_in = re.match(r"(.+?)\s*=\s*shape\((\w+)\)", entry, flags=re.IGNORECASE)
+                if mshape_in:
+                    targets_raw = mshape_in.group(1)
+                    arr_name = mshape_in.group(2)
+                    targets = [t.strip() for t in targets_raw.split(",") if t.strip()]
+                    for idx, tgt in enumerate(targets):
+                        contracts.append((tgt, f"shape({arr_name})[{idx}]", is_post))
+                    continue
+                mlen = re.match(r"len\((\w+)\)\s*=\s*(.+)", entry, flags=re.IGNORECASE)
+                if mlen:
+                    target = mlen.group(1)
+                    expr = mlen.group(2).strip()
+                    contracts.append((target, expr, is_post))
+                    continue
+                mgeneric = re.match(r"(\w+)\s*=\s*(.+)", entry)
+                if mgeneric:
+                    target = mgeneric.group(1)
+                    expr = mgeneric.group(2).strip()
+                    contracts.append((target, expr, is_post))
             fspec.contracts = contracts or None
             fspec.owns = owns or None
 
@@ -633,10 +684,23 @@ class CModule:
                     parts = ", ".join(parts_list)
                     return f"{spec.name}({parts})"
 
+                @classmethod
+                def _from_data(cls, data, copy=False):
+                    arr = np.asarray(data, dtype=dtype)
+                    if arr.shape != ():
+                        raise ValueError(f"{spec.name} expects scalar data, got shape {arr.shape}")
+                    if copy:
+                        arr = np.array(arr, dtype=dtype, copy=True)
+                    obj = cls()
+                    object.__setattr__(obj, "_data", arr)
+                    object.__setattr__(obj, "_children", {})
+                    return obj
+
                 namespace = {
                     "__slots__": slots,
                     "__init__": __init__,
                     "__repr__": __repr__,
+                    "_from_data": _from_data,
                     "__doc__": f"Python wrapper for C struct {spec.name}. Fields: {', '.join(dtype.names)}.",
                     "dtype": dtype,
                     "zeros": staticmethod(
@@ -679,10 +743,147 @@ class CModule:
 
                 return type(spec.name, (), namespace)
 
+            def make_struct_array_class(spec, dtype, struct_cls):
+                slots = ("_data",)
+                class_name = f"{spec.name}Array"
+
+                def __init__(self, data=None, copy=False, **kwargs):
+                    if data is not None and kwargs:
+                        raise TypeError(f"{class_name} accepts either data or field values, not both")
+                    if kwargs:
+                        unknown = sorted(set(kwargs) - set(dtype.names))
+                        if unknown:
+                            names = ", ".join(unknown)
+                            raise TypeError(f"{class_name} got unknown field(s): {names}")
+                        field_values = {}
+                        lengths = []
+                        for fname, value in kwargs.items():
+                            field_dtype = dtype.fields[fname][0]
+                            if field_dtype.shape == ():
+                                value_arr = np.asarray(value, dtype=field_dtype)
+                                if value_arr.shape != ():
+                                    lengths.append(value_arr.shape[0])
+                            else:
+                                value_arr = np.asarray(value, dtype=field_dtype.base)
+                                if value_arr.shape == field_dtype.shape:
+                                    pass
+                                elif value_arr.shape[1:] == field_dtype.shape:
+                                    lengths.append(value_arr.shape[0])
+                                else:
+                                    raise ValueError(
+                                        f"Field {fname} expects shape {field_dtype.shape} or "
+                                        f"(n, {', '.join(str(s) for s in field_dtype.shape)}), "
+                                        f"got {value_arr.shape}"
+                                    )
+                            field_values[fname] = value_arr
+                        if lengths and len(set(lengths)) != 1:
+                            raise ValueError(f"{class_name} field values have inconsistent lengths: {lengths}")
+                        n = lengths[0] if lengths else 1
+                        arr = np.zeros(n, dtype=dtype)
+                        for fname, value_arr in field_values.items():
+                            arr[fname] = value_arr
+                    elif data is None:
+                        arr = np.zeros(0, dtype=dtype)
+                    elif hasattr(data, "_data") and getattr(data, "_data", None) is not None:
+                        arr = np.asarray(data._data, dtype=dtype)
+                    elif isinstance(data, (list, tuple)) and data and hasattr(data[0], "_data"):
+                        arr = np.asarray([item._data for item in data], dtype=dtype)
+                    else:
+                        arr = np.asarray(data, dtype=dtype)
+                    if arr.shape == ():
+                        arr = arr.reshape(1)
+                    if copy:
+                        arr = np.array(arr, dtype=dtype, copy=True)
+                    object.__setattr__(self, "_data", arr)
+
+                @classmethod
+                def _from_data(cls, data, copy=False):
+                    return cls(data, copy=copy)
+
+                @staticmethod
+                def zeros(n):
+                    return array_cls(np.zeros(n, dtype=dtype))
+
+                def __len__(self):
+                    return len(self._data)
+
+                def __iter__(self):
+                    for idx in range(len(self)):
+                        yield self[idx]
+
+                def __array__(self, dtype=None, copy=None):
+                    arr = np.asarray(self._data, dtype=dtype)
+                    if copy:
+                        arr = np.array(arr, copy=True)
+                    return arr
+
+                def __getitem__(self, key):
+                    if isinstance(key, str):
+                        return self._data[key]
+                    if isinstance(key, (int, np.integer)):
+                        idx = int(key)
+                        if idx < 0:
+                            idx += len(self._data)
+                        return struct_cls._from_data(self._data[idx:idx + 1].reshape(()))
+                    value = self._data[key]
+                    if getattr(value, "dtype", None) == dtype:
+                        if getattr(value, "shape", ()) == ():
+                            return struct_cls._from_data(value)
+                        return array_cls(value)
+                    return value
+
+                def __setitem__(self, key, value):
+                    if hasattr(value, "_data") and getattr(value, "_data", None) is not None:
+                        self._data[key] = value._data
+                    else:
+                        self._data[key] = value
+
+                def __repr__(self):
+                    return f"<Array {spec.name}[{len(self)}]>"
+
+                namespace = {
+                    "__slots__": slots,
+                    "__init__": __init__,
+                    "__repr__": __repr__,
+                    "__len__": __len__,
+                    "__iter__": __iter__,
+                    "__array__": __array__,
+                    "__getitem__": __getitem__,
+                    "__setitem__": __setitem__,
+                    "_from_data": _from_data,
+                    "zeros": zeros,
+                    "dtype": dtype,
+                    "__doc__": f"Python wrapper for arrays of C struct {spec.name}.",
+                    "array": property(lambda self: self._data),
+                    "shape": property(lambda self: self._data.shape),
+                    "ndim": property(lambda self: self._data.ndim),
+                    "size": property(lambda self: self._data.size),
+                    "ctypes": property(lambda self: self._data.ctypes),
+                }
+
+                for fname in dtype.names:
+                    namespace[fname] = property(lambda self, fname=fname: self._data[fname])
+
+                array_cls = type(class_name, (), namespace)
+                return array_cls
+
             struct_cls = make_struct_class(sspec, dtype)
+            struct_array_cls = make_struct_array_class(sspec, dtype, struct_cls)
             self._struct_dtypes[sname] = dtype
             self._struct_classes[sname] = struct_cls
+            self._struct_array_classes[sname] = struct_array_cls
             setattr(self, sname, struct_cls)
+            setattr(self, f"{sname}Array", struct_array_cls)
+
+    def _wrap_struct_output(self, value, struct_name: str):
+        struct_cls = self._struct_classes[struct_name]
+        struct_array_cls = self._struct_array_classes[struct_name]
+        if isinstance(value, (struct_cls, struct_array_cls)):
+            return value
+        arr = np.asarray(value, dtype=self._struct_dtypes[struct_name])
+        if arr.shape == ():
+            return struct_cls._from_data(arr)
+        return struct_array_cls._from_data(arr)
 
     def _make_wrapper_from_spec(self, fspec: FuncSpec):
         struct_names = set(self._struct_specs.keys())
@@ -709,6 +910,7 @@ class CModule:
             "base_type_from_ctype": base_type_from_ctype,
             "_struct_classes": self._struct_classes,
             "_struct_dtypes": self._struct_dtypes,
+            "_struct_array_classes": self._struct_array_classes,
         }
         filename = f"<cmodule:{self._c_path.name}:{fspec.name}>"
         linecache.cache[filename] = (
@@ -813,8 +1015,18 @@ class CModule:
 
         contract_map: dict[str, str] = {}
         post_contract_map: dict[str, str] = {}
+        shape_contract_map: dict[str, str] = {}
+        post_shape_contract_map: dict[str, str] = {}
         if getattr(fspec, "contracts", None):
             for target, expr, is_post in fspec.contracts:
+                is_shape = target.startswith("shape(") and target.endswith(")")
+                if is_shape:
+                    arr_name = target[len("shape(") : -1]
+                    if is_post:
+                        post_shape_contract_map[arr_name] = expr
+                    else:
+                        shape_contract_map[arr_name] = expr
+                    continue
                 if is_post:
                     post_contract_map[target] = expr
                 else:
@@ -848,6 +1060,7 @@ class CModule:
         def _expr_py(expr: str) -> str:
             expr = expr.strip()
             expr = re.sub(r"len\((\w+)\)", r"len(arr_\1)", expr)
+            expr = re.sub(r"shape\((\w+)\)", r"np.shape(arr_\1)", expr)
             for name in pointer_scalar_names:
                 expr = re.sub(rf"\b{name}\b", f"int(arr_{name}.ravel()[0])", expr)
                 expr = re.sub(rf"\b{name}\b", f"scalar_{name}", expr)
@@ -870,6 +1083,8 @@ class CModule:
         call_args: list[str] = []
         output_vars: list[str] = []
         output_names: list[str] = []
+        output_conditions: dict[str, str] = {}
+        struct_output_types: dict[str, str] = {}
         pointer_scalar_outputs: list[tuple[str, str]] = []
         struct_scalar_outputs: list[tuple[str, str, str]] = []
         pre_lines: list[str] = []
@@ -952,20 +1167,34 @@ class CModule:
                 else:
                     dtype_expr = f"np.dtype('{np.dtype(numpy_dtype_for_base_type(a.base_type)).name}')"
                 ref_name = a.name[4:] if a.name.lower().startswith("out_") else None
+                shape_expr = shape_contract_map.get(a.name)
+                len_expr = contract_map.get(a.name)
                 out_lines += [
                     f"    base_dtype = {dtype_expr}",
+                ]
+                if a.base_type in struct_names:
+                    out_lines += [
+                        f"    _ret_{a.name} = {a.name} is None",
+                    ]
+                out_lines += [
                     f"    if {a.name} is None:",
                 ]
                 if a.array_len is not None:
                     out_lines += [
                         f"        arr_{a.name} = np.zeros({int(a.array_len)}, dtype=base_dtype)"
                     ]
-                elif a.name in contract_map:
-                    expr_py = _expr_py(contract_map[a.name])
+                elif shape_expr is not None:
+                    expr_py = _expr_py(shape_expr)
+                    out_lines += [
+                        f"        _shape_{a.name} = tuple({expr_py})",
+                        f"        arr_{a.name} = np.zeros(_shape_{a.name}, dtype=base_dtype)",
+                    ]
+                elif len_expr is not None:
+                    expr_py = _expr_py(len_expr)
                     out_lines += [
                         f"        arr_{a.name} = np.zeros(int({expr_py}), dtype=base_dtype)"
                     ]
-                elif a.array_len is None and a.name not in contract_map:
+                elif a.array_len is None and len_expr is None and shape_expr is None:
                     out_lines += [
                         f"        arr_{a.name} = np.zeros((), dtype=base_dtype)"
                     ]
@@ -983,11 +1212,33 @@ class CModule:
                     ]
                 out_lines += [
                     "    else:",
-                    f"        arr_{a.name} = np.ascontiguousarray({a.name}, dtype=base_dtype)",
+                ]
+                if a.base_type in struct_names:
+                    out_lines += [
+                        f"        if hasattr({a.name}, '_data') and getattr({a.name}, '_data', None) is not None and getattr({a.name}, '_data').dtype == base_dtype:",
+                        f"            arr_{a.name} = {a.name}._data",
+                        "        else:",
+                        f"            arr_{a.name} = np.ascontiguousarray({a.name}, dtype=base_dtype)",
+                    ]
+                else:
+                    out_lines += [
+                        f"        arr_{a.name} = np.ascontiguousarray({a.name}, dtype=base_dtype)",
+                    ]
+                if shape_expr is not None:
+                    expr_py = _expr_py(shape_expr)
+                    out_lines += [
+                        f"        _expected_shape_{a.name} = tuple({expr_py})",
+                        f"        if arr_{a.name}.shape != _expected_shape_{a.name}:",
+                        f"            arr_{a.name} = np.reshape(arr_{a.name}, _expected_shape_{a.name})",
+                    ]
+                out_lines += [
                     f"    ptr_{a.name} = _self._ffi.cast('{a.base_type} *', _self._ffi.from_buffer(arr_{a.name}))",
                 ]
                 arg_call_args[idx] = f"ptr_{a.name}"
                 output_names.append(a.name)
+                if a.base_type in struct_names:
+                    output_conditions[a.name] = f"_ret_{a.name}"
+                    struct_output_types[a.name] = a.base_type
                 if a.name in pointer_scalar_names:
                     pointer_scalar_outputs.append((a.name, f"arr_{a.name}"))
                 else:
@@ -1014,6 +1265,7 @@ class CModule:
                     ]
                 else:
                     out_lines += [
+                        f"    _ret_{a.name} = {a.name} is None",
                         f"    if {a.name} is None:",
                         f"        obj_{a.name} = _struct_classes['{a.base_type}']()",
                         f"        arr_{a.name} = obj_{a.name}._data",
@@ -1026,6 +1278,7 @@ class CModule:
                         f"    ptr_{a.name} = _self._ffi.cast('{a.base_type} *', _self._ffi.from_buffer(arr_{a.name}))",
                     ]
                     output_names.append(a.name)
+                    output_conditions[a.name] = f"_ret_{a.name}"
                     output_vars.append(f"obj_{a.name} if obj_{a.name} is not None else arr_{a.name}")
                 arg_call_args[idx] = f"ptr_{a.name}"
             elif a.is_scalar and not a.is_length_param and arg_call_args[idx] is None:
@@ -1061,6 +1314,7 @@ class CModule:
         pairs_sorted = sorted(pairs, key=lambda p: 1 if p[1] in pointer_scalar_map else 0)
         output_names_reordered: list[str] = []
         output_vars_final: list[str] = []
+        output_conditions_final: list[str | None] = []
         for name, ov in pairs_sorted:
             output_names_reordered.append(name)
             if ov in struct_scalar_map:
@@ -1070,11 +1324,32 @@ class CModule:
                 output_vars_final.append(pointer_scalar_map[ov][1])
             else:
                 output_vars_final.append(ov)
+            output_conditions_final.append(output_conditions.get(name))
 
         own_return_len_expr = None
         if own_return and contract_map.get("return"):
             own_return_len_expr = _expr_py(contract_map["return"])
 
+        output_value_exprs = list(output_vars_final)
+        if output_value_exprs:
+            scalar_names = {n for n, _ in pointer_scalar_outputs}
+            for idx, (out_name, out_var) in enumerate(
+                zip(output_names_reordered, output_value_exprs)
+            ):
+                if out_name in post_contract_map:
+                    expr_py = _expr_py(post_contract_map[out_name])
+                    if out_name in scalar_names:
+                        expr_py = expr_py.replace(out_name, f"scalar_{out_name}")
+                    output_value_exprs[idx] = f"({out_var})[:int({expr_py})]"
+                elif out_name in post_shape_contract_map:
+                    expr_py = _expr_py(post_shape_contract_map[out_name])
+                    output_value_exprs[idx] = f"np.reshape({out_var}, tuple({expr_py}))"
+                if out_name in struct_output_types:
+                    output_value_exprs[idx] = (
+                        f"_self._wrap_struct_output({output_value_exprs[idx]}, "
+                        f"'{struct_output_types[out_name]}')"
+                    )
+
         if own_return:
             base_ret = base_type_from_ctype(fspec.return_ctype)
             ret_dtype_expr = f"np.dtype('{np.dtype(numpy_dtype_for_base_type(base_ret)).name}')"
@@ -1105,77 +1380,60 @@ class CModule:
                 lines.append(
                     f"    arr_ret = np.frombuffer(_self._ffi.buffer(res_buf, int({own_return_len_expr}) * np.dtype({ret_dtype_expr}).itemsize), dtype={ret_dtype_expr})"
                 )
-            ret_parts: list[str] = ["arr_ret"]
-            if output_vars_final:
-                for v in output_vars_final:
-                    if v not in ret_parts:
-                        ret_parts.append(v)
-            # append any scalar lengths not already in ret_parts
+            lines.append("    _ret_vals = []")
+            lines.append("    _ret_names = set()")
+            if output_value_exprs:
+                for out_name, ov, cond in zip(
+                    output_names_reordered, output_value_exprs, output_conditions_final
+                ):
+                    if cond:
+                        lines.append(f"    if {cond}:")
+                        lines.append(f"        _ret_vals.append({ov})")
+                        lines.append(f"        _ret_names.add('{out_name}')")
+                    else:
+                        lines.append(f"    _ret_vals.append({ov})")
+                        lines.append(f"    _ret_names.add('{out_name}')")
+            lines.append("    ret_parts = [arr_ret]")
+            lines.append("    if _ret_vals:")
+            lines.append("        ret_parts.extend(_ret_vals)")
             for name, _arr in pointer_scalar_outputs:
-                sval = f"scalar_{name}"
-                if sval not in ret_parts:
-                    ret_parts.append(sval)
-            if len(ret_parts) == 1:
-                ret_expr = ret_parts[0]
-            else:
-                ret_expr = "(" + ", ".join(ret_parts) + ")"
-            lines.append(f"    return {ret_expr}")
+                lines.append(f"    if '{name}' not in _ret_names:")
+                lines.append(f"        ret_parts.append(scalar_{name})")
+                lines.append(f"        _ret_names.add('{name}')")
+            lines.append("    if len(ret_parts) == 1:")
+            lines.append("        return ret_parts[0]")
+            lines.append("    return tuple(ret_parts)")
             return "\n".join(lines)
 
-        if output_vars_final:
-            if ret_type == "void":
-                if len(output_vars_final) == 1:
-                    ret_expr = output_vars_final[0]
-                else:
-                    ret_expr = "(" + ", ".join(output_vars_final) + ")"
-            else:
-                if len(output_vars_final) == 1:
-                    ret_expr = f"{output_vars_final[0]}, res"
-                else:
-                    ret_expr = "(" + ", ".join(output_vars_final) + "), res"
-            # apply post-contract slicing using scalar lengths if available
-            for out_name, out_var in zip(output_names_reordered, output_vars_final):
-                if out_name in post_contract_map:
-                    expr_py = _expr_py(post_contract_map[out_name])
-                    scalar_names = {n for n, _ in pointer_scalar_outputs}
-                    if out_name in scalar_names:
-                        expr_py = expr_py.replace(out_name, f"scalar_{out_name}")
-                    ret_expr = ret_expr.replace(out_var, f"({out_var})[:int({expr_py})]")
-            if pointer_scalar_outputs:
-                scalars = [
-                    f"scalar_{n}"
-                    for n, _ in pointer_scalar_outputs
-                    if f"scalar_{n}" not in output_vars_final
-                ]
-                if isinstance(ret_expr, str) and ret_expr.startswith("("):
-                    ret_expr = (
-                        ret_expr[:-1]
-                        + (", " if len(scalars) else "")
-                        + ", ".join(scalars)
-                        + ")"
-                    )
+        lines.append("    _ret_vals = []")
+        lines.append("    _ret_names = set()")
+        if output_value_exprs:
+            for out_name, ov, cond in zip(
+                output_names_reordered, output_value_exprs, output_conditions_final
+            ):
+                if cond:
+                    lines.append(f"    if {cond}:")
+                    lines.append(f"        _ret_vals.append({ov})")
+                    lines.append(f"        _ret_names.add('{out_name}')")
                 else:
-                    if len(scalars) == 1:
-                        ret_expr = (
-                            "(" + ret_expr + ", " + scalars[0] + ")"
-                            if ret_expr
-                            else scalars[0]
-                        )
-                    else:
-                        ret_expr = "(" + ret_expr + ", " + ", ".join(scalars) + ")"
-            lines.append(f"    return {ret_expr}")
+                    lines.append(f"    _ret_vals.append({ov})")
+                    lines.append(f"    _ret_names.add('{out_name}')")
+        for name, _arr in pointer_scalar_outputs:
+            lines.append(f"    if '{name}' not in _ret_names:")
+            lines.append(f"        _ret_vals.append(scalar_{name})")
+            lines.append(f"        _ret_names.add('{name}')")
+        if ret_type == "void":
+            lines.append("    if _ret_vals:")
+            lines.append("        if len(_ret_vals) == 1:")
+            lines.append("            return _ret_vals[0]")
+            lines.append("        return tuple(_ret_vals)")
+            lines.append("    return None")
         else:
-            if ret_type == "void":
-                lines.append("    return None")
-            else:
-                ret_expr = "res"
-                if pointer_scalar_outputs:
-                    scalars = [f"scalar_{n}" for n, _ in pointer_scalar_outputs]
-                    if len(scalars) == 1:
-                        ret_expr = f"({ret_expr}, {scalars[0]})"
-                    else:
-                        ret_expr = f"({ret_expr}, " + ", ".join(scalars) + ")"
-                lines.append(f"    return {ret_expr}")
+            lines.append("    if _ret_vals:")
+            lines.append("        if len(_ret_vals) == 1:")
+            lines.append("            return _ret_vals[0], res")
+            lines.append("        return tuple(_ret_vals), res")
+            lines.append("    return res")
 
         return "\n".join(lines)
 

{tinycwrap-0.0.7 → tinycwrap-0.1.1}/tinycwrap/parsing.py

@@ -240,7 +240,8 @@ def _parse_functions_regex(cdef: str) -> dict[str, FuncSpec]:
             decls.append(decl)
             buff = []
 
-    func_re = re.compile(r"(.+?)\s+(\w+)\s*\((.*?)\)\s*;")
+    # allow pointer-return functions where the * may be glued to the name
+    func_re = re.compile(r"(.+?)\s+(\*?\w+)\s*\((.*?)\)\s*;")
 
     funcs: dict[str, FuncSpec] = {}
     for decl in decls:
@@ -249,6 +250,12 @@ def _parse_functions_regex(cdef: str) -> dict[str, FuncSpec]:
             continue
         ret_ctype, fname, arglist = m.groups()
         ret_ctype = ret_ctype.strip()
+        fname = fname.strip()
+        # handle prototypes like `double *fn(...)` where `*` attaches to the name
+        if fname.startswith("*"):
+            star_count = len(fname) - len(fname.lstrip("*"))
+            fname = fname.lstrip("*")
+            ret_ctype = f"{ret_ctype} {'*' * star_count}".strip()
         arglist = arglist.strip()
 
         argspecs: list[ArgSpec] = []
@@ -305,6 +312,9 @@ def _parse_structs_regex(cdef: str) -> dict[str, StructSpec]:
         name = m.group("name")
         fields: list[StructField] = []
         body_clean = re.sub(r"\bstruct\b", "", body)
+        # Strip C++-style comments before splitting fields so inline comments
+        # don't swallow subsequent declarations (e.g., "double x; // comment\n double y;").
+        body_clean = re.sub(r"//.*?$", "", body_clean, flags=re.MULTILINE)
         for line in body_clean.split(";"):
             line = line.strip()
             if not line:

tinycwrap-0.1.1/tinycwrap.egg-info/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: tinycwrap
+Version: 0.1.1
+Summary: Lightweight C-to-Python wrapper generator using CFFI and NumPy
+Author: TinyCWrap Contributors
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.24
+Requires-Dist: cffi>=1.15
+
+# tinycwrap
+
+TinyCWrap is a lightweight helper around CFFI that:
+
+- compiles one or more C sources into a shared library,
+- auto-generates the `cdef` from your function/struct declarations,
+- builds NumPy-friendly Python wrappers that take/return arrays and structs,
+- optionally hot-reloads when the C file changes (inside IPython).
+
+## Quick start
+
+```bash
+pip install tinycwrap
+```
+
+Write a small C file (only non-`static` functions are exported):
+
+```c
+/* kernels.c */
+double dot(const double *x, const double *y, int len_x)
+/* Return dot product between x and y
+   Contract: len_x=len(x);
+*/
+{
+    double acc = 0.0;
+    for (int i = 0; i < len_x; ++i)
+        acc += x[i] * y[i];
+    return acc;
+}
+```
+
+Wrap and call it from Python:
+
+```python
+import numpy as np
+from tinycwrap import CModule
+
+cm = CModule("kernels.c")  # builds the shared library, creates wrappers
+
+x = np.arange(5, dtype=np.float64)
+y = np.ones_like(x)
+
+cm.dot(x, y)           # -> 10.0, len_x auto-filled by the contract
+print(cm.dot.__doc__)  # docstring comes from the C comment
+```
+
+See `examples/` and `tests/` for more involved cases.
+
+## C coding conventions
+
+TinyCWrap infers how to build wrappers from simple C conventions:
+
+- **Inputs vs outputs**
+  - `const T *arg` -> input NumPy array.
+  - `T *arg` -> output/in-place array (prefer naming it `out_*` when possible).
+  - `T arg[N]` in the signature -> fixed-size array (input if `const`, otherwise output).
+  - Plain scalars (`double`, `int`, ...) -> Python scalars.
+- **Length parameters**: integers such as `len_x`, `n`, `size_x` can be auto-filled if you declare a contract (see below). Otherwise pass them explicitly from Python.
+- **Docstrings**: the block comment immediately after the function header becomes the Python docstring.
+- **Structs**: `typedef struct { ... } Name;` definitions in your headers/sources become Python classes with a `.dtype` and NumPy-backed storage.
+- **Compilation**: extra sources can be passed (`CModule("main.c", "helper.c")`), and extra include dirs via `include_dirs=[...]`. Default compiler flags are `-O3 -shared -fPIC -march=native -mtune=native` plus the NumPy include path.
+
+## Contracts: tell the wrapper how to size things
+
+Contracts are declared inside the doc comment with `Contract:` (or `Contracts:`). Separate multiple rules with semicolons. Supported forms:
+
+- `len_x=len(x)` — mark `len_x` as the length of array `x`. If you omit `len_x` in Python, the wrapper fills it.
+- `shape(out)=n,m` — allocate `out` with shape `(n, m)`. You can define `n,m=shape(a)` to capture the shape of an input first.
+- `len(out)=len_x` — allocate a 1D output array.
+- `postlen(out)=out_len` — slice the output after the call using an integer pointer result `out_len` (useful when the C code writes less than the allocated length).
+- `own(return)` — the returned pointer is owned by the caller; the wrapper will `free` it after copying to NumPy (requires a `len(return)=...` contract).
+
+Examples pulled from the test suite:
+
+```c
+void mat_add(const double *a, const double *b, int n, int m, double *out)
+/* Elementwise addition
+   Contract: n,m=shape(a); shape(out)=n,m;
+*/
+```
+
+```c
+void merge_sorted(const double *a, const double *b, int len_a, int len_b,
+                  double *out, int *out_len)
+/* Merge unique sorted values
+   Contract: len_a=len(a); len_b=len(b);
+             len(out)=len_a+len_b; postlen(out)=out_len;
+*/
+```
+
+```c
+double *alloc_random_array(int *out_len)
+/* Return a freshly malloc'ed array
+   Contract: len(return)=out_len; own(return);
+*/
+```
+
+Rules are parsed case-insensitively; whitespace does not matter.
+
+## Python wrapper behavior
+
+- **Automatic allocation**: any `out_*` argument defaults to `None` in Python; TinyCWrap allocates it based on contracts, fixed array sizes, or by matching the shape of a related input (`out_x` matches `x` when no contract is present).
+- **Struct pointer outputs**: non-const struct pointers are treated as in/out; when you pass an object/array explicitly, it is mutated in place and not returned. When you pass `None`, TinyCWrap allocates and returns the struct (or struct array).
+- **Optional length arguments**: integer length parameters inferred from contracts default to `None` in the wrapper signature. If you pass them, they are cast to `int`; if not, the expression from the contract is evaluated.
+- **Post contracts**: when a contract uses `postlen(...)` or `post shape(...)`, the wrapper slices/reshapes outputs after the C call using the values written by the C function.
+- **Scalar pointer outputs**: pointers to integer-like types (e.g., `int *out_len`) are returned as plain Python integers alongside other outputs.
+- **Structs**: for `typedef struct` declarations TinyCWrap generates a Python class:
+  - fields are accessible as properties backed by a NumPy structured dtype (`Name.dtype`);
+  - scalar struct outputs return `Name` objects;
+  - struct-array outputs return compact `NameArray` wrappers, with field arrays as properties (`points.x`), scalar items as `Name` objects (`points[0]`), and Python construction as `NameArray(array_like)` or `NameArray(x=..., y=...)`;
+  - pointer fields paired with `len_<field>` automatically allocate NumPy arrays when you instantiate the struct with `len_field` or when you pass an array for that field;
+  - `_data` holds the underlying structured array, `Name.zeros(n)` returns a raw array of that dtype, and `NameArray.zeros(n)` returns the typed wrapper.
+- **Reloading**: inside IPython, pass `reload=True` (default) to auto-recompile before each cell if the C sources changed.
+
+## Worked examples
+
+### Two outputs and automatic lengths
+
+```c
+void split_vectors(const double *inp, int len_inp,
+                   double *out_even, double *out_odd)
+/* Split even/odd elements
+   Contract: len_inp=len(inp); len(out_even)=len_inp/2; len(out_odd)=len_inp/2;
+*/
+```
+
+```python
+data = np.array([0, 1, 2, 3, 4, 5], dtype=np.float64)
+out_even, out_odd = cm.split_vectors(data)  # lengths inferred, arrays allocated
+```
+
+### Structs and struct arrays
+
+```c
+typedef struct {
+    double real;
+    double imag;
+} ComplexPair;
+
+double complex_magnitude(const ComplexPair *z);
+```
+
+```python
+cp = cm.ComplexPair(real=3.0, imag=4.0)
+cm.complex_magnitude(cp)  # -> 5.0
+
+# struct arrays are NumPy dtypes; useful when C expects pointers to arrays of structs
+pairs = cm.ComplexPair.zeros(2)
+pairs["real"] = [1.0, 2.0]
+pairs["imag"] = [0.0, -1.0]
+```
+
+### Owned return value
+
+```c
+double *alloc_random_array(int *out_len)
+/* Contract: len(return)=out_len; own(return); */
+```
+
+```python
+arr, n = cm.alloc_random_array()  # returns NumPy array, frees the C buffer
+```
+
+## Tips
+
+- Keep function declarations (or headers) visible at the top level; TinyCWrap scans the C files and headers you pass.
+- If a length cannot be inferred from a contract, you must pass it explicitly from Python.
+- Use `cm.<func>.__source__` to inspect the wrapper code if something behaves unexpectedly.
+- For debugging parsed signatures/contracts call `cm._debug_specs()`.
+
+That is all you need to start turning small C helpers into ergonomic Python callables.

tinycwrap-0.0.7/PKG-INFO

@@ -1,13 +0,0 @@
-Metadata-Version: 2.4
-Name: tinycwrap
-Version: 0.0.7
-Summary: Lightweight C-to-Python wrapper generator using CFFI and NumPy
-Author: TinyCWrap Contributors
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-Requires-Dist: numpy>=1.24
-Requires-Dist: cffi>=1.15
-
-# tinycwrap
-
-TinyCWrap provides a small helper (`CModule`) to compile C sources with CFFI, auto-generate `cdef`s, and expose NumPy-friendly Python wrappers.

tinycwrap-0.0.7/README.md

@@ -1,3 +0,0 @@
-# tinycwrap
-
-TinyCWrap provides a small helper (`CModule`) to compile C sources with CFFI, auto-generate `cdef`s, and expose NumPy-friendly Python wrappers.

tinycwrap-0.0.7/tinycwrap.egg-info/PKG-INFO

@@ -1,13 +0,0 @@
-Metadata-Version: 2.4
-Name: tinycwrap
-Version: 0.0.7
-Summary: Lightweight C-to-Python wrapper generator using CFFI and NumPy
-Author: TinyCWrap Contributors
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-Requires-Dist: numpy>=1.24
-Requires-Dist: cffi>=1.15
-
-# tinycwrap
-
-TinyCWrap provides a small helper (`CModule`) to compile C sources with CFFI, auto-generate `cdef`s, and expose NumPy-friendly Python wrappers.