> ## Documentation Index
> Fetch the complete documentation index at: https://zinc.ossl.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Python Adapter

> Use Zinc from Python with numpy integration

The Python adapter uses cffi (not ctypes) for FFI bindings. It wraps numpy's `np.frombuffer` for zero-copy array views.

## Installation

```bash theme={null}
pip install zinc-shm
```

Or from source:

```bash theme={null}
cd adapters/python
pip install -e .
```

## SharedRegion

```python theme={null}
from zinc import SharedRegion
```

### create

```python theme={null}
region = SharedRegion.create("my-data", 4096)
```

Creates a new region. Raises `OSError` if the name already exists, the name is invalid, or the capacity is not page-aligned.

### open

```python theme={null}
region = SharedRegion.open("my-data")
```

Opens an existing region. Raises `OSError` if the region does not exist or the header is corrupted.

### as\_buffer

Returns a `memoryview` backed directly by the shared mmap. No copying occurs.

```python theme={null}
buf = region.as_buffer()
# buf is a memoryview, writable and sliceable
buf[:4] = struct.pack('<I', 42)
```

### as\_numpy

Returns a numpy `ndarray` backed directly by the shared memory. No copying occurs. Requires numpy to be installed.

```python theme={null}
import numpy as np

arr = region.as_numpy(dtype=np.float32)
arr[0] = 42.0  # writes directly to shared memory
```

Without a dtype argument, it defaults to `np.uint8`.

```python theme={null}
raw = region.as_numpy()  # shape: (capacity,), dtype: uint8
```

### notify

```python theme={null}
region.notify()
```

### wait

```python theme={null}
success = region.wait(timeout_ms=1000)
```

Returns `True` if notified, `False` if timed out.

### close

```python theme={null}
region.close()
```

The region is also closed when the `SharedRegion` object is garbage collected or used as a context manager:

```python theme={null}
with SharedRegion.open("my-data") as region:
    buf = region.as_buffer()
    # region is automatically closed after the block
```

## Example: numpy integration

```python theme={null}
from zinc import SharedRegion
import numpy as np
import struct

# Writer process
writer = SharedRegion.create("tensor-data", 8192)
arr = writer.as_numpy(dtype=np.float32)
arr[:] = np.linspace(0, 1, 2048, dtype=np.float32)
writer.notify()

# Reader process (separate terminal)
reader = SharedRegion.open("tensor-data")
arr = reader.as_numpy(dtype=np.float32)
print(arr[:5])  # [0. 0.00048828 0.00097656 0.00146484 0.00195312]
```

The `as_numpy` call returns a view, not a copy. Writing to the array from either process modifies the same physical memory.

## FFI details

The adapter loads `libzinc_core.{so,dylib,dll}` at import time. It reads `zinc.h` from `include/` relative to the Python package to define the FFI signatures. If the header is missing, it falls back to a hardcoded CDEF.

The library path is resolved relative to the Python package location. If the library is not found, copy it to a standard library path or set `LD_LIBRARY_PATH` / `DYLD_LIBRARY_PATH`.