Static liblzma for hopefully portable Py wheels, bump py to rc2, readme

Author: bede

deacon-py/python/README.md

@@ -1,19 +1,88 @@
-# Deacon Python bindings
+# Deacon for Python
 
-Enables index reuse between filtering sessions.
+Python bindings for [Deacon](https://github.com/bede/deacon), enabling fast multithreaded DNA sequence filtering for e.g. host pangenome depletion using Python code. These bindings load an index once, allowing subsequent filtering runs with low latency. Deacon's complete functionality is currently only available using the [Rust/CLI version of Deacon](https://github.com/bede/deacon).
+
+## Installation
+
+```bash
+uv install deacon
+```
+
+## Quickstart
 
 ```python
 from deacon import Index
 
 index = Index("panhuman-1.k31w15.idx")
-stats = [
-    index.filter(fq, deplete=True, rename=True,
-                 output=fq.replace(".fastq.gz", ".clean.fastq.gz"))
-    for fq in input_fastqs
-]
-print(stats[0]["seqs_in"], stats[0]["seqs_out"])
+stats = index.filter(
+    fastq_path,
+    deplete=True,
+    rename=True,
+    output=fastq_path.replace(".fastq.gz", ".clean.fastq.gz")
+)
+print(stats["seqs_in"], stats["seqs_out"])
+```
+
+## `Index()`
+
+Load a minimizer index or probabilistic filter from disk. The resulting object may be reused across many `filter` calls.
+
+## `Index.fetch()`
+
+Download a prebuilt index, then load and return it (a static method, so `Index.fetch(...)` returns an `Index`). `output` is the local path to save to; when omitted it defaults to `"{name}.k{k}w{w}.idx"` in the working directory. The index is downloaded on every call — there is no local cache, so an existing file at that path is overwritten.
+
+```python
+index = Index.fetch("panhuman-1", k=31, w=15, output=None)
 ```
 
-`filter` accepts single or paired input (`fastq2=`, `output2=`), auto-detects `.gz`/`.zst`/
-`.xz` output compression from the extension, and returns a `dict` of summary statistics.
-`from deacon import filter` also exposes `filter(index, ...)` as a free function.
+## `Index.info()`
+
+`Index.info(index_path)` Returns a `dict` of index metadata:
+
+| Key | Meaning |
+| --- | --- |
+| `k` | *k*-mer length |
+| `w` | minimizer window size |
+| `format` | `exact-u64`, `exact-u128`, or `bff` (binary fuse filter) |
+| `count` | number of keys in index (fingerprint slot count for `bff`) |
+
+## `Index.filter()`
+
+Filter a FASTA/FASTQ file or file pair against the index and return a `dict` of summary statistics. Auto-detects `.gz`/`.zst`/`.xz` compression on both input and output based on file extension. The Python GIL is released while filtering meaning calls benefit from multithreading. Refer to the [main Deacon readme](https://github.com/bede/deacon) for more detailed usage examples.
+
+```python
+def filter(
+    fastq,                   # input path (FASTA/FASTQ, optionally .gz/.zst/.xz)
+    fastq2=None,             # second mate for paired reads
+    deplete=False,           # False = search (keep matches); True = deplete (remove matches)
+    rename=False,            # replace read names with sequential integers
+    rename_random=False,     # replace read names with random strings
+    output=None,             # output path; None writes to stdout
+    output2=None,            # second output path for paired reads
+    abs_threshold=2,         # min absolute minimizer hits to call a match
+    rel_threshold=0.01,      # min proportion of minimizers hitting to call a match
+    prefix_length=0,         # only use the first N bp of each read (0 = whole read)
+    output_fasta=False,      # emit FASTA instead of FASTQ
+    threads=8,               # worker threads for filtering
+    compression_level=2,     # output compression level
+    compression_threads=0,   # threads for output compression (0 = auto)
+    debug=False,             # verbose per-read debug output
+    quiet=True,              # suppress progress/log output on stderr
+) -> dict
+```
+
+**Modes.** With `deplete=False` (the default, *search* mode) reads that match the index are kept; with `deplete=True` reads that match are removed (host depletion). A read is a match only when it clears **both** thresholds: at least `abs_threshold` minimizer hits **and** at least `rel_threshold` of its minimizers hitting the index.
+
+**Output.** When `output` is `None` the filtered records are written to stdout. To count without keeping the filtered sequences, pass `output="/dev/null"`. Statistics are returned regardless.
+
+**Return value.** A `dict` including the run configuration (`version`, `index`, `input`/`input2`, `output`/`output2`, `k`, `w`, `abs_threshold`, `rel_threshold`, `prefix_length`, `deplete`, `rename`, `rename_random`) and the results:
+
+| Key | Meaning |
+| --- | --- |
+| `seqs_in`, `seqs_out`, `seqs_removed` | sequence counts |
+| `seqs_out_proportion`, `seqs_removed_proportion` | sequence proportions |
+| `bp_in`, `bp_out`, `bp_removed` | base-pair counts |
+| `bp_out_proportion`, `bp_removed_proportion` | base-pair proportions |
+| `time` | wall-clock seconds |
+| `seqs_per_second`, `bp_per_second` | throughput (filtering only) |
+| `seqs_per_second_total`, `bp_per_second_total` | throughput (including load/IO) |

deacon-py/python/deacon/__init__.py

@@ -1,3 +1,3 @@
-from ._deacon import Index, __version__, filter
+from ._deacon import Index, __version__
 
-__all__ = ["Index", "filter", "__version__"]
+__all__ = ["Index", "__version__"]

deacon-py/python/deacon/_deacon.pyi

@@ -18,9 +18,4 @@ class Index:
         Index metadata: k, w, format and minimizer/key count.
         """
 
-def filter(index: Index, fastq: str, fastq2: str |None = None, deplete: bool = False, rename: bool = False, rename_random: bool = False, output: str |None = None, output2: str |None = None, abs_threshold: int = 2, rel_threshold: float = 0.01, prefix_length: int = 0, output_fasta: bool = False, threads: int = 8, compression_level: int = 2, compression_threads: int = 0, debug: bool = False, quiet: bool = True) -> Any:
-    """
-    Module-level wrapper so `from deacon import filter` works: `filter(index, ...)`.
-    """
-
 def __getattr__(name: str) -> Incomplete: ...

deacon-py/src/lib.rs

@@ -132,77 +132,13 @@ impl Index {
     }
 }
 
-/// Module-level wrapper so `from deacon import filter` works: `filter(index, ...)`.
-#[pyfunction]
-#[pyo3(signature = (
-    index,
-    fastq,
-    fastq2=None,
-    deplete=false,
-    rename=false,
-    rename_random=false,
-    output=None,
-    output2=None,
-    abs_threshold=2,
-    rel_threshold=0.01,
-    prefix_length=0,
-    output_fasta=false,
-    threads=8,
-    compression_level=2,
-    compression_threads=0,
-    debug=false,
-    quiet=true,
-))]
-fn filter(
-    py: Python<'_>,
-    index: &Index,
-    fastq: String,
-    fastq2: Option<String>,
-    deplete: bool,
-    rename: bool,
-    rename_random: bool,
-    output: Option<String>,
-    output2: Option<String>,
-    abs_threshold: usize,
-    rel_threshold: f64,
-    prefix_length: usize,
-    output_fasta: bool,
-    threads: u16,
-    compression_level: u8,
-    compression_threads: u16,
-    debug: bool,
-    quiet: bool,
-) -> PyResult<Py<PyAny>> {
-    index.filter(
-        py,
-        fastq,
-        fastq2,
-        deplete,
-        rename,
-        rename_random,
-        output,
-        output2,
-        abs_threshold,
-        rel_threshold,
-        prefix_length,
-        output_fasta,
-        threads,
-        compression_level,
-        compression_threads,
-        debug,
-        quiet,
-    )
-}
-
 // Declarative module form so pyo3 introspection can link members (see scripts/gen-py-stubs.sh).
 #[pymodule]
 mod _deacon {
     use pyo3::prelude::*;
 
     #[pymodule_export]
     use super::Index;
-    #[pymodule_export]
-    use super::filter;
 
     #[pymodule_init]
     fn init(m: &Bound<'_, PyModule>) -> PyResult<()> {