blazeseq (Python)

Python bindings for BlazeSeq — high-performance FASTQ parsing.

Wheels only: install from PyPI. No source build of the extension.

# Install (uv recommended)
uv pip install blazeseq

# Or with pip
pip install blazeseq

Quick start

import blazeseq

# quality_schema defaults to "generic"; use keyword args for clarity
parser = blazeseq.parser("file.fastq", quality_schema="sanger")
while parser.has_more():
    rec = parser.next_record()
    print(rec.id, rec.sequence)

Or use the iterator over records:

for rec in parser.records:
    print(rec.id, rec.sequence)

For batched iteration (default 100 records per batch):

for batch in parser.batches:
    for rec in batch:
        print(rec.id, rec.sequence)

Custom batch size:

for batch in parser.batches_with_size(50):
    for rec in batch:
        print(rec.id, rec.sequence)

Gzip files: use .fastq.gz or .fq.gz and set parallelism for decompression threads (default 4):

parser = blazeseq.parser("reads.fastq.gz", quality_schema="sanger", parallelism=8)
for rec in parser.records:
    print(rec.id, rec.sequence)

API reference

Module-level

Parser (returned by parser / create_parser)

FastqRecord

FastqBatch

Local development (uv)

From the repo root, after building the Mojo extension into python/blazeseq/_extension/:

uv pip install -e python/
uv run python tests/test_python_bindings.py

Build and upload to PyPI

Prerequisites: Build the Mojo extension so that python/blazeseq/_extension/ contains the platform wheel (.so). Ensure version in pyproject.toml is bumped for releases.

1. Install build tools and twine:

   uv pip install build twine
   

2. Build the package (from the python/ directory):

   cd python
   uv run python -m build
   

   This produces dist/blazeseq-<version>.tar.gz (sdist) and dist/blazeseq-<version>-*.whl (wheel).

3. Upload to PyPI (use a PyPI API token; create one at pypi.org):

   uv run twine upload dist/*
   

   For Test PyPI first:

   uv run twine upload --repository testpypi dist/*