sassy 0.2.4

Approximate string matching using SIMD
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128

# Sassy Python Bindings

🐍 The python bindings for Sassy

## Installation

**Pip.**
```bash
pip install sassy-rs
```
(as sassy was already taken we chose sassy-rs)

**From source.**
In the root of the repository, run: 
```bash
maturin develop --features python
```
You need Maturin for this, see [maturin](https://github.com/PyO3/maturin):


## Usage

A simple usage is as follows:

``` python
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:

``` text
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,
and `sassy.Searcher("dna", rc=False)` to disable reverse complements for DNA
or IUPAC strings. `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](sassy/example.py) for a larger example.

## Type Hints

This package ships [PEP 561](https://peps.python.org/pep-0561/) 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:

```bash
# 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](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`](https://docs.astral.sh/uv/) command:
```console
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`](https://docs.astral.sh/uv/) command:
```console
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:
```python
['__all__', '__builtins__', '__cached__', '__doc__', '__file__', '__loader__', '__name__', '__package__', '__path__', '__spec__']
```
Whereas it should look like:
```python
['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()`.