Deacon for Python

Python bindings for 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.

Installation

uv pip install deacon

Quickstart

from deacon import Index

index = Index("panhuman-1.k31w15.idx")
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 = Index("panhuman-1.k31w15.idx", complexity_threshold=None)

Pass complexity_threshold (0.0–1.0, e.g. 0.9) to discard low-complexity index minimizers once at load using kdust; the filtered set is then reused across all filter calls. Not supported for bff (binary fuse filter) indexes.

path is positional-only and accepts a string or path-like object. complexity_threshold is keyword-only.

`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.

index = Index.fetch(
    name="panhuman-1",
    k=31,
    w=15,
    output=None,
    complexity_threshold=None,
)

All fetch() arguments are keyword-only.

`Index.info()`

index.info() 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 minimizers/keys represented by the index

`Index.filter()`

Filter FASTA, FASTQ, or CBQ input against the index and return a dict of summary statistics. FASTA/FASTQ compression (.gz, .zst, or .xz) is detected automatically. A .cbq output writes CBQ; .cba writes quality-free CBQ. The Python GIL is released while filtering, so calls benefit from multithreading. Refer to the main Deacon readme for more detailed usage examples.

def filter(
    input,                   # positional-only FASTA, FASTQ, or CBQ path
    /,
    *,                       # every remaining argument is keyword-only
    input2=None,             # second FASTA/FASTQ mate
    interleaved=False,       # treat input as interleaved pairs (cannot combine with input2)
    check_pairs=False,       # validate paired read names
    deplete=False,           # False = search (keep matches); True = deplete (remove matches)
    rename=False,            # replace read names with sequential integers
    output=None,             # output path; None writes FASTA/FASTQ to stdout
    output2=None,            # second output path for paired reads
    summary=None,            # optional JSON summary output path
    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)
    discard_quality=False,   # discard quality scores
    ordered=False,           # preserve input record ordering (deterministic, slightly slower)
    threads=8,               # worker threads for filtering
    compression_level=2,     # output compression level
    compression_threads=0,   # threads for output compression (0 = auto)
    cbq_block_size=16,        # CBQ output block size in MiB (1-1024)
    quiet=True,              # suppress progress/log output on stderr
    debug=False,             # verbose per-read debug output
) -> 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.

Paired and CBQ input. Use input2= for separate FASTA/FASTQ mates or interleaved=True for an interleaved stream. check_pairs=True validates Illumina CASAVA or /1 and /2 names. CBQ stores pairing internally, so CBQ input cannot be combined with input2 or interleaved; paired CBQ output uses one output and cannot use output2.

Output. When output is None the filtered records are written to stdout. To count without keeping the filtered sequences, pass output="/dev/null". Pass summary= to write the same statistics returned by the call as JSON. For CBQ output, cbq_block_size is a lower bound: a larger input CBQ block size is preserved.

Return value. A dict including the run configuration (version, index, input/input2, output/output2, k, w, abs_threshold, rel_threshold, prefix_length, deplete, rename, ordered, check_pairs) 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)

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

deacon-0.17.0.tar.gz (3.0 MB view details)

Uploaded Aug 18, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

deacon-0.17.0-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (3.2 MB view details)

Uploaded Aug 18, 2026 CPython 3.12+manylinux: glibc 2.17+ x86-64

deacon-0.17.0-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (3.0 MB view details)

Uploaded Aug 18, 2026 CPython 3.12+manylinux: glibc 2.17+ ARM64

deacon-0.17.0-cp312-abi3-macosx_11_0_arm64.whl (2.4 MB view details)

Uploaded Aug 18, 2026 CPython 3.12+macOS 11.0+ ARM64

File details

Details for the file deacon-0.17.0.tar.gz.

File metadata

Download URL: deacon-0.17.0.tar.gz
Upload date: Aug 18, 2026
Size: 3.0 MB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for deacon-0.17.0.tar.gz
Algorithm	Hash digest
SHA256	`adf94c2cf03e2bf84fabdf7f60a888f6b259d516d249172f9c8fd109828603c7`
MD5	`d5ea80d6fc250b81b0210c02d956fddd`
BLAKE2b-256	`6db4d7be20b54f01d9d609e7b56bcb7013c2a95837c8b75deb2baeacb204a702`

See more details on using hashes here.

Provenance

The following attestation bundles were made for deacon-0.17.0.tar.gz:

Publisher: release-pypi.yaml on bede/deacon

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: deacon-0.17.0.tar.gz
- Subject digest: adf94c2cf03e2bf84fabdf7f60a888f6b259d516d249172f9c8fd109828603c7
- Sigstore transparency entry: 2502921280
- Sigstore integration time: Aug 18, 2026
Source repository:
- Permalink: bede/deacon@fd5708b0f3a0e9a6904885053ca34338ea51b861
- Branch / Tag: refs/tags/0.17.0
- Owner: https://github.com/bede
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release-pypi.yaml@fd5708b0f3a0e9a6904885053ca34338ea51b861
- Trigger Event: push

File details

Details for the file deacon-0.17.0-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

Download URL: deacon-0.17.0-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Upload date: Aug 18, 2026
Size: 3.2 MB
Tags: CPython 3.12+, manylinux: glibc 2.17+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for deacon-0.17.0-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm	Hash digest
SHA256	`7d15c60409d78c132521d3e74e318a53ac5809273ef83f947597f57828240374`
MD5	`d1f08c80de040b46fb530b301c82be93`
BLAKE2b-256	`5a65d311c51bdc7b433f588e1dc623cfd715134d43bc2052478ec0bce866faf4`

See more details on using hashes here.

Provenance

The following attestation bundles were made for deacon-0.17.0-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release-pypi.yaml on bede/deacon

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: deacon-0.17.0-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- Subject digest: 7d15c60409d78c132521d3e74e318a53ac5809273ef83f947597f57828240374
- Sigstore transparency entry: 2502921424
- Sigstore integration time: Aug 18, 2026
Source repository:
- Permalink: bede/deacon@fd5708b0f3a0e9a6904885053ca34338ea51b861
- Branch / Tag: refs/tags/0.17.0
- Owner: https://github.com/bede
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release-pypi.yaml@fd5708b0f3a0e9a6904885053ca34338ea51b861
- Trigger Event: push

File details

Details for the file deacon-0.17.0-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

Download URL: deacon-0.17.0-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Upload date: Aug 18, 2026
Size: 3.0 MB
Tags: CPython 3.12+, manylinux: glibc 2.17+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for deacon-0.17.0-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm	Hash digest
SHA256	`f3b4b9eea0b7325c8556f5dadcba2f2fafb62f9af0fa7754f4740ccb566b9b81`
MD5	`d3ff2ca1593114b89e4a4ef5a9b72803`
BLAKE2b-256	`75b1142543cc10308f608d9a702246f3e77b8c9e8b80599cd0e5bb0dcd0876c6`

See more details on using hashes here.

Provenance

The following attestation bundles were made for deacon-0.17.0-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release-pypi.yaml on bede/deacon

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: deacon-0.17.0-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
- Subject digest: f3b4b9eea0b7325c8556f5dadcba2f2fafb62f9af0fa7754f4740ccb566b9b81
- Sigstore transparency entry: 2502921576
- Sigstore integration time: Aug 18, 2026
Source repository:
- Permalink: bede/deacon@fd5708b0f3a0e9a6904885053ca34338ea51b861
- Branch / Tag: refs/tags/0.17.0
- Owner: https://github.com/bede
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release-pypi.yaml@fd5708b0f3a0e9a6904885053ca34338ea51b861
- Trigger Event: push

File details

Details for the file deacon-0.17.0-cp312-abi3-macosx_11_0_arm64.whl.

File metadata

Download URL: deacon-0.17.0-cp312-abi3-macosx_11_0_arm64.whl
Upload date: Aug 18, 2026
Size: 2.4 MB
Tags: CPython 3.12+, macOS 11.0+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for deacon-0.17.0-cp312-abi3-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`7d0bc685093b94d1a8b0dca2b469dd9e35c6e2ad64714bf01ce63bb71440b0b9`
MD5	`9fbb4607ed7928621293c54fb20858c1`
BLAKE2b-256	`0aca4aab75c778d62d832ccdbd4f61b90a2ba5a268e690453f9f2dcab0b8c29f`

See more details on using hashes here.

Provenance

The following attestation bundles were made for deacon-0.17.0-cp312-abi3-macosx_11_0_arm64.whl:

Publisher: release-pypi.yaml on bede/deacon

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: deacon-0.17.0-cp312-abi3-macosx_11_0_arm64.whl
- Subject digest: 7d0bc685093b94d1a8b0dca2b469dd9e35c6e2ad64714bf01ce63bb71440b0b9
- Sigstore transparency entry: 2502921691
- Sigstore integration time: Aug 18, 2026
Source repository:
- Permalink: bede/deacon@fd5708b0f3a0e9a6904885053ca34338ea51b861
- Branch / Tag: refs/tags/0.17.0
- Owner: https://github.com/bede
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release-pypi.yaml@fd5708b0f3a0e9a6904885053ca34338ea51b861
- Trigger Event: push

Release history Release notifications | RSS feed

This release

0.17.0 This release

Aug 18, 2026 4 files

0.16.0

Aug 9, 2026 4 files

Pre-release

0.16.0rc4

Jul 2, 2026 4 files

Pre-release

0.16.0rc3

Jul 2, 2026 4 files

Pre-release

0.16.0rc2

Jul 1, 2026 4 files

Pre-release

0.16.0rc1

Jul 1, 2026 4 files

deacon 0.17.0

Deacon for Python

Installation

Quickstart

`Index()`

`Index.fetch()`

`Index.info()`

`Index.filter()`

Project links

Key dates

1 maintainer

GitHub Statistics

License expression

Requires

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

Release history Release notifications | RSS feed