Metadata-Version: 2.4
Name: pyisyntax-fastio
Version: 0.2.0a1
Summary: Experimental pyisyntax fork with positional I/O and bounded codeblock prefetching
Author-email: Aiden Nibali <dismaldenizen@gmail.com>
Maintainer: Kuan Ting Wu
License-Expression: MIT
Project-URL: Homepage, https://github.com/chaosbeagle/pyisyntax-fastio
Project-URL: Source, https://github.com/chaosbeagle/pyisyntax-fastio
Project-URL: Download, https://github.com/chaosbeagle/pyisyntax-fastio/releases
Project-URL: Tracker, https://github.com/chaosbeagle/pyisyntax-fastio/issues
Project-URL: Release notes, https://github.com/chaosbeagle/pyisyntax-fastio/blob/master/CHANGELOG.md
Project-URL: Upstream, https://github.com/anibali/pyisyntax
Project-URL: Native upstream, https://github.com/amspath/libisyntax
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
License-File: isyntax_build/vendor/libisyntax/LICENSE.txt
Requires-Dist: cffi>=1.12
Requires-Dist: numpy
Dynamic: license-file

# pyisyntax-fastio

> [!IMPORTANT]
> This is an experimental, unofficial fork of
> [pyisyntax](https://github.com/anibali/pyisyntax). It preserves the public
> `from isyntax import ISyntax` API while evaluating positional I/O and bounded
> codeblock prefetching. The 64 KiB coalescing policy is enabled in this alpha
> but has not been accepted as a stable-release default; true OS-cold HDD
> validation is still pending.

A Python library for working with pathology images in the iSyntax file format,
powered by [libisyntax](https://github.com/amspath/libisyntax).

## Installation

Pre-release wheels are distributed through the
[GitHub Releases page](https://github.com/chaosbeagle/pyisyntax-fastio/releases).
Download the file matching your operating system and architecture, then run:

```console
$ python -m pip install ./pyisyntax_fastio-0.2.0a1-<platform>.whl
```

The Windows x86-64, Linux x86-64, and macOS Intel/Apple Silicon wheels use the
CPython Stable ABI (`cp310-abi3`) and require Python 3.10 or newer. CI tests
cover CPython 3.10, 3.11, and 3.12.

Alternatively, install from a checked-out source tree with its submodule
initialized:

```console
$ git submodule update --init --recursive
$ python -m pip install .
```

This fork has not been published to PyPI. The existing
`pip install pyisyntax` command installs the upstream project, not this
experimental fork.

## Usage

Read and display a region of the WSI via
[Pillow](https://pillow.readthedocs.io/).

```python
from isyntax import ISyntax
import PIL.Image

with ISyntax.open("my_file.isyntax") as isyntax:
    # Read pixels from the specified region into a numpy array
    pixels = isyntax.read_region(500, 500, 400, 200, level=4)
    # Convert numpy array into a PIL image
    pil_image = PIL.Image.fromarray(pixels)
    # Show the image
    pil_image.show()
```

Extract and save the associated macro image.

```python
from isyntax import ISyntax

with ISyntax.open("my_file.isyntax") as isyntax:
    # The macro image will be returned as compressed JPEG data.
    jpeg_data = isyntax.read_macro_image_jpeg()
    # This JPEG data can be written directly to a file.
    with open("macro_image.jpg", "wb") as f:
        f.write(jpeg_data)
    # Alternatively, you could decompress the data using Pillow:
    # pil_image = PIL.Image.open(io.BytesIO(jpeg_data), formats=["JPEG"])
```

### I/O backends

`ISyntax.open(path)` uses a native positional file source. Seekable Python
file-like objects remain supported through `ISyntax(stream, n_bytes)` and use
one atomic `read_at` callback per physical request. Both paths share the same
decoder and strict short-read handling.

Tile reads plan missing codeblocks before decoding, read them in file-offset
order, and merge only ranges separated by at most 64 KiB. A merged range is
also capped at 1 MiB, limiting over-read and temporary memory use. These are
private implementation details; the public NumPy/RGBA API is unchanged.

### Threading safety

Pixel reads must currently run on the same Python thread that first opens an
iSyntax slide. The vendored libisyntax initializes temporary-memory state only
for that caller thread; calling `read_tile()` or `read_region()` from another
Python thread can otherwise crash the process. pyisyntax temporarily rejects
such calls with `RuntimeError` until the native library provides safe
per-caller-thread initialization. Opening and reading a slide inside one worker
thread is supported as long as that worker is also the first thread to
initialize libisyntax in the process.

## Provenance and licensing

This fork retains the upstream pyisyntax history and MIT license. Its modified
native backend is based on libisyntax and retains the BSD-2-Clause license.
See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for attribution and source
links. This project is not an official release of either upstream project.

## Development

### Dependency management

To set up a development environment from the lock file:

1. Ensure that you have [uv](https://docs.astral.sh/uv/) installed.
2. Create the virtual environment:
   ```console
   $ uv sync --frozen
   ```

To modify pyisyntax project dependencies:

1. Edit dependencies in `pyproject.toml`.
2. Update the lock file using uv:
   ```console
   $ uv lock
   ```
