Metadata-Version: 2.4
Name: spellchecks
Version: 0.1.1
Summary: Python library for spell-checking text in multiple languages
Keywords: python,spellcheck,spellchecker,enchant,nlp
Author: Artur Shiriev
Author-email: Artur Shiriev <me@shiriev.ru>
License-Expression: MIT
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Classifier: Topic :: Software Development :: Libraries
Requires-Dist: pyenchant
Requires-Dist: cachebox
Requires-Dist: urlextract
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# spellcheck-lib

Python library for spell-checking text in multiple languages, backed by [pyenchant](https://pyenchant.github.io/pyenchant/).

**Supported languages**: `ru_RU`, `en_US`, `es_ES`, `fr_FR`, `de_DE`, `pt_PT`

## Installation

```bash
pip install spellchecks
# or
uv add spellchecks
```

### System dependencies

These are native OS packages — they cannot be installed from PyPI.

| Package | Purpose |
|---|---|
| `libenchant-2` | C library that `pyenchant` wraps; provides the spell-checking abstraction layer |
| `aspell` | Spell-checking backend used by enchant at runtime |
| `aspell-en` / `aspell-ru` / `aspell-es` / `aspell-fr` / `aspell-de` / `aspell-pt` | Per-language word dictionaries for aspell |

```bash
# macOS (installs enchant + hunspell backend + EN dictionary)
brew install enchant
export PYENCHANT_LIBRARY_PATH=/opt/homebrew/lib/libenchant-2.dylib
# additional languages via hunspell dicts, e.g.:
brew install hunspell
# place .dic/.aff files in ~/Library/Spelling/

# Debian/Ubuntu
apt-get install libenchant-2-dev aspell aspell-en aspell-ru aspell-es aspell-fr aspell-de aspell-pt-br
```

## Usage

```python
from spellchecks import SpellChecker

checker = SpellChecker(language="ru_RU")
corrections = checker.check("Превед медвет")
# [OneCorrection(first_position=0, last_position=6, word='Превед', suggestions=(...)),
#  OneCorrection(first_position=7, last_position=13, word='медвет', suggestions=(...))]
```

### With per-user word exceptions

```python
from spellchecks import SpellChecker, FileProvider

provider = FileProvider("/data/dicts")
provider.add_word("alice", "Превед")  # add to alice's personal dictionary

words = provider.get_words("alice")
checker = SpellChecker(language="ru_RU", exclusion_words=words)
corrections = checker.check("Привет Превед")
# Превед is now excluded from corrections
```

### Parameters

`SpellChecker(*, language, exclusion_words=(), exclude_urls=True, cache_size=10000, max_suggestions=0)`

- `language` — one of the supported language codes
- `exclusion_words` — iterable of words to ignore (case-insensitive)
- `exclude_urls` — automatically ignore URLs found in the text (default `True`)
- `cache_size` — LRU cache size for suggestions; `0` disables caching (default `10000`)
- `max_suggestions` — max suggestions per misspelled word; `0` = unlimited (default `0`)

`SpellChecker.check(text)`

- `text` — text to check

### Custom dictionary storage

Implement `UserDictProtocol` for custom storage backends:

```python
from spellchecks import UserDictProtocol


class RedisProvider:
    def get_words(self, user_name: str) -> list[str]: ...

    def add_word(self, user_name: str, word: str) -> None: ...

    def remove_word(self, user_name: str, word: str) -> None: ...
```

## Development

```bash
uv sync --all-groups
just lint
just test
```
