nanofastq 0.0.1__tar.gz

nanofastq-0.0.1/.gitignore

@@ -0,0 +1,8 @@
+uv.lock
+.venv/
+build/
+*.so
+__pycache__/
+wheelhouse/
+dist/
+benchmarks/data/

nanofastq-0.0.1/.pre-commit-config.yaml

@@ -0,0 +1,35 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v6.0.0
+  hooks:
+  - id: trailing-whitespace
+  - id: end-of-file-fixer
+  - id: check-yaml
+  - id: check-added-large-files
+
+- repo: https://github.com/python-jsonschema/check-jsonschema
+  rev: 0.38.2
+  hooks:
+  - id: check-github-workflows
+  - id: check-renovate
+    language: python
+    additional_dependencies:
+    - pyjson5==2.0.1
+
+- repo: https://github.com/tox-dev/pyproject-fmt
+  rev: "v2.30.3"
+  hooks:
+  - id: pyproject-fmt
+
+- repo: https://github.com/zizmorcore/zizmor-pre-commit
+  rev: v1.31.1
+  hooks:
+  - id: zizmor
+    args: ["--persona=pedantic"]
+
+- repo: https://github.com/hukkin/mdformat
+  rev: 1.0.0
+  hooks:
+  - id: mdformat

nanofastq-0.0.1/AGENTS.md

@@ -0,0 +1,28 @@
+# AGENTS.md
+
+nanofastq is a FASTQ reader written in C (nanoarrow + zlib), wrapped with nanobind, that exposes the Arrow PyCapsule stream interface (`__arrow_c_stream__`).
+
+## Layout
+
+- `src/fastq.c`, `src/fastq.h`: the parser, which builds Arrow record batches.
+- `src/module.cc`: the nanobind wrapper (`open_stream`).
+- `src/nanofastq/`: the Python API. `_core.pyi` is a hand-written stub for the compiled module.
+- `tests/`: pytest. `benchmarks/`: CodSpeed benchmarks (`test_perf.py`) and a biobear comparison (see its README).
+
+## Commands
+
+- Test: `uv run pytest`. Every supported Python plus the type check: `tox p`.
+- Type check: `tox -e type` (mypy and ty; nothing to compile).
+- Lint and format: `pre-commit run -a`.
+- Benchmarks: `uv run pytest benchmarks/test_perf.py --codspeed` (only checks they run; the numbers come from CI).
+
+## Gotchas
+
+- Keep `_core.pyi` in sync with `module.cc`; nothing checks it.
+- The version comes from git tags (setuptools-scm). Don't set it in `pyproject.toml`; any job that builds the package needs `fetch-depth: 0`.
+- The parser validates a whole record (structure, lengths, UTF-8) before appending it, so a bad record never leaves a half-built row. Keep it that way.
+- Output must stay identical to biobear's (`benchmarks/check.py`).
+- Workflow actions are pinned by SHA with a `# vX.Y.Z` comment, and runner images are pinned too; Renovate updates both. zizmor (pedantic) runs in pre-commit.
+- PR titles use Conventional Commits (`feat:`, `fix:`, `ci:`, `chore(deps):`, ...). `.github/semantic.yml` enforces this, and Release Drafter derives labels, sections and version bumps from them.
+- Never name a branch `renovate`: it collides with the Renovate app's `renovate/*` branches.
+- CodSpeed can flag a roughly 12% "regression" on untouched code when the run landed on different hardware. Re-run before chasing it.

nanofastq-0.0.1/CMakeLists.txt

@@ -0,0 +1,45 @@
+cmake_minimum_required(VERSION 3.28)
+project(nanofastq LANGUAGES C CXX)
+
+set(CMAKE_C_STANDARD 11)
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+
+find_package(Python 3.12 COMPONENTS Interpreter Development.Module Development.SABIModule REQUIRED)
+find_package(ZLIB QUIET)
+if(NOT ZLIB_FOUND)
+  # No system zlib (e.g. Windows): build a static copy.
+  include(FetchContent)
+  FetchContent_Declare(
+    zlib
+    URL https://github.com/madler/zlib/releases/download/v1.3.2/zlib-1.3.2.tar.gz
+    DOWNLOAD_EXTRACT_TIMESTAMP TRUE
+    EXCLUDE_FROM_ALL)
+  set(ZLIB_BUILD_TESTING OFF CACHE BOOL "" FORCE)
+  set(ZLIB_BUILD_SHARED OFF CACHE BOOL "" FORCE)
+  set(ZLIB_INSTALL OFF CACHE BOOL "" FORCE)
+  FetchContent_MakeAvailable(zlib)
+  add_library(ZLIB::ZLIB ALIAS zlibstatic)
+endif()
+
+execute_process(
+  COMMAND "${Python_EXECUTABLE}" -m nanobind --cmake_dir
+  OUTPUT_STRIP_TRAILING_WHITESPACE OUTPUT_VARIABLE nanobind_ROOT)
+find_package(nanobind CONFIG REQUIRED)
+
+include(FetchContent)
+FetchContent_Declare(
+  nanoarrow
+  URL https://github.com/apache/arrow-nanoarrow/archive/refs/tags/apache-arrow-nanoarrow-0.9.0.tar.gz
+  DOWNLOAD_EXTRACT_TIMESTAMP TRUE
+  EXCLUDE_FROM_ALL)  # keep nanoarrow's headers/libs out of the wheel
+set(NANOARROW_NAMESPACE "NanoFastq")
+FetchContent_MakeAvailable(nanoarrow)
+
+add_library(fastq_core STATIC src/fastq.c)
+target_include_directories(fastq_core PUBLIC src)
+target_link_libraries(fastq_core PUBLIC nanoarrow::nanoarrow ZLIB::ZLIB)
+
+nanobind_add_module(_core STABLE_ABI src/module.cc)
+target_link_libraries(_core PRIVATE fastq_core)
+install(TARGETS _core LIBRARY DESTINATION .)

nanofastq-0.0.1/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.2
+Name: nanofastq
+Version: 0.0.1
+Summary: Tiny, dependency-free FASTQ reader that exposes the Arrow PyCapsule stream interface.
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# nanofastq
+
+[![CodSpeed](https://img.shields.io/endpoint?url=https://codspeed.io/badge.json)](https://codspeed.io/edgarrmondragon/nanofastq)
+[![Python Versions](https://img.shields.io/pypi/pyversions/nanofastq.svg?logo=python&logoColor=FFE873)](https://pypi.org/project/nanofastq/)
+
+Tiny [FASTQ] reader (C + nanoarrow) exposing `__arrow_c_stream__`.
+
+```python
+import pyarrow as pa
+from nanofastq import read_fastq
+
+table = pa.table(read_fastq("reads.fastq.gz"))
+```
+
+## Development
+
+Run the tests and the type check with [ty] (requires [Tox]):
+
+```
+tox p
+```
+
+Performance is tracked with [CodSpeed]. Running the benchmarks locally only checks that they
+work; the reported numbers come from CI:
+
+```
+uv run pytest benchmarks/test_perf.py --codspeed
+```
+
+## Releasing
+
+The version is derived from git tags with [setuptools-scm]; there is no version to edit in
+`pyproject.toml`. [Release Drafter] keeps a draft GitHub release up to date from merged pull
+requests (their labels pick the section and the next version). To release, review the draft and
+publish it: that creates the `vX.Y.Z` tag, builds the wheels and uploads them to PyPI (see
+`.github/workflows/wheels.yml`). Untagged commits get development versions such as
+`0.1.dev12+gabc1234`.
+
+[codspeed]: https://codspeed.io
+[fastq]: https://en.wikipedia.org/wiki/FASTQ_format
+[release drafter]: https://github.com/release-drafter/release-drafter
+[setuptools-scm]: https://setuptools-scm.readthedocs.io
+[tox]: https://tox.wiki
+[ty]: https://docs.astral.sh/ty/

nanofastq-0.0.1/README.md

@@ -0,0 +1,44 @@
+# nanofastq
+
+[![CodSpeed](https://img.shields.io/endpoint?url=https://codspeed.io/badge.json)](https://codspeed.io/edgarrmondragon/nanofastq)
+[![Python Versions](https://img.shields.io/pypi/pyversions/nanofastq.svg?logo=python&logoColor=FFE873)](https://pypi.org/project/nanofastq/)
+
+Tiny [FASTQ] reader (C + nanoarrow) exposing `__arrow_c_stream__`.
+
+```python
+import pyarrow as pa
+from nanofastq import read_fastq
+
+table = pa.table(read_fastq("reads.fastq.gz"))
+```
+
+## Development
+
+Run the tests and the type check with [ty] (requires [Tox]):
+
+```
+tox p
+```
+
+Performance is tracked with [CodSpeed]. Running the benchmarks locally only checks that they
+work; the reported numbers come from CI:
+
+```
+uv run pytest benchmarks/test_perf.py --codspeed
+```
+
+## Releasing
+
+The version is derived from git tags with [setuptools-scm]; there is no version to edit in
+`pyproject.toml`. [Release Drafter] keeps a draft GitHub release up to date from merged pull
+requests (their labels pick the section and the next version). To release, review the draft and
+publish it: that creates the `vX.Y.Z` tag, builds the wheels and uploads them to PyPI (see
+`.github/workflows/wheels.yml`). Untagged commits get development versions such as
+`0.1.dev12+gabc1234`.
+
+[codspeed]: https://codspeed.io
+[fastq]: https://en.wikipedia.org/wiki/FASTQ_format
+[release drafter]: https://github.com/release-drafter/release-drafter
+[setuptools-scm]: https://setuptools-scm.readthedocs.io
+[tox]: https://tox.wiki
+[ty]: https://docs.astral.sh/ty/

nanofastq-0.0.1/benchmarks/README.md

@@ -0,0 +1,31 @@
+# Benchmarks
+
+Compares `nanofastq` with [biobear](https://github.com/wheretrue/biobear) on real
+Illumina FASTQ files from ENA. Each measurement runs in a fresh process (imports are
+excluded from the timer); the first run of each case is a warm-up and the table shows the
+median of the rest.
+
+```console
+$ uv venv --python 3.13 && uv pip install biobear pyarrow ..
+$ python fetch_data.py data            # ~220 MB download, ~1.2 GB on disk
+$ python check.py data/SRR1770413_1.fastq.gz   # both readers return identical columns
+$ python bench.py data 5
+```
+
+`inflate-only` / `read-only` are floors: just decompressing (system zlib) or reading the
+bytes, with no parsing.
+
+## Results
+
+Apple M3 Pro, Python 3.13, biobear 0.23.7, pyarrow 26.0, warm file cache. Median wall time
+to build a full Arrow table:
+
+| File | nanofastq | biobear | Floor |
+|---|---|---|---|
+| SRR1770413 `.gz` (643k × ~120 bp) | 0.45 s | 1.22 s | 0.37 s |
+| SRR1770413 plain | 0.14 s | 0.47 s | 0.02 s |
+| SRR390728 `.gz` (7.2M × 36 bp) | 0.82 s | 2.29 s | 0.30 s |
+| SRR390728 plain | 0.60 s | 1.99 s | 0.04 s |
+
+Streaming batch by batch gives the same ratios. Neither reader used more than one core.
+One machine and two files: treat the ratios as indicative, not general.

nanofastq-0.0.1/benchmarks/bench.py

@@ -0,0 +1,43 @@
+"""Compare nanofastq with biobear, each run in a fresh process.
+
+Usage: python bench.py DATA_DIR [RUNS]   (needs biobear: see README)
+"""
+
+import json
+import statistics as st
+import subprocess
+import sys
+from pathlib import Path
+
+data = Path(sys.argv[1])
+runs = int(sys.argv[2]) if len(sys.argv) > 2 else 5
+run_one = Path(__file__).with_name("run_one.py")
+
+IMPLS = ["nanofastq", "biobear", "nanofastq-stream", "biobear-stream"]
+CASES = [
+    ("SRR1770413_1.fastq.gz", ["inflate-only", *IMPLS]),
+    ("SRR1770413_1.fastq", ["read-only", *IMPLS]),
+    ("SRR390728_1.fastq.gz", ["inflate-only", *IMPLS]),
+    ("SRR390728_1.fastq", ["read-only", *IMPLS]),
+]
+
+for name, impls in CASES:
+    for impl in impls:
+        res = []
+        for _ in range(runs + 1):  # first run is a warm-up (page cache)
+            p = subprocess.run(
+                [sys.executable, "-I", str(run_one), impl, str(data / name)],
+                capture_output=True,
+                text=True,
+                check=True,
+            )
+            res.append(json.loads(p.stdout.splitlines()[-1]))
+        res = res[1:]
+        print(
+            f"{name:22} {impl:16} "
+            f"med={st.median(r['wall'] for r in res):6.2f}s "
+            f"min={min(r['wall'] for r in res):6.2f}s "
+            f"cpu={st.median(r['cpu'] for r in res):6.2f}s "
+            f"rss={max(r['rss_mb'] for r in res):6.0f}MB",
+            flush=True,
+        )

nanofastq-0.0.1/benchmarks/check.py

@@ -0,0 +1,20 @@
+import sys
+import biobear as bb
+import pyarrow as pa
+import nanofastq
+
+path = sys.argv[1]
+mine = pa.table(nanofastq.read_fastq(path))
+theirs = bb.connect().read_fastq_file(path).to_arrow()
+print("rows:", mine.num_rows, theirs.num_rows)
+print("nanofastq schema:", mine.schema.to_string().replace("\n", "; "))
+print("biobear   schema:", theirs.schema.to_string().replace("\n", "; "))
+for col in mine.column_names:
+    a = mine[col].combine_chunks().cast(pa.large_string())
+    b = theirs[col].combine_chunks().cast(pa.large_string())
+    print(f"  {col}: equal={a.equals(b)}")
+    if not a.equals(b):
+        for i in range(len(a)):
+            if a[i].as_py() != b[i].as_py():
+                print("   first diff at", i, repr(a[i].as_py())[:80], "|", repr(b[i].as_py())[:80])
+                break

nanofastq-0.0.1/benchmarks/fetch_data.py

@@ -0,0 +1,31 @@
+"""Download the benchmark FASTQ files from ENA and write plain copies next to them.
+
+Usage: python fetch_data.py [DATA_DIR]   (default: ./data)
+"""
+
+import gzip
+import shutil
+import sys
+import urllib.request
+from pathlib import Path
+
+BASE = "https://ftp.sra.ebi.ac.uk/vol1/fastq"
+FILES = [
+    # 643k reads of ~120 bp (119 MB gzipped)
+    f"{BASE}/SRR177/003/SRR1770413/SRR1770413_1.fastq.gz",
+    # 7.2M reads of 36 bp (101 MB gzipped)
+    f"{BASE}/SRR390/SRR390728/SRR390728_1.fastq.gz",
+]
+
+data = Path(sys.argv[1] if len(sys.argv) > 1 else "data")
+data.mkdir(parents=True, exist_ok=True)
+for url in FILES:
+    gz = data / url.rsplit("/", 1)[1]
+    if not gz.exists():
+        print("downloading", url)
+        urllib.request.urlretrieve(url, gz)  # noqa: S310
+    plain = gz.with_suffix("")
+    if not plain.exists():
+        print("decompressing", gz.name)
+        with gzip.open(gz, "rb") as src, plain.open("wb") as dst:
+            shutil.copyfileobj(src, dst)

nanofastq-0.0.1/benchmarks/run_one.py

@@ -0,0 +1,56 @@
+"""Run one implementation once in this process; print a JSON line.
+
+Imports happen before the timer starts and are reported separately.
+"""
+import json
+import resource
+import sys
+import time
+import zlib
+
+impl, path = sys.argv[1], sys.argv[2]
+
+t_imp = time.perf_counter()
+if impl.startswith("nanofastq"):
+    import pyarrow as pa
+    import nanofastq
+elif impl.startswith("biobear"):
+    import biobear as bb
+    import pyarrow as pa
+t_imp = time.perf_counter() - t_imp
+
+
+def run():
+    if impl == "nanofastq":
+        return pa.table(nanofastq.read_fastq(path)).num_rows
+    if impl == "nanofastq-stream":
+        r = pa.RecordBatchReader.from_stream(nanofastq.read_fastq(path))
+        return sum(len(b) for b in r)
+    if impl == "biobear":
+        return bb.connect().read_fastq_file(path).to_arrow().num_rows
+    if impl == "biobear-stream":
+        r = bb.connect().read_fastq_file(path).to_arrow_record_batch_reader()
+        return sum(len(b) for b in r)
+    if impl == "inflate-only":  # floor: just decompress (system zlib), no parsing
+        n = 0
+        d = zlib.decompressobj(31)
+        with open(path, "rb") as f:
+            while chunk := f.read(1 << 20):
+                n += len(d.decompress(chunk))
+        return n
+    if impl == "read-only":  # floor for uncompressed: just read the bytes
+        n = 0
+        with open(path, "rb") as f:
+            while chunk := f.read(1 << 20):
+                n += len(chunk)
+        return n
+    raise SystemExit(f"unknown impl {impl}")
+
+
+ru0 = resource.getrusage(resource.RUSAGE_SELF)
+t0 = time.perf_counter()
+out = run()
+wall = time.perf_counter() - t0
+ru1 = resource.getrusage(resource.RUSAGE_SELF)
+cpu = (ru1.ru_utime - ru0.ru_utime) + (ru1.ru_stime - ru0.ru_stime)
+print(json.dumps({"impl": impl, "wall": wall, "cpu": cpu, "rss_mb": ru1.ru_maxrss / 1e6, "imp": t_imp, "out": out}))

nanofastq-0.0.1/benchmarks/test_perf.py

@@ -0,0 +1,64 @@
+"""CodSpeed benchmarks: small, deterministic inputs (the simulator is slow, and counts must
+be stable between runs). Run with `pytest benchmarks/test_perf.py --codspeed`.
+"""
+
+import gzip
+import random
+
+import pyarrow as pa
+import pytest
+
+from nanofastq import read_fastq
+
+QUALS = "".join(chr(33 + q) for q in range(41))
+
+
+def make_fastq(n_reads: int, read_len: int, *, utf8_headers: bool = False) -> bytes:
+    rng = random.Random(0)  # fixed seed: identical bytes on every run
+    out = []
+    for i in range(n_reads):
+        seq = "".join(rng.choices("ACGT", k=read_len))
+        qual = "".join(rng.choices(QUALS, k=read_len))
+        name = f"réad{i}" if utf8_headers else f"read{i}"
+        out.append(f"@{name} lane=1 sample=a\n{seq}\n+\n{qual}\n")
+    return "".join(out).encode()
+
+
+# name -> (reads, read length, non-ASCII headers, gzip)
+CASES = {
+    "short-plain": (20_000, 36, False, False),
+    "short-gz": (20_000, 36, False, True),
+    "long-plain": (200, 10_000, False, False),
+    "long-gz": (200, 10_000, False, True),
+    "short-utf8-headers": (20_000, 36, True, False),  # exercises the strict UTF-8 fallback
+}
+
+
+@pytest.fixture(scope="session")
+def files(tmp_path_factory):
+    d = tmp_path_factory.mktemp("fastq")
+    paths = {}
+    for name, (n, length, utf8, gz) in CASES.items():
+        data = make_fastq(n, length, utf8_headers=utf8)
+        p = d / (f"{name}.fastq.gz" if gz else f"{name}.fastq")
+        p.write_bytes(gzip.compress(data, 1, mtime=0) if gz else data)
+        paths[name] = p
+    return paths
+
+
+@pytest.mark.parametrize("case", CASES)
+def test_read_table(benchmark, files, case):
+    path = files[case]
+    n_reads = CASES[case][0]
+    assert benchmark(lambda: pa.table(read_fastq(path)).num_rows) == n_reads
+
+
+def test_stream_small_batches(benchmark, files):
+    """Per-batch overhead: many small batches instead of a few large ones."""
+    path = files["short-plain"]
+
+    def run():
+        reader = pa.RecordBatchReader.from_stream(read_fastq(path, batch_size=512))
+        return sum(len(b) for b in reader)
+
+    assert benchmark(run) == CASES["short-plain"][0]

nanofastq-0.0.1/pyproject.toml

@@ -0,0 +1,95 @@
+[build-system]
+build-backend = "scikit_build_core.build"
+requires = [
+  "nanobind>=2",
+  "scikit-build-core>=0.10",
+]
+
+[project]
+name = "nanofastq"
+description = "Tiny, dependency-free FASTQ reader that exposes the Arrow PyCapsule stream interface."
+readme = "README.md"
+requires-python = ">=3.12"
+classifiers = [
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: 3.15",
+]
+dynamic = [ "version" ]
+dependencies = []
+
+[dependency-groups]
+dev = [
+  "duckdb",
+  "mypy",
+  "polars",
+  "pyarrow",
+  "pyarrow-stubs>=20.0.0.20260819",
+  "pytest",
+  "pytest-codspeed>=5.0.4",
+  "ty",
+]
+
+# Version comes from the latest git tag (e.g. v0.1.0); see "Releasing" in the README.
+[tool.setuptools_scm]
+
+[tool.scikit-build]
+[tool.scikit-build.cmake]
+build-type = "Release"
+version = ">=3.28"
+[tool.scikit-build.sdist]
+exclude = [ ".github" ]
+[tool.scikit-build.wheel]
+install-dir = "nanofastq"
+py-api = "cp312"
+packages = [ "src/nanofastq" ]
+[tool.scikit-build.metadata.version]
+provider = "scikit_build_core.metadata.setuptools_scm"
+
+[tool.uv]
+cache-keys = [
+  { git = { commit = true, tags = true } },
+  { file = "pyproject.toml" },
+  { file = "CMakeLists.txt" },
+  { file = "src/**/*.{c,h,cc}" },
+]
+
+[tool.cibuildwheel]
+# One abi3 wheel (cp312-abi3) per platform covers every supported Python.
+build = "cp312-*"
+skip = "*-win32 *_i686"
+test-command = "pytest {project}/tests"
+test-requires = [ "pytest", "pyarrow", "polars", "duckdb" ]
+[[tool.cibuildwheel.overrides]]
+# pyarrow has no musllinux wheels, so only smoke-test the import there.
+select = "*-musllinux*"
+test-command = "python -c 'import nanofastq'"
+test-requires = []
+
+[tool.pyproject-fmt]
+table_format = "long"
+
+[tool.pytest]
+minversion = "9"
+testpaths = [ "tests" ]
+
+[tool.tox]
+env_list = [
+  { prefix = "3.", start = 12, stop = 15 },
+  "type",
+]
+[tool.tox.env.type]
+description = "type check with ty"
+# ty reads src/ and the _core.pyi stub directly, so nothing needs compiling.
+package = "skip"
+dependency_groups = [ "dev" ]
+commands = [
+  [ "mypy", "src", "tests" ],
+  [ "ty", "check", "src", "tests" ],
+]
+[tool.tox.env_run_base]
+description = "run tests on Python {py_dot_ver}"
+dependency_groups = [ "dev" ]
+commands = [ [ "pytest", { replace = "posargs", extend = true, substitute = true } ] ]

nanofastq-0.0.1/src/fastq.c

@@ -0,0 +1,386 @@
+#include "fastq.h"
+
+#include <errno.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <zlib.h>
+
+#define READ_CHUNK (1 << 20)
+#define NO_PIN ((size_t)-1)
+
+struct FastqState {
+  gzFile file;
+  int64_t batch_size;
+  int64_t record_no;
+  int done;
+  // line reader: [pos, end) holds unconsumed bytes in buf
+  char* buf;
+  size_t cap, pos, end;
+  // Start of the record being parsed, or NO_PIN. Buffer compaction keeps bytes from
+  // here on so the record's earlier lines stay addressable while later ones are read.
+  size_t pin;
+  // Error found after good rows were already built: reported on the next get_next.
+  int pending_rc;
+  struct ArrowSchema schema;
+  char error[256];
+};
+
+// Records an error message and returns a negative errno-style code.
+static int Fail(struct FastqState* s, const char* fmt, long long n) {
+  snprintf(s->error, sizeof(s->error), fmt, n);
+  return -EINVAL;
+}
+
+// Strict UTF-8 check (rejects overlongs, surrogates and code points > U+10FFFF).
+// Has an 8-bytes-at-a-time fast path since FASTQ is almost always pure ASCII.
+static int IsValidUtf8(const char* data, size_t n) {
+  const unsigned char* p = (const unsigned char*)data;
+  const unsigned char* end = p + n;
+  while (p < end) {
+    if (end - p >= 8) {
+      uint64_t w;
+      memcpy(&w, p, 8);
+      if ((w & 0x8080808080808080ULL) == 0) {
+        p += 8;
+        continue;
+      }
+    }
+    unsigned char c = *p;
+    if (c < 0x80) {
+      p++;
+      continue;
+    }
+    size_t need;
+    unsigned char lo = 0x80, hi = 0xBF;  // allowed range of the 2nd byte
+    if (c >= 0xC2 && c <= 0xDF) {
+      need = 1;
+    } else if (c >= 0xE0 && c <= 0xEF) {
+      need = 2;
+      if (c == 0xE0) lo = 0xA0;
+      if (c == 0xED) hi = 0x9F;
+    } else if (c >= 0xF0 && c <= 0xF4) {
+      need = 3;
+      if (c == 0xF0) lo = 0x90;
+      if (c == 0xF4) hi = 0x8F;
+    } else {
+      return 0;
+    }
+    if ((size_t)(end - p) <= need) return 0;
+    if (p[1] < lo || p[1] > hi) return 0;
+    for (size_t i = 2; i <= need; i++) {
+      if ((p[i] & 0xC0) != 0x80) return 0;
+    }
+    p += need + 1;
+  }
+  return 1;
+}
+
+// True if every byte is < 0x80. Written as a branch-free OR-reduction so the compiler
+// can vectorize it.
+static int IsAscii(const char* data, size_t n) {
+  uint64_t acc = 0;
+  size_t i = 0;
+  for (; i + 8 <= n; i += 8) {
+    uint64_t w;
+    memcpy(&w, data + i, 8);
+    acc |= w;
+  }
+  unsigned char tail = 0;
+  for (; i < n; i++) tail |= (unsigned char)data[i];
+  return ((acc & 0x8080808080808080ULL) | (tail & 0x80)) == 0;
+}
+
+// Returns 1 with the line's offset into buf and length (without the trailing \n or
+// \r\n), 0 on EOF, -1 on error. Offsets, unlike pointers, survive later calls as long
+// as they are taken relative to s->pin.
+static int NextLine(struct FastqState* s, size_t* off, size_t* len) {
+  for (;;) {
+    char* nl = s->pos < s->end ? memchr(s->buf + s->pos, '\n', s->end - s->pos) : NULL;
+    if (nl) {
+      size_t start = s->pos;
+      size_t n = (size_t)(nl - (s->buf + start));
+      s->pos = start + n + 1;
+      if (n > 0 && s->buf[start + n - 1] == '\r') n--;
+      *off = start;
+      *len = n;
+      return 1;
+    }
+    // Need more data: compact (keeping the pinned record), grow, then refill.
+    size_t from = s->pin < s->pos ? s->pin : s->pos;
+    if (from > 0) {
+      memmove(s->buf, s->buf + from, s->end - from);
+      s->end -= from;
+      s->pos -= from;
+      if (s->pin != NO_PIN) s->pin -= from;
+    }
+    if (s->cap - s->end < READ_CHUNK) {
+      size_t new_cap = s->cap * 2;
+      char* nb = realloc(s->buf, new_cap);
+      if (!nb) {
+        snprintf(s->error, sizeof(s->error), "out of memory");
+        return -1;
+      }
+      s->buf = nb;
+      s->cap = new_cap;
+    }
+    int got = gzread(s->file, s->buf + s->end, (unsigned)(s->cap - s->end));
+    if (got < 0) {
+      int zerr;
+      snprintf(s->error, sizeof(s->error), "read error: %s", gzerror(s->file, &zerr));
+      return -1;
+    }
+    if (got == 0) {
+      if (s->pos == s->end) return 0;
+      // final line without trailing newline
+      size_t start = s->pos, n = s->end - s->pos;
+      s->pos = s->end;
+      if (s->buf[start + n - 1] == '\r') n--;
+      *off = start;
+      *len = n;
+      return 1;
+    }
+    s->end += (size_t)got;
+  }
+}
+
+struct Record {
+  const char *name, *desc, *seq, *qual;  // desc is NULL when the header has none
+  size_t name_len, desc_len, seq_len;    // qual has the same length as seq
+};
+
+// Reads and fully validates one record before anything is appended to Arrow.
+// Returns 1 with `r` filled in (pointers valid until the next NextLine call),
+// 0 on EOF, or a negative errno-style code with s->error set.
+static int ParseRecordLines(struct FastqState* s, struct Record* r) {
+  size_t rel[4], len[4], off;  // rel[i]: offset of line i relative to s->pin
+  int got;
+
+  for (;;) {
+    s->pin = s->pos;
+    if ((got = NextLine(s, &off, &len[0])) < 0) return -EIO;
+    if (got == 0) return 0;
+    if (len[0] > 0) break;  // tolerate blank lines between records
+  }
+  rel[0] = off - s->pin;
+  s->record_no++;
+  if (s->buf[off] != '@') {
+    return Fail(s, "record %lld: header does not start with '@'", s->record_no);
+  }
+
+  static const char* const truncated[3] = {
+      "record %lld: truncated after header",
+      "record %lld: missing '+' separator line",
+      "record %lld: truncated before quality line",
+  };
+  for (int i = 1; i < 4; i++) {
+    if ((got = NextLine(s, &off, &len[i])) < 0) return -EIO;
+    if (got == 0) return Fail(s, truncated[i - 1], s->record_no);
+    rel[i] = off - s->pin;
+  }
+
+  const char* base = s->buf + s->pin;
+  const char* header = base + rel[0];
+  const char* plus = base + rel[2];
+  if (len[2] == 0 || plus[0] != '+') return Fail(s, truncated[1], s->record_no);
+  if (len[3] != len[1]) {
+    return Fail(s, "record %lld: sequence and quality lengths differ", s->record_no);
+  }
+
+  r->name = header + 1;
+  r->name_len = len[0] - 1;
+  r->desc = NULL;
+  r->desc_len = 0;
+  for (size_t i = 0; i < r->name_len; i++) {
+    if (r->name[i] == ' ' || r->name[i] == '\t') {
+      r->desc = r->name + i + 1;
+      r->desc_len = r->name_len - i - 1;
+      r->name_len = i;
+      break;
+    }
+  }
+  r->seq = base + rel[1];
+  r->seq_len = len[1];
+  r->qual = base + rel[3];
+
+  // The four lines are contiguous in the buffer, so one pass over the whole record
+  // settles the (overwhelmingly common) pure-ASCII case; only otherwise check per field.
+  if (IsAscii(base, rel[3] + len[3])) return 1;
+  if (!IsValidUtf8(r->name, r->name_len) || (r->desc && !IsValidUtf8(r->desc, r->desc_len))) {
+    return Fail(s, "record %lld: header is not valid UTF-8", s->record_no);
+  }
+  if (!IsValidUtf8(r->seq, r->seq_len)) {
+    return Fail(s, "record %lld: sequence is not valid UTF-8", s->record_no);
+  }
+  if (!IsValidUtf8(r->qual, r->seq_len)) {
+    return Fail(s, "record %lld: quality scores are not valid UTF-8", s->record_no);
+  }
+  return 1;
+}
+
+// Appends one value to a non-nullable utf8 column by writing its offset and data buffers
+// directly. This skips ArrowArrayAppendString's type dispatch and validity-bitmap handling,
+// which are pure overhead for columns that can never hold a null (no bitmap is allocated).
+static inline int AppendNonNull(struct ArrowArray* col, const char* data, size_t n) {
+  struct ArrowBuffer* offsets = ArrowArrayBuffer(col, 1);
+  struct ArrowBuffer* values = ArrowArrayBuffer(col, 2);
+  if (values->size_bytes + (int64_t)n > INT32_MAX) return EOVERFLOW;
+  int rc = ArrowBufferReserve(offsets, (int64_t)sizeof(int32_t));
+  if (rc != NANOARROW_OK) return rc;
+  if ((rc = ArrowBufferReserve(values, (int64_t)n)) != NANOARROW_OK) return rc;
+  memcpy(values->data + values->size_bytes, data, n);
+  values->size_bytes += (int64_t)n;
+  int32_t end = (int32_t)values->size_bytes;
+  memcpy(offsets->data + offsets->size_bytes, &end, sizeof(end));
+  offsets->size_bytes += (int64_t)sizeof(end);
+  col->length++;
+  return NANOARROW_OK;
+}
+
+static int AppendRecord(struct ArrowArray* array, const struct Record* r) {
+  int rc;
+  if ((rc = AppendNonNull(array->children[0], r->name, r->name_len)) != NANOARROW_OK) return rc;
+  if (r->desc) {
+    struct ArrowStringView dv = {r->desc, (int64_t)r->desc_len};
+    rc = ArrowArrayAppendString(array->children[1], dv);
+  } else {
+    rc = ArrowArrayAppendNull(array->children[1], 1);
+  }
+  if (rc != NANOARROW_OK) return rc;
+  if ((rc = AppendNonNull(array->children[2], r->seq, r->seq_len)) != NANOARROW_OK) return rc;
+  if ((rc = AppendNonNull(array->children[3], r->qual, r->seq_len)) != NANOARROW_OK) return rc;
+  // Equivalent to ArrowArrayFinishElement for a struct; the children's lengths are
+  // validated once per batch by ArrowArrayFinishBuildingDefault.
+  array->length++;
+  return NANOARROW_OK;
+}
+
+static int GetSchema(struct ArrowArrayStream* stream, struct ArrowSchema* out) {
+  struct FastqState* s = stream->private_data;
+  return ArrowSchemaDeepCopy(&s->schema, out);
+}
+
+static int GetNext(struct ArrowArrayStream* stream, struct ArrowArray* out) {
+  struct FastqState* s = stream->private_data;
+  out->release = NULL;
+  if (s->pending_rc) {
+    int rc = s->pending_rc;
+    s->pending_rc = 0;
+    s->done = 1;
+    return rc;
+  }
+  if (s->done) return 0;
+
+  struct ArrowArray array;
+  struct ArrowError nerr;
+  int rc = ArrowArrayInitFromSchema(&array, &s->schema, &nerr);
+  if (rc != NANOARROW_OK) {
+    snprintf(s->error, sizeof(s->error), "%.200s", nerr.message);
+    return rc;
+  }
+  if ((rc = ArrowArrayStartAppending(&array)) != NANOARROW_OK) goto fail;
+
+  int64_t n = 0;
+  while (n < s->batch_size) {
+    struct Record rec;
+    int got = ParseRecordLines(s, &rec);
+    if (got == 0) {
+      s->done = 1;
+      break;
+    }
+    if (got < 0) {
+      s->pin = NO_PIN;
+      if (n == 0) {
+        s->done = 1;
+        rc = -got;
+        goto fail;
+      }
+      // Hand back the good rows now; the error surfaces on the next call.
+      s->pending_rc = -got;
+      break;
+    }
+    rc = AppendRecord(&array, &rec);
+    s->pin = NO_PIN;  // the record's bytes were copied into Arrow buffers
+    if (rc != NANOARROW_OK) goto fail;
+    n++;
+  }
+  s->pin = NO_PIN;
+
+  if (n == 0) {
+    array.release(&array);
+    return 0;  // end of stream: out->release stays NULL
+  }
+  if ((rc = ArrowArrayFinishBuildingDefault(&array, &nerr)) != NANOARROW_OK) {
+    snprintf(s->error, sizeof(s->error), "%.200s", nerr.message);
+    array.release(&array);
+    return rc;
+  }
+  *out = array;
+  return 0;
+
+fail:
+  if (!s->error[0]) snprintf(s->error, sizeof(s->error), "failed to build batch (%d)", rc);
+  array.release(&array);
+  return rc;
+}
+
+static const char* GetLastError(struct ArrowArrayStream* stream) {
+  struct FastqState* s = stream->private_data;
+  return s->error[0] ? s->error : NULL;
+}
+
+static void Release(struct ArrowArrayStream* stream) {
+  struct FastqState* s = stream->private_data;
+  if (s->file) gzclose(s->file);
+  if (s->schema.release) s->schema.release(&s->schema);
+  free(s->buf);
+  free(s);
+  stream->release = NULL;
+}
+
+int NanoFastqOpen(const char* path, int64_t batch_size, struct ArrowArrayStream* out,
+                  struct ArrowError* err) {
+  if (batch_size <= 0) {
+    ArrowErrorSet(err, "batch_size must be positive");
+    return EINVAL;
+  }
+  struct FastqState* s = calloc(1, sizeof(*s));
+  if (!s) return ENOMEM;
+  s->batch_size = batch_size;
+  s->pin = NO_PIN;
+  s->cap = 2 * READ_CHUNK;
+  s->buf = malloc(s->cap);
+  s->file = gzopen(path, "rb");  // transparently reads uncompressed files too
+  if (!s->buf || !s->file) {
+    ArrowErrorSet(err, "cannot open '%s'", path);
+    if (s->file) gzclose(s->file);
+    free(s->buf);
+    free(s);
+    return ENOENT;
+  }
+  gzbuffer(s->file, 1 << 18);
+
+  ArrowSchemaInit(&s->schema);
+  int rc = ArrowSchemaSetTypeStruct(&s->schema, 4);
+  static const char* names[4] = {"name", "description", "sequence", "quality_scores"};
+  for (int i = 0; rc == NANOARROW_OK && i < 4; i++) {
+    rc = ArrowSchemaSetType(s->schema.children[i], NANOARROW_TYPE_STRING);
+    if (rc == NANOARROW_OK) rc = ArrowSchemaSetName(s->schema.children[i], names[i]);
+    if (rc == NANOARROW_OK && i != 1) s->schema.children[i]->flags &= ~ARROW_FLAG_NULLABLE;
+  }
+  if (rc != NANOARROW_OK) {
+    ArrowErrorSet(err, "failed to build schema");
+    struct ArrowArrayStream tmp = {0};
+    tmp.private_data = s;
+    Release(&tmp);
+    return rc;
+  }
+
+  out->get_schema = GetSchema;
+  out->get_next = GetNext;
+  out->get_last_error = GetLastError;
+  out->release = Release;
+  out->private_data = s;
+  return 0;
+}

nanofastq-0.0.1/src/fastq.h

@@ -0,0 +1,21 @@
+#ifndef NANOFASTQ_FASTQ_H
+#define NANOFASTQ_FASTQ_H
+
+#include "nanoarrow/nanoarrow.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/// Open a (optionally gzip-compressed) FASTQ file and expose it as a stream
+/// of record batches with schema:
+///   name: utf8, description: utf8 (nullable), sequence: utf8, quality_scores: utf8
+/// Returns 0 on success or an errno-style code (message written to `err`).
+int NanoFastqOpen(const char* path, int64_t batch_size, struct ArrowArrayStream* out,
+                  struct ArrowError* err);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

nanofastq-0.0.1/src/module.cc

@@ -0,0 +1,41 @@
+#include <nanobind/nanobind.h>
+#include <nanobind/stl/string.h>
+
+#include <cstdlib>
+
+#include "fastq.h"
+
+namespace nb = nanobind;
+
+static void stream_capsule_destructor(PyObject* capsule) {
+  auto* stream = static_cast<ArrowArrayStream*>(PyCapsule_GetPointer(capsule, "arrow_array_stream"));
+  if (stream == nullptr) {
+    PyErr_Clear();
+    return;
+  }
+  if (stream->release != nullptr) stream->release(stream);
+  free(stream);
+}
+
+NB_MODULE(_core, m) {
+  m.doc() = "Native FASTQ -> Arrow C stream reader";
+  m.def(
+      "open_stream",
+      [](const std::string& path, int64_t batch_size) {
+        auto* stream = static_cast<ArrowArrayStream*>(malloc(sizeof(ArrowArrayStream)));
+        ArrowError err{};
+        int rc = NanoFastqOpen(path.c_str(), batch_size, stream, &err);
+        if (rc != 0) {
+          free(stream);
+          throw nb::value_error(err.message);
+        }
+        PyObject* cap = PyCapsule_New(stream, "arrow_array_stream", stream_capsule_destructor);
+        if (!cap) {
+          stream->release(stream);
+          free(stream);
+          throw nb::python_error();
+        }
+        return nb::steal(cap);
+      },
+      nb::arg("path"), nb::arg("batch_size") = 65536);
+}

nanofastq-0.0.1/src/nanofastq/__init__.py

@@ -0,0 +1,31 @@
+"""Tiny FASTQ reader exposing the Arrow PyCapsule stream interface."""
+
+from __future__ import annotations
+
+import os
+
+from nanofastq import _core
+
+__all__ = ["FastqReader", "read_fastq"]
+
+
+class FastqReader:
+    """A lazily-read FASTQ file.
+
+    Implements ``__arrow_c_stream__`` so it can be passed directly to
+    pyarrow, polars, duckdb, pandas, etc. Each call opens the file afresh, so
+    consumers that probe the schema first (e.g. duckdb) work, and the object
+    can be scanned more than once.
+    """
+
+    def __init__(self, path: str | os.PathLike[str], batch_size: int = 65536) -> None:
+        self._path = os.fspath(path)
+        self._batch_size = batch_size
+        _core.open_stream(self._path, batch_size)  # fail early if unreadable
+
+    def __arrow_c_stream__(self, requested_schema: object | None = None) -> object:
+        return _core.open_stream(self._path, self._batch_size)
+
+
+def read_fastq(path: str | os.PathLike[str], batch_size: int = 65536) -> FastqReader:
+    return FastqReader(path, batch_size)

nanofastq-0.0.1/src/nanofastq/_core.pyi

@@ -0,0 +1,5 @@
+def open_stream(path: str, batch_size: int = 65536) -> object:
+    """Open a FASTQ file and return an ``arrow_array_stream`` PyCapsule.
+
+    Raises ``ValueError`` if the file cannot be opened or ``batch_size`` is not positive.
+    """

nanofastq-0.0.1/tests/test_reader.py

@@ -0,0 +1,254 @@
+import gzip
+from pathlib import Path
+
+import pyarrow as pa
+import pytest
+
+from nanofastq import read_fastq
+
+DATA = b"""\
+@r1 sample=a
+ACGT
++
+IIII
+@r2
+GG
++r2
+#!
+"""
+
+
+def write_lines(p: Path, lines: list[str]):
+    p.write_text("\n".join(lines) + "\n")
+
+
+def write_bytes(p: Path, lines: list[bytes]):
+    p.write_bytes(b"\n".join(lines) + b"\n")
+
+
+@pytest.fixture(params=["plain", "gz"])
+def fastq(request: pytest.FixtureRequest, tmp_path: Path) -> Path:
+    if request.param == "gz":
+        p = tmp_path / "x.fastq.gz"
+        p.write_bytes(gzip.compress(DATA))
+    else:
+        p = tmp_path / "x.fastq"
+        p.write_bytes(DATA)
+    return p
+
+
+def test_roundtrip(fastq: Path):
+    t = pa.table(read_fastq(fastq))
+    assert t.to_pylist() == [
+        {
+            "name": "r1",
+            "description": "sample=a",
+            "sequence": "ACGT",
+            "quality_scores": "IIII",
+        },
+        {"name": "r2", "description": None, "sequence": "GG", "quality_scores": "#!"},
+    ]
+
+
+def test_small_batches(fastq):
+    reader = pa.RecordBatchReader.from_stream(read_fastq(fastq, batch_size=1))
+    assert [len(b) for b in reader] == [1, 1]
+
+
+def test_rescan(fastq):
+    r = read_fastq(fastq)
+    assert pa.table(r).equals(pa.table(r))
+
+
+def test_polars_and_duckdb(fastq):
+    duckdb = pytest.importorskip("duckdb")
+    pl = pytest.importorskip("polars")
+
+    assert pl.DataFrame(read_fastq(fastq)).height == 2
+    r = read_fastq(fastq)  # noqa: F841 (duckdb replacement scan)
+    assert duckdb.execute("select count(*) from r").fetchall() == [(2,)]
+
+
+def test_malformed(tmp_path: Path):
+    p = tmp_path / "bad.fastq"
+    write_lines(p, ["@r1", "ACGT", "+", "II"])  # quality too short
+    with pytest.raises(pa.ArrowInvalid, match="lengths differ"):
+        pa.table(read_fastq(p))
+
+
+def test_missing_file(tmp_path: Path):
+    with pytest.raises(ValueError, match="cannot open"):
+        read_fastq(tmp_path / "nope.fastq")
+
+
+def test_utf8_header_ok(tmp_path: Path):
+    p = tmp_path / "u.fastq"
+    p.write_bytes("@r\u00e9ad \u2603 \U0001f9ec\nAC\n+\nII\n".encode())
+    write_bytes(
+        p,
+        [
+            "@r\u00e9ad \u2603 \U0001f9ec".encode(),
+            b"AC",
+            b"+",
+            b"II",
+        ],
+    )
+    t = pa.table(read_fastq(p))
+    assert t["name"].to_pylist() == ["r\u00e9ad"]
+    assert t["description"].to_pylist() == ["\u2603 \U0001f9ec"]
+
+
+@pytest.mark.parametrize(
+    "bad",
+    [
+        b"\xff",  # never valid
+        b"\xc0\x80",  # overlong NUL
+        b"\xe0\x80\x80",  # overlong
+        b"\xed\xa0\x80",  # surrogate
+        b"\xf4\x90\x80\x80",  # > U+10FFFF
+        b"\xe2\x98",  # truncated
+        b"\xc3",  # truncated at end of field
+    ],
+)
+@pytest.mark.parametrize("where", ["header", "sequence", "quality"])
+def test_invalid_utf8(tmp_path: Path, bad: bytes, where: str):
+    hdr, seq, qual = b"r1", b"A" * len(bad), b"I" * len(bad)
+    if where == "header":
+        hdr = b"r1 " + bad
+    elif where == "sequence":
+        seq = bad
+    else:
+        qual = bad
+    p = tmp_path / "bad.fastq"
+    write_bytes(
+        p,
+        [
+            b"@" + hdr,
+            seq,
+            b"+",
+            qual,
+        ],
+    )
+    with pytest.raises(pa.ArrowInvalid, match="not valid UTF-8"):
+        pa.table(read_fastq(p))
+
+
+def test_good_rows_before_error_are_kept(tmp_path: Path):
+    p = tmp_path / "partial.fastq"
+    write_lines(
+        p,
+        [
+            "@a",
+            "AC",
+            "+",
+            "II",
+            "@b",
+            "GG",
+            "+",
+            "##",
+            "@c",
+            "ACGT",
+            "+",
+            "II",
+            "@d",
+            "T",
+            "+",
+            "I",
+        ],
+    )
+    reader = pa.RecordBatchReader.from_stream(read_fastq(p, batch_size=100))
+    first = reader.read_next_batch()
+    assert first.column("name").to_pylist() == ["a", "b"]
+    with pytest.raises(pa.ArrowInvalid, match="record 3: sequence and quality"):
+        reader.read_next_batch()
+
+
+def test_error_in_first_row_of_batch(tmp_path: Path):
+    p = tmp_path / "first.fastq"
+    write_lines(
+        p,
+        [
+            "@a",
+            "AC",
+            "+",
+            "II",
+            "@b",
+            "GG",
+            "+",
+            "##",
+            "@c",
+            "ACGT",
+            "+",
+            "II",
+        ],
+    )
+    reader = pa.RecordBatchReader.from_stream(read_fastq(p, batch_size=2))
+    assert len(reader.read_next_batch()) == 2
+    with pytest.raises(pa.ArrowInvalid, match="record 3"):
+        reader.read_next_batch()
+
+
+def test_record_spanning_buffer_refills(tmp_path: Path):
+    # Lines far larger than the initial buffer force compaction/realloc mid-record.
+    n = 5_000_000
+    p = tmp_path / "big.fastq"
+    write_lines(
+        p,
+        [
+            "@big desc",
+            "A" * n,
+            "+",
+            "I" * n,
+            "@s",
+            "AC",
+            "+",
+            "II",
+        ],
+    )
+    t = pa.table(read_fastq(p))
+    assert t["name"].to_pylist() == ["big", "s"]
+
+    seq0 = t["sequence"][0]
+    assert isinstance(seq0, pa.StringScalar)
+    assert len(seq0.as_py()) == n
+
+    qual1 = t["quality_scores"][1]
+    assert isinstance(qual1, pa.StringScalar)
+    assert qual1.as_py() == "II"
+
+
+@pytest.mark.parametrize(
+    ("data", "msg"),
+    [
+        pytest.param(
+            ["garbage"],
+            "does not start with '@'",
+            id="no-at-start",
+        ),
+        pytest.param(
+            ["@a"],
+            "truncated after header",
+            id="truncated-after-header",
+        ),
+        pytest.param(
+            ["@a", "AC"],
+            "missing '\\+'",
+            id="missing-plus-after-sequence",
+        ),
+        pytest.param(
+            ["@a", "AC", "x", "II"],
+            "missing '\\+'",
+            id="missing-plus-after-quality",
+        ),
+        pytest.param(
+            ["@a", "AC", "+"],
+            "truncated before quality",
+            id="truncated-before-quality",
+        ),
+    ],
+)
+def test_structural_errors(tmp_path: Path, data: list[str], msg: str):
+    p = tmp_path / "s.fastq"
+    write_lines(p, data)
+    with pytest.raises(pa.ArrowInvalid, match=msg):
+        pa.table(read_fastq(p))