Sassy Python Bindings

🐍 The python bindings for Sassy

Installation

Pip.

pip install sassy-rs

(as sassy was already taken we chose sassy-rs)

From source. In the root of the repository, run:

maturin develop --features python

You need Maturin for this, see maturin:

Usage

A simple usage is as follows:

import sassy
pattern = b"ATCGATCG"
text = b"GGGGATCGATCGTTTT"
# alphabet: ascii, dna, iupac
searcher = sassy.Searcher("dna")
matches = searcher.search(pattern, text, k=1)
for i, match in enumerate(matches):
    print(f"Match {i+1}:")
    print(f"    Start: {match.text_start}")
    print(f"    End: {match.text_end}")
    print(f"    Cost: {match.cost}")
    print(f"    Strand: {match.strand}")
    print(f"    CIGAR: {match.cigar}")

This finds 3 matches:

Match 1:
    Start: 4
    End: 12
    Cost: 0
    Strand: +
    CIGAR: 8=
Match 2:
    Start: 6
    End: 14
    Cost: 1
    Strand: -
    CIGAR: 6=X=
Match 3:
    Start: 2
    End: 10
    Cost: 1
    Strand: -
    CIGAR: X7=

Further options are sassy.Searcher(alpha=0.5) to allow overhang alignments, sassy.Searcher("dna", rc=False) to disable reverse complements for DNA or IUPAC strings, and sassy.Searcher("dna", max_n_frac=0.1) to drop matches whose aligned text region is more than 10% N bases. Here, max_n_frac is a fraction in [0, 1] where omitting it or using 1.0 disables the filter. searcher.search is the simple function to search one pattern in one text, while searcher.search_many takes multiple patterns and multiple texts and searches each pattern in each text, possibly in multiple threads.

See sassy/example.py for a larger example.

Type Hints

This package ships PEP 561 type stubs (sassy/py.typed + sassy/__init__.pyi) so that type checkers and IDEs can provide autocomplete and type checking out of the box.

The .pyi stubs are auto-generated by the PyPI publishing workflow, and are not stored in git. To manually generate stubs for local testing:

# macOS
RUSTFLAGS="-C link-arg=-undefined -C link-arg=dynamic_lookup" cargo build --features python
cargo run --features python-stubs --bin gen_stubs -- target/debug/libsassy.dylib

# Linux
cargo build --features python
cargo run --features python-stubs --bin gen_stubs -- target/debug/libsassy.so

Once the stubs have been generated, type-checking for the sassy Python library will be enabled. See sassy/example_typed.py for a typed example that exercises all public APIs.

Running the example requires the sassy package be installed in your environment.

To install maturin and the package in an isolated environment, then run the typed example you can use a single uv command:

uv run \
    --with maturin \
    sh -c 'maturin develop && python python/sassy/example_typed.py'

Running type checking on the type exampled requires mypy be installed in your environment.

To install mypy in an isolated environment then run type checking on the typed example you can use a single uv command:

uv run \
    --with mypy \
    sh -c 'mypy python/sassy/example_typed.py'

Troubleshooting

1. I could install sassy-rc but no modules/functions are found.

When creating an issue please include the output of print(dir(sassy)) if you were able to install sassy-rs but no functions/modules were found.

Your output might look like:

['__all__', '__builtins__', '__cached__', '__doc__', '__file__', '__loader__', '__name__', '__package__', '__path__', '__spec__']

Whereas it should look like:

['Match', 'Searcher', '__all__', '__builtins__', '__cached__', '__doc__', '__file__', '__loader__', '__name__', '__package__', '__path__', '__spec__', 'features']

2. Other sassy issues.

If you were able to install sassy, but have other issues please also add the output of sassy.features().