### Install cyhunspell

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/quick-reference.md

Install the cyhunspell library using pip.

```bash
pip install cyhunspell
```

--------------------------------

### String Type Examples

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/types.md

Demonstrates the usage of the string type for word input and output, including ASCII, Unicode, and empty strings.

```python
from hunspell import Hunspell

h = Hunspell()

# ASCII strings
h.spell('test')

# Unicode/UTF-8 strings
h.spell('café')

# Empty string
h.spell('')  # Returns True
```

--------------------------------

### Tuple Type Examples for Morphological Operations

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/types.md

Provides examples of tuple return types for operations like stemming, suggesting, and analyzing words, showing single, multiple, and empty results.

```python
from hunspell import Hunspell

h = Hunspell()

# Single result
result: tuple[str, ...] = h.stem('dog')
# ('dog',)

# Multiple results, ordered by relevance
result: tuple[str, ...] = h.suggest('incorect')
# ('incorrect', 'correction', 'corrector', 'correct', 'injector')

# Empty result
result: tuple[str, ...] = h.suggest('')
# ()

# Analysis result
result: tuple[str, ...] = h.analyze('permanently')
# (' st:permanent fl:Y',)
```

--------------------------------

### add

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/api-reference/hunspell.md

Adds a word to the runtime dictionary, optionally inheriting affix rules from an example word.

```APIDOC
## Method: `add`

Add a word to the runtime dictionary.

```python
def add(self, word: str, example: str | None = None) -> int
```

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| word | str | Yes | Word to add to dictionary. |
| example | str | None | No | Example word whose affix rules apply to the new word. If provided, new word inherits morphological capabilities of example. |

### Returns

`int`: Hunspell internal return code (typically 0 on success).

### Examples

```python
h = Hunspell()
# Add simple word
h.add('sillly')
h.spell('sillly')  # True

# Add word with affix inheritance
h.add('silllies', 'example')  # Inherits affix flags from 'example'
```
```

--------------------------------

### Integer Type Examples

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/types.md

Shows the use of integers for dictionary operation return codes and thread count configuration.

```python
from hunspell import Hunspell

h = Hunspell()

# Dictionary operation return code
ret: int = h.add('newword')

# Thread configuration
h.set_concurrency(4)
thread_count: int = h.max_threads  # Returns int
```

--------------------------------

### Dictionary Type Examples for Bulk Operations

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/types.md

Demonstrates the dictionary return type for bulk operations, mapping input words to their respective results.

```python
from hunspell import Hunspell

h = Hunspell()

# Bulk suggest returns dict
result: dict[str, tuple[str, ...]] = h.bulk_suggest(['correct', 'incorect'])
# {
#     'correct': ('correct',),
#     'incorect': ('incorrect', 'correction', 'corrector', 'correct', 'injector')
# }

# Bulk stem returns dict
result: dict[str, tuple[str, ...]] = h.bulk_stem(['stems', 'currencies'])
# {
#     'stems': ('stem',),
#     'currencies': ('currency',)
# }

# Bulk analyze returns dict
result: dict[str, tuple[str, ...]] = h.bulk_analyze(['dog', 'permanently'])
# {
#     'dog': (' st:dog',),
#     'permanently': (' st:permanent fl:Y',)
# }
```

--------------------------------

### Add Word

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/README.md

Adds a new word to the dictionary, optionally with an example.

```APIDOC
## add

### Description
Add a word to the dictionary.

### Method
`add(word: str, example: str | None = None) -> int`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
h.add('newword', 'This is a new word.')
```

### Response
#### Success Response (int)
- The number of words added (typically 1 if successful).

#### Response Example
```json
1
```
```

--------------------------------

### Check Cython Hunspell Version

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/api-reference/module.md

Import and print the installed version of the cython_hunspell library.

```python
from hunspell import __version__

print(f"Using cython_hunspell {__version__}")
```

--------------------------------

### Bulk Processing

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/api-reference/overview.md

Demonstrates using `set_concurrency` to configure the number of threads for parallel processing and `bulk_suggest` to efficiently get suggestions for multiple words.

```python
from hunspell import Hunspell

h = Hunspell('en_US')
h.set_concurrency(8)  # Use 8 threads

words = ['cat', 'dog', 'elephant', 'brd', 'fish']
results = h.bulk_suggest(words)

for word, suggestions in results.items():
    print(f"{word}: {suggestions}")
```

--------------------------------

### Bulk Suggest

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/README.md

Gets spelling suggestions for multiple words concurrently.

```APIDOC
## bulk_suggest

### Description
Get spelling suggestions for multiple words concurrently.

### Method
`bulk_suggest(words: list[str]) -> dict[str, tuple[str, ...]]`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
h.bulk_suggest(['word1', 'word2'])
```

### Response
#### Success Response (dict[str, tuple[str, ...]])
- A dictionary mapping each input word to its tuple of suggestions.

#### Response Example
```json
{
  "word1": ["suggestion1a", "suggestion1b"],
  "word2": ["suggestion2a"]
}
```
```

--------------------------------

### Suggestions & Alternatives

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/api-reference/overview.md

Get spelling suggestions or suffix-based word variants.

```APIDOC
## Suggestions & Alternatives

### Description
Get spelling suggestions or suffix-based word variants.

### Method Signatures
```python
h.suggest(word: str) -> tuple[str, ...]
h.suffix_suggest(word: str) -> tuple[str, ...]
```
```

--------------------------------

### Get Suffix Suggestions

Source: https://github.com/mseal/cython_hunspell/blob/master/README.md

Obtain suggestions based on a word's suffix, useful for inflected forms.

```python
h.suffix_suggest('do') # ('doing', 'doth', 'doer', 'doings', 'doers', 'doest')
```

--------------------------------

### Basic Spell Check

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/api-reference/overview.md

Demonstrates how to initialize Hunspell and check if a word is spelled correctly. If misspelled, it shows how to get suggestions.

```python
from hunspell import Hunspell

h = Hunspell()

if h.spell('word'):
    print("Correctly spelled")
else:
    print("Misspelled, suggestions:", h.suggest('word'))
```

--------------------------------

### add_with_affix

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/api-reference/hunspell.md

An alias for the `add` method, specifically designed for adding a word with explicit affix rules defined by an example word.

```APIDOC
## Method: `add_with_affix`

Alias for `add()` with explicit affix parameter.

```python
def add_with_affix(self, word: str, example: str) -> int
```

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| word | str | Yes | Word to add. |
| example | str | Yes | Example word whose affix rules apply. |

### Returns

`int`: Hunspell internal return code.

### Examples

```python
h = Hunspell()
h.add_with_affix('silllies', 'is:plural')
```
```

--------------------------------

### Get the Best Spelling Suggestion

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/quick-reference.md

A pattern to retrieve the top spelling suggestion for a word, defaulting to the original word if no suggestions are found.

```python
suggestions = h.suggest(word)
best = suggestions[0] if suggestions else word
```

--------------------------------

### Spell-Check Text and Get Suggestions

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/README.md

Split a given text into words, check the spelling of each word, and retrieve the first suggestion if a word is misspelled. This snippet demonstrates basic text spell-checking.

```python
text = "This is a tets of the sistem"
words = text.split()

for word in words:
    if not h.spell(word):
        suggestions = h.suggest(word)
        print(f"{word} -> {suggestions[0] if suggestions else '?'}")
```

--------------------------------

### Hunspell Instance Lifecycle and Cleanup

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/advanced-topics.md

Details the lifecycle of a Hunspell instance, from initialization (loading dictionaries, creating C++ objects, starting caches) to destruction (freeing memory, stopping caches). Explicit cleanup using `del` is optional.

```python
h = Hunspell('en_US')

# __init__ called:
# 1. Load dictionary .dic and .aff files
# 2. Create Hunspell C++ instance (malloc)
# 3. Initialize caches
# 4. Start cache manager

h.spell('test')

# __del__ called (when h goes out of scope):
# 1. Delete Hunspell C++ instance (free)
# 2. Free file path C strings
# 3. Stop cache manager

# Explicit Cleanup:
h = Hunspell('en_US')
# ... use h ...
del h  # Force cleanup (optional, happens anyway)
```

--------------------------------

### Add Word with Affix Inheritance

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/api-reference/hunspell.md

Adds a word to the dictionary and inherits morphological capabilities from an example word. Useful for handling related word forms.

```python
h = Hunspell()
# Add word with affix inheritance
h.add('silllies', 'example')  # Inherits affix flags from 'example'
```

--------------------------------

### Add Word with Explicit Affix

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/api-reference/hunspell.md

Adds a word to the dictionary, explicitly specifying an example word to inherit affix rules from. This is an alias for the `add` method.

```python
h = Hunspell()
h.add_with_affix('silllies', 'is:plural')
```

--------------------------------

### API Methods Reference

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/INDEX.txt

This section provides a detailed reference for all public API methods available in the Cython Hunspell library. It includes specifications for parameters, return types, error conditions, and code examples for each method.

```APIDOC
## API Reference

This document details the public API methods for the Cython Hunspell library.

### Spell Checking

**Method:** `spell(word)`

**Description:** Checks if a given word is spelled correctly according to the loaded dictionaries.

**Parameters:**
- **word** (string) - Required - The word to check.

**Return Type:**
- boolean - True if the word is spelled correctly, False otherwise.

### Suggestions

**Method:** `suggest(word)`

**Description:** Provides spelling suggestions for a given word.

**Parameters:**
- **word** (string) - Required - The word for which to generate suggestions.

**Return Type:**
- list of strings - A list of suggested corrections.

### Bulk Processing

**Method:** `bulk_suggest(words)`

**Description:** Processes a list of words to provide spelling suggestions for each.

**Parameters:**
- **words** (list of strings) - Required - A list of words to process.

**Return Type:**
- dict - A dictionary where keys are the input words and values are lists of suggestions.
```

--------------------------------

### Optimize Batch Word Suggestions

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/examples.md

Process a large list of words efficiently by dividing them into batches and using bulk suggestion. This method is suitable for high-throughput scenarios. Ensure Hunspell is installed and dictionaries are available for the specified language.

```python
from hunspell import Hunspell
import time

def process_batch_optimized(words, batch_size=1000, lang='en_US'):
    """Process large word list in optimized batches."""
    h = Hunspell(lang, disk_cache_dir='/tmp/hunspell_cache')
    h.set_concurrency(8)
    
    all_results = {}
    total_words = len(words)
    
    for batch_start in range(0, total_words, batch_size):
        batch_end = min(batch_start + batch_size, total_words)
        batch = words[batch_start:batch_end]
        
        # Process batch in bulk
        batch_results = h.bulk_suggest(batch)
        all_results.update(batch_results)
        
        # Progress
        processed = min(batch_end, total_words)
        print(f"Processed {processed}/{total_words} words")
        
        # Periodic cache save for long-running jobs
        if batch_end % 5000 == 0:
            h.save_cache()
    
    return all_results

# Usage
words = ['test', 'word'] * 500  # 1000 words
results = process_batch_optimized(words, batch_size=100)
```

--------------------------------

### Prepare and Push Release Tag

Source: https://github.com/mseal/cython_hunspell/blob/master/RELEASING.md

Clean the distribution directory, tag the release with the current version, and push the tags to the remote repository.

```bash
rm -rf dist
git tag `cat VERSION`
git push --tags
```

--------------------------------

### Bulk Operations with Concurrency

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/quick-reference.md

Demonstrates how to perform bulk operations like suggesting, stemming, analyzing, and generating variants efficiently using multiple threads.

```python
h.set_concurrency(8)  # Use 8 threads

h.bulk_suggest(['word1', 'word2'])      # Dict[str, Tuple[str]]
h.bulk_stem(['word1', 'word2'])         # Dict[str, Tuple[str]]
h.bulk_analyze(['word1', 'word2'])      # Dict[str, Tuple[str]]
h.bulk_suffix_suggest(['word1'])        # Dict[str, Tuple[str]]
```

--------------------------------

### Initialize Hunspell with Constructor Options

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/configuration.md

Instantiate Hunspell with language, cache manager, and directory settings. All options are passed directly to the Hunspell constructor.

```python
from hunspell import Hunspell

h = Hunspell(
    lang='en_US',
    cache_manager='hunspell',
    disk_cache_dir=None,
    hunspell_data_dir=None,
    system_encoding=None
)
```

--------------------------------

### Manual Cache Override for Debugging

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/advanced-topics.md

Illustrates how to manually set a cache entry for the suggest cache, allowing for debugging by forcing a specific return value for a given word.

```python
h = Hunspell('en_US')

# Manual override (debugging)
h._suggest_cache['manual'] = ('override1', 'override2')
print(h.suggest('manual'))  # Returns ('override1', 'override2')
```

--------------------------------

### Multi-Process Caching with Disk Cache

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/advanced-topics.md

Illustrates how to use persistent disk caching across multiple processes. Process 1 builds the cache, and Process 2 loads and uses the cached results instantly.

```python
# Process 1: Build cache
from hunspell import Hunspell
h = Hunspell('en_US', disk_cache_dir='/shared/cache')

words = ['test', 'word', 'example']
for word in words:
    h.suggest(word)

h.save_cache()  # Ensure saved before Process 2 starts

# Process 2: Use cached results
h2 = Hunspell('en_US', disk_cache_dir='/shared/cache')
result = h2.suggest('test')  # Loaded from cache (instant)
```

--------------------------------

### Error Handling for Dictionaries

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/quick-reference.md

Provides an example of how to catch and handle `HunspellFilePathError` during dictionary loading, with a fallback mechanism.

```python
try:
    h = Hunspell('en_GB')
except HunspellFilePathError as e:
    print(f"Dictionary error: {e}")
    h = Hunspell('en_US')  # Fallback
```

--------------------------------

### Configuration

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/INDEX.txt

Details on constructor options and environment variables for configuring Cyhunspell.

```APIDOC
## Configuration

### Description
This section covers the various options available for configuring the `cyhunspell` package, including constructor parameters and environment variables.

### Constructor Options

Refer to the `__init__` method documentation for a complete list of constructor parameters such as `lang`, `hunspell_path`, `cache_path`, `encoding`, `concurrency`, etc.

### Environment Variables

- **`HUNSPELL_DATA`**: Specifies the directory containing Hunspell dictionaries.
- **`HUNSPELL_PATH_ENCODING`**: Sets the encoding for paths related to Hunspell dictionaries.

### Dictionary Management

- **Built-in Dictionaries**: Information on available default dictionaries.
- **Custom Dictionaries**: Guidance on using user-provided dictionary files.
- **Caching**: Details on in-memory versus persistent caching strategies and synchronization.

### Platform-Specific Configuration

Notes on configuration nuances for different operating systems (Windows, Linux, macOS).

### Dictionary Encoding

Reference for supported dictionary encodings.

```

--------------------------------

### Get Language Code

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/api-reference/hunspell.md

Retrieves the language code of the currently loaded Hunspell dictionary. This is a read-only property.

```python
h = Hunspell('en_CA')
print(h.lang)  # 'en_CA'
```

--------------------------------

### Analyze Word Morphology

Source: https://github.com/mseal/cython_hunspell/blob/master/README.md

Get a morphological analysis of a word, including its base form and inflectional features.

```python
h.analyze('permanently') # (' st:permanent fl:Y',)
```

--------------------------------

### Cache Inspection and Mocking

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/types.md

Demonstrates how to inspect the contents of the suggestion cache after an operation and how to manually override cache entries for testing or debugging.

```python
from hunspell import Hunspell

h = Hunspell('en_US')

# Run operation to populate cache
h.suggest('test')

# Inspect cache contents
if 'test' in h._suggest_cache:
    print(h._suggest_cache['test'])

# Override cache for testing
h._suggest_cache['mocked'] = ('result1', 'result2')
print(h.suggest('mocked'))  # ('result1', 'result2')
```

--------------------------------

### Build and Test Extensions

Source: https://github.com/mseal/cython_hunspell/blob/master/RELEASING.md

Ensure extensions are built and tests pass before release. Requires Python >= 3.6.x and development dependencies.

```bash
python --version # Use >= 3.6.x
pip install -r requirements-dev.txt
python setup.py build_ext
# Remove the any accidentally added so files
rm -rf hunspell/*.so
pytest # Should pass with changes
```

--------------------------------

### Get Spelling Suggestions

Source: https://github.com/mseal/cython_hunspell/blob/master/README.md

Retrieve a tuple of suggested corrections for a misspelled word. Suggestions are sorted by relevance.

```python
h.suggest('incorect') # ('incorrect', 'correction', corrector', 'correct', 'injector')
```

--------------------------------

### Optional String Parameters with None

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/types.md

Illustrates how optional string parameters can be set to None to use default behaviors or omit features. Explicitly setting a parameter to None is equivalent to omitting it entirely.

```python
from hunspell import Hunspell

# None value uses defaults
h = Hunspell(disk_cache_dir=None)  # In-memory caching

# str value specifies custom path
h = Hunspell(disk_cache_dir='/tmp/cache')  # Persistent caching

# Optional parameter omission equivalent to None
h1 = Hunspell()  # disk_cache_dir defaults to None
h2 = Hunspell(disk_cache_dir=None)  # Explicit None, same as h1
```

--------------------------------

### Hunspell Constructor Options

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/quick-reference.md

Illustrates various options available when initializing the Hunspell class, including language, cache directory, custom dictionary paths, and system encoding.

```python
Hunspell(
    lang='en_US',                          # Language code
    disk_cache_dir='/tmp/cache',           # Persistent caching
    hunspell_data_dir='/path/to/dicts',   # Custom dictionaries
    system_encoding='UTF-8'                # Windows path encoding
)
```

--------------------------------

### Boolean Type Examples

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/types.md

Illustrates the boolean return values for spell checking operations, indicating whether a word is correctly spelled.

```python
from hunspell import Hunspell

h = Hunspell()

result: bool = h.spell('correct')  # True
result: bool = h.spell('incorect')  # False
```

--------------------------------

### Standard Hunspell Import

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/api-reference/module.md

Import the Hunspell class and initialize it with a default dictionary.

```python
from hunspell import Hunspell

h = Hunspell('en_US')
```

--------------------------------

### Shared and Separate Cache Managers

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/advanced-topics.md

Demonstrates how using the same cache manager name ('shared') leads to shared cache infrastructure, while different names ('other') result in separate infrastructure.

```python
# Same cache manager = shared cache infrastructure
h1 = Hunspell('en_US', cache_manager='shared')
h2 = Hunspell('en_GB', cache_manager='shared')

# Different cache managers = separate cache infrastructure
h3 = Hunspell('en_US', cache_manager='other')
```

--------------------------------

### Combine Base, File, and Runtime Dictionaries

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/examples.md

Construct a spellchecker that integrates a base language dictionary with terms from a custom dictionary file and individual terms added at runtime. Includes basic error handling for loading dictionary files.

```python
from hunspell import Hunspell

def create_combined_spellchecker(base_lang='en_US', 
                                custom_dict_file=None,
                                custom_terms=None):
    """Create spellchecker combining base, file, and runtime terms."""
    h = Hunspell(base_lang)
    
    # Load dictionary file if provided
    if custom_dict_file:
        try:
            h.add_dic(custom_dict_file)
        except Exception as e:
            print(f"Warning: Could not load {custom_dict_file}: {e}")
    
    # Add individual terms
    if custom_terms:
        for term in custom_terms:
            h.add(term)
    
    return h

h = create_combined_spellchecker(
    base_lang='en_US',
    custom_dict_file='/path/to/slang.dic',
    custom_terms=['y2k', 'lol', 'omg']
)
```

--------------------------------

### Custom Dictionary

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/api-reference/overview.md

Shows how to load a custom dictionary for a specific language or domain and add domain-specific words using `add()`.

```python
from hunspell import Hunspell
import os

# Load custom technical dictionary
h = Hunspell(
    lang='technical',
    hunspell_data_dir='/path/to/technical/dicts'
)

# Add domain-specific words
h.add('API')
h.add('microservices')

print(h.spell('API'))  # True
```

--------------------------------

### Get Spellchecker with Fallback

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/advanced-topics.md

This function attempts to load a spellchecker for a given language and falls back to a default language if the requested one is unavailable.

```python
from hunspell import Hunspell, HunspellFilePathError

def get_spellchecker(lang, fallback='en_US'):
    """Get spellchecker with fallback."""
    try:
        return Hunspell(lang)
    except HunspellFilePathError as e:
        print(f"Warning: {lang} not available, using {fallback}")
        return Hunspell(fallback)

h = get_spellchecker('fr_FR', 'en_US')  # Fallback if French unavailable
```

--------------------------------

### Add Dictionary

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/README.md

Loads an additional dictionary file (.dic and .aff).

```APIDOC
## add_dic

### Description
Load an additional dictionary.

### Method
`add_dic(dpath: str, key: str | None = None) -> int`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
h.add_dic('/path/to/custom.dic', 'custom_key')
```

### Response
#### Success Response (int)
- The number of dictionaries loaded (typically 1 if successful).

#### Response Example
```json
1
```
```

--------------------------------

### Initialize Hunspell

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/api-reference/hunspell.md

Instantiate Hunspell with default or custom language dictionaries and caching options. Use 'UTF-8' for system_encoding on Windows with UTF-8.

```python
from hunspell import Hunspell
h = Hunspell()
```

```python
h = Hunspell('en_CA')
```

```python
h = Hunspell(
    lang='en_GB-large',
    hunspell_data_dir='/path/to/custom/dicts',
    disk_cache_dir='/tmp/hunspell_cache'
)
```

```python
h = Hunspell(system_encoding='UTF-8')
```

--------------------------------

### Method Signatures - Dictionary and Cache Management

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/quick-reference.md

Provides type hints for methods related to adding/removing words, loading dictionaries, and managing the cache in Hunspell.

```python
add(word: str, example: str | None = None) -> int
remove(word: str) -> int
add_dic(dpath: str, key: str | None = None) -> int

set_concurrency(max_threads: int) -> None
save_cache() -> None
clear_cache() -> None
```

--------------------------------

### Check Text and Get Suggestions for Misspellings

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/examples.md

Checks text word-by-word and provides up to three spelling suggestions for each misspelled word. Useful for interactive spell-checking interfaces.

```python
from hunspell import Hunspell

def check_text_with_suggestions(text, lang='en_US'):
    """Check text and provide suggestions for misspelled words."""
    h = Hunspell(lang)
    words = text.split()
    
    corrections = []
    for word in words:
        if not h.spell(word):
            suggestions = h.suggest(word)
            corrections.append({
                'word': word,
                'suggestions': suggestions[:3]  # Top 3
            })
    
    return corrections

result = check_text_with_suggestions('I hav two tets')
for item in result:
    print(f"{item['word']}: {item['suggestions']}")
# hav: ('have', 'ham', 'hat')
# tets: ('tests', 'test', 'tent')
```

--------------------------------

### Method Signatures - Bulk Operations

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/quick-reference.md

Provides type hints for bulk operation methods in Hunspell, including suggestions and stemming for lists of words.

```python
bulk_suggest(words: list[str]) -> dict[str, tuple[str, ...]]
bulk_stem(words: list[str]) -> dict[str, tuple[str, ...]]
```

--------------------------------

### Incorrect Thread Safety Example

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/advanced-topics.md

Demonstrates an incorrect approach to using Hunspell in a multi-threaded environment. Avoid this pattern as the Hunspell C++ API is not thread-safe, leading to race conditions.

```python
from hunspell import Hunspell
import threading

h = Hunspell('en_US')

def worker(word):
    # ERROR: DO NOT do this - Hunspell is not thread-safe
    return h.spell(word)  # Race condition!

threads = [
    threading.Thread(target=worker, args=(w,)) 
    for w in ['test', 'word']
]
```

--------------------------------

### Extract Keywords using Stemming

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/README.md

Identify unique word stems from a given text. The `stem` method returns a list of stems for a word; this example uses the first stem as the root.

```python
text = "running runners run"
unique_stems = {}

for word in text.split():
    stems = h.stem(word)
    root = stems[0] if stems else word
    unique_stems.setdefault(root, []).append(word)

# Output: {'run': ['running', 'runners', 'run']}
```

--------------------------------

### Bulk Suggestion Processing

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/README.md

Demonstrates efficient processing of multiple words for suggestions using `bulk_suggest`. Configure the number of worker threads with `set_concurrency` for performance.

```python
words = ['dog', 'cat', 'bird', 'brd']
h.set_concurrency(8)
results = h.bulk_suggest(words)
# {'dog': ('dog',), 'brd': ('bird', 'bred', ...), ...}
```

--------------------------------

### Initialize Hunspell with Custom Dictionary Path

Source: https://github.com/mseal/cython_hunspell/blob/master/README.md

Load a Hunspell dictionary from a custom directory path, allowing the use of non-standard dictionaries.

```python
h = Hunspell('en_GB-large', hunspell_data_dir='/custom/dicts/dir')
```

--------------------------------

### Analyze Word with Special Characters

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/errors.md

Demonstrates how Cython Hunspell gracefully handles words containing special characters (like UTF-8) by converting them to an empty string during analysis. This snippet requires the 'hunspell' library to be installed.

```python
from hunspell import Hunspell

h = Hunspell('en_US')

# Handled gracefully - bad characters convert to empty string
result = h.analyze('café')  # UTF-8 word in dictionary
```

--------------------------------

### Dictionary Management

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/quick-reference.md

Shows how to add, remove, and load words and dictionaries with the Hunspell instance.

```python
h.add('word')                           # Add word
h.add('word', 'example')                # Add with affix
h.remove('word')                        # Remove word
h.add_dic('/path/to/custom.dic')        # Load additional dict
```

--------------------------------

### Load Technical Dictionary

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/examples.md

Create a spellchecker instance that includes a custom dictionary file containing technical terms. This allows the spellchecker to recognize domain-specific vocabulary. Ensure the dictionary file exists at the specified path.

```python
from hunspell import Hunspell
import os

def create_technical_spellchecker(base_lang='en_US', tech_dict_path=None):
    """Create spellchecker with technical terms."""
    h = Hunspell(base_lang)
    
    # Load technical dictionary if provided
    if tech_dict_path and os.path.exists(tech_dict_path):
        h.add_dic(tech_dict_path)
    
    return h

h = create_technical_spellchecker('en_US', '/path/to/technical.dic')

# Now technical terms are recognized
h.spell('microservices')  # True (if in technical dict)
```

--------------------------------

### Type Hinting for Hunspell Operations (Python < 3.9)

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/api-reference/overview.md

Demonstrates how to use type hints for Hunspell objects and method return values, including spell checking, suggestions, and bulk operations.

```python
from hunspell import Hunspell, HunspellFilePathError
from typing import Tuple, Dict, List

h: Hunspell = Hunspell('en_US')

# Spell check
is_correct: bool = h.spell('word')

# Suggestions
suggestions: Tuple[str, ...] = h.suggest('misspelled')

# Bulk operations
results: Dict[str, Tuple[str, ...]] = h.bulk_stem(['word1', 'word2'])

# Word lists
words: List[str] = ['one', 'two', 'three']
```

--------------------------------

### File Structure Overview

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/README.md

This code block outlines the directory structure of the cython_hunspell project, showing the location of README, API references, types, configuration, and error documentation.

```bash
Output Files:
├── README.md                          # This file
├── api-reference/
│   ├── overview.md                    # API overview and patterns
│   ├── hunspell.md                    # Hunspell class complete reference
│   ├── module.md                    # Module structure and exports
├── types.md                           # Data types reference
├── configuration.md                   # Constructor options and env vars
└── errors.md                          # Error types and handling
```

--------------------------------

### Initialize Hunspell with Asynchronous Caching

Source: https://github.com/mseal/cython_hunspell/blob/master/README.md

Configure Hunspell to use asynchronous caching by providing a directory path. This improves performance by caching suggestions and stems in the background.

```python
h = Hunspell(disk_cache_dir='/tmp/hunspell/cache/dir')
```

--------------------------------

### Initialize Hunspell with Caching Options

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/api-reference/overview.md

Instantiate Hunspell with in-memory caching or persistent disk caching for improved performance on subsequent runs.

```python
h = Hunspell('en_US')
h = Hunspell('en_US', disk_cache_dir='/tmp/cache')
```

--------------------------------

### Method Signatures - Basic Operations

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/quick-reference.md

Provides type hints for basic Hunspell methods like spell checking, suggesting, stemming, analyzing, and generating variants.

```python
spell(word: str) -> bool
suggest(word: str) -> tuple[str, ...]
stem(word: str) -> tuple[str, ...]
analyze(word: str) -> tuple[str, ...]
suffix_suggest(word: str) -> tuple[str, ...]
```

--------------------------------

### bulk_suggest

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/api-reference/hunspell.md

Retrieves suggestions for multiple words concurrently using multi-threading.

```APIDOC
## Method: `bulk_suggest`

Get suggestions for multiple words using multi-threaded processing.

```python
def bulk_suggest(self, words: list[str]) -> dict[str, tuple[str, ...]]
```

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| words | list[str] | Yes | List of words to get suggestions for. |

### Returns

`dict[str, tuple[str, ...]]`: Dictionary mapping each input word to a tuple of suggestions. Correctly spelled words map to themselves: `{'correct': ('correct',)}`.

### Examples

```python
h = Hunspell()
result = h.bulk_suggest(['correct', 'incorect'])
# {
#     'correct': ('correct',),
#     'incorect': ('incorrect', 'correction', 'corrector', 'correct', 'injector')
# }
```
```

--------------------------------

### Suggest Suffix-Based Words

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/api-reference/hunspell.md

Generate words by applying suffix and affix rules to a root word. Returns an empty tuple for an empty input string.

```python
h = Hunspell()
h.suffix_suggest('do')
# ('doing', 'doth', 'doer', 'doings', 'doers', 'doest')

h.suffix_suggest('cat')
# ('cater', 'cats', "cat's", 'caters')

h.suffix_suggest('')  # ()
```

--------------------------------

### Load Dictionary from Package

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/api-reference/module.md

Instantiate Hunspell using a dictionary pre-bundled within the package. Alternatively, set the HUNSPELL_DATA environment variable to specify a custom dictionary path.

```python
from hunspell import Hunspell

# Automatically loaded from package dictionaries
h = Hunspell('en_GB')

# Or explicitly specify with HUNSPELL_DATA:
import os
os.environ['HUNSPELL_DATA'] = '/path/to/hunspell/dictionaries'
h = Hunspell('en_AU')
```

--------------------------------

### Import Package Version

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/api-reference/module.md

Import and print the version string of the cython_hunspell package.

```python
from hunspell import __version__
print(__version__)  # e.g., '2.0.3'
```

--------------------------------

### Bulk Suffix Suggestion Requests

Source: https://github.com/mseal/cython_hunspell/blob/master/README.md

Execute suffix suggestions for a list of words in parallel. The output is a dictionary of word-to-suggestion mappings.

```python
h.bulk_suffix_suggest(['cat', 'do'])
# {'do': ('doing', 'doth', 'doer', 'doings', 'doers', 'doest'), 'cat': ('cater', 'cats', "cat's", 'caters')}
```

--------------------------------

### Import Hunspell Class

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/api-reference/module.md

Import the main Hunspell class for spell-checking functionality.

```python
from hunspell import Hunspell
```

--------------------------------

### Tuning Hunspell Concurrency for Performance

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/advanced-topics.md

Demonstrates how to test and tune the number of threads Hunspell uses for bulk operations to find optimal performance. This helps identify diminishing returns from excessive thread counts.

```python
import time
from hunspell import Hunspell

h = Hunspell('en_US')
words = ['word'] * 10000

# Test different thread counts
for threads in [1, 2, 4, 8, 16]:
    h.set_concurrency(threads)
    start = time.time()
    h.bulk_suggest(words)
    elapsed = time.time() - start
    print(f"{threads} threads: {elapsed:.2f}s")

# Output (example):
# 1 threads: 2.45s
# 2 threads: 1.35s
# 4 threads: 0.78s
# 8 threads: 0.42s
# 16 threads: 0.45s  (diminishing returns)
```

--------------------------------

### Add Word with Affix

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/README.md

Adds a word to the dictionary, inheriting affix properties.

```APIDOC
## add_with_affix

### Description
Add a word with affix inheritance.

### Method
`add_with_affix(word: str, example: str) -> int`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
h.add_with_affix('newword', 'example_word')
```

### Response
#### Success Response (int)
- The number of words added (typically 1 if successful).

#### Response Example
```json
1
```
```

--------------------------------

### Hunspell Constructor

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/api-reference/hunspell.md

Initializes a Hunspell instance with a specific language dictionary and optional caching configurations.

```APIDOC
## Hunspell Constructor: `__init__`

Initializes a Hunspell instance with a specific language dictionary.

### Parameters

- **lang** (str) - Optional - Default: 'en_US' - Language/dictionary code. Built-in options: en_AU, en_CA, en_GB, en_NZ, en_US, en_ZA. Custom dictionaries must be specified with hunspell_data_dir.
- **cache_manager** (str) - Optional - Default: 'hunspell' - Name of the cache manager to use for caching results.
- **disk_cache_dir** (str | None) - Optional - Default: None - Directory path for persistent disk-based caching. If not specified, caching is in-memory only. Enables asynchronous cache synchronization.
- **hunspell_data_dir** (str | None) - Optional - Default: None - Directory path containing .dic and .aff dictionary files. If None, uses built-in dictionary directory or HUNSPELL_DATA environment variable.
- **system_encoding** (str | None) - Optional - Default: None - Encoding for file paths on the system. If None, uses HUNSPELL_PATH_ENCODING environment variable or system locale. On Windows with UTF-8, use 'UTF-8'.

### Raises

- **HunspellFilePathError**: Required .dic or .aff file not found, not accessible, or path encoding does not match system locale.
- **MemoryError**: Insufficient memory to allocate internal Hunspell structures.

### Examples

```python
# Basic usage with default English dictionary
from hunspell import Hunspell
h = Hunspell()

# Canadian English
h = Hunspell('en_CA')

# Custom dictionary with persistent caching
h = Hunspell(
    lang='en_GB-large',
    hunspell_data_dir='/path/to/custom/dicts',
    disk_cache_dir='/tmp/hunspell_cache'
)

# Windows with UTF-8 encoding
h = Hunspell(system_encoding='UTF-8')
```
```

--------------------------------

### Hunspell Constructor Parameters

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/README.md

Defines the parameters available for the Hunspell constructor, including language, cache management, and directory configurations. Refer to the Configuration documentation for more details.

```python
Hunspell(
    lang: str = 'en_US',
    cache_manager: str = 'hunspell',
    disk_cache_dir: str | None = None,
    hunspell_data_dir: str | None = None,
    system_encoding: str | None = None
)
```

--------------------------------

### Benchmark Bulk Operations Concurrency

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/advanced-topics.md

Compares the performance of bulk suggesting words using different concurrency levels (single-threaded vs. multi-threaded).

```python
import time
from hunspell import Hunspell

h = Hunspell('en_US')
words = ['test', 'correct', 'incorect'] * 100

# Single-threaded
h.set_concurrency(1)
start = time.time()
h.bulk_suggest(words)
single_elapsed = time.time() - start

# Multi-threaded
h.set_concurrency(8)
start = time.time()
h.bulk_suggest(words)
multi_elapsed = time.time() - start

print(f"1 thread: {single_elapsed:.3f}s")
print(f"8 threads: {multi_elapsed:.3f}s")
print(f"Speedup: {single_elapsed / multi_elapsed:.1f}x")
```

--------------------------------

### Error Handling

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/api-reference/overview.md

Demonstrates how to handle `HunspellFilePathError` when a dictionary file is not found, with a fallback mechanism to load a default dictionary.

```python
from hunspell import Hunspell, HunspellFilePathError

def get_hunspell_instance(lang='en_US', fallback='en_US'):
    try:
        return Hunspell(lang)
    except HunspellFilePathError as e:
        print(f"Failed to load {lang}: {e}")
        if lang != fallback:
            return Hunspell(fallback)
        raise

h = get_hunspell_instance('custom_lang')
```

--------------------------------

### Add a Word with Affix Information

Source: https://github.com/mseal/cython_hunspell/blob/master/README.md

Add a word to the dictionary along with its affix information, such as pluralization rules.

```python
h.add('silllies', "is:plural")
```

--------------------------------

### Process Words and Monitor Memory

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/advanced-topics.md

This snippet demonstrates processing a large number of words and monitoring memory usage before and after clearing the cache.

```python
import tracemalloc

tracemalloc.start()
h = Hunspell('en_US')

# Process words
for word in ['test'] * 1000:
    h.suggest(word)

current, peak = tracemalloc.get_traced_memory()
print(f"Current: {current / 1024 / 1024:.1f}MB")
print(f"Peak: {peak / 1024 / 1024:.1f}MB")

h.clear_cache()  # Free cache memory
current, peak = tracemalloc.get_traced_memory()
print(f"After clear: {current / 1024 / 1024:.1f}MB")
```

--------------------------------

### Benchmark Hunspell Configurations

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/examples.md

Benchmarks the performance of different Hunspell configurations, including caching and threading options, by measuring the speed of bulk suggestions.

```python
from hunspell import Hunspell
import time

def benchmark_configurations(words, configs):
    """Benchmark different Hunspell configurations."""
    results = {}
    
    for config_name, kwargs in configs.items():
        h = Hunspell(**kwargs)
        
        start = time.time()
        h.bulk_suggest(words)
        elapsed = time.time() - start
        
        results[config_name] = {
            'time': elapsed,
            'rate': len(words) / elapsed
        }
    
    return results

words = ['test', 'word'] * 500

configs = {
    'no_cache': {'lang': 'en_US'},
    'with_disk_cache': {'lang': 'en_US', 'disk_cache_dir': '/tmp/cache'},
    'single_thread': {'lang': 'en_US'},
    'multi_thread': {'lang': 'en_US'},
}

# Adjust concurrency
configs['single_thread']['instance'] = lambda: Hunspell('en_US')  # TODO: adjust
configs['multi_thread']['instance'] = lambda: Hunspell('en_US')  # set_concurrency

results = benchmark_configurations(words, configs)
for config, result in results.items():
    print(f"{config}: {result['rate']:.0f} words/sec")
```

--------------------------------

### Bulk Suggestion with List Type

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/types.md

Demonstrates the use of a list of strings for bulk suggestion operations. The input list can be modified after the call without affecting the results, as the operation processes the list at the time of the call.

```python
from hunspell import Hunspell

h = Hunspell()

words: list[str] = ['dog', 'cat', 'bird']
result = h.bulk_suggest(words)

# Input list can be modified independently
words.append('new_word')

# Result is not affected by subsequent list changes
print(result)  # Still only has 'dog', 'cat', 'bird' keys
```

--------------------------------

### Using Hunspell Bulk Operations

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/advanced-topics.md

Illustrates how to leverage Hunspell's bulk operations for improved performance when processing a large number of words. The library handles threading internally for these operations.

```python
from hunspell import Hunspell

h = Hunspell('en_US')
h.set_concurrency(8)

# Bulk operations handle threading internally
results = h.bulk_suggest(['test', 'word', 'misspeled'])
```

--------------------------------

### Basic Hunspell Operations

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/quick-reference.md

Demonstrates fundamental spell checking, suggestion, stemming, morphological analysis, and variant generation using the Hunspell class.

```python
h = Hunspell('en_US')

# Check spelling
h.spell('word')  # True or False

# Get suggestions
h.suggest('incorect')  # ('incorrect', 'correction', ...)

# Extract stems
h.stem('running')  # ('run',)

# Morphological analysis
h.analyze('running')  # (' st:run fl:G',)

# Generate variants
h.suffix_suggest('cat')  # ('cats', 'cater', ...)
```

--------------------------------

### Persistent Caching

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/api-reference/overview.md

Shows how to enable disk-based caching for spell-checking results to improve performance across application restarts. The cache is automatically loaded on initialization and can be explicitly saved.

```python
from hunspell import Hunspell

h = Hunspell('en_US', disk_cache_dir='/tmp/hunspell_cache')

# First run: suggest() performs lookup and caches result
result = h.suggest('misspelled')

# Explicit save
h.save_cache()

# Process restart: cache is automatically loaded
# Subsequent suggest() calls are faster
```

--------------------------------

### Stemming Pipeline

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/api-reference/overview.md

Illustrates using `bulk_stem` to efficiently extract the base form (stem) of multiple words in a list.

```python
from hunspell import Hunspell

h = Hunspell()

words = ['running', 'walks', 'jumped', 'swimming']
stems = h.bulk_stem(words)

for word, stem_list in stems.items():
    print(f"{word} -> {stem_list[0] if stem_list else 'unknown'}")
```

--------------------------------

### Bulk Analysis Requests

Source: https://github.com/mseal/cython_hunspell/blob/master/README.md

Conduct morphological analysis on a list of words in parallel. The result is a dictionary mapping words to their analyses.

```python
h.bulk_analyze(['dog', 'permanently'])
# {'permanently': (' st:permanent fl:Y',), 'dog': (' st:dog',)}
```

--------------------------------

### suffix_suggest

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/api-reference/hunspell.md

Generates word suggestions based on suffixes and affix rules applied to a root word.

```APIDOC
## Method: `suffix_suggest`

Get suggestions based on word suffixes and affix rules.

### Parameters

- **word** (str) - Yes - Root word to generate suffix suggestions for. Empty string returns empty tuple.

### Returns

`tuple[str, ...]`: Words generated by applying suffix/affix rules to the input word.

### Examples

```python
h = Hunspell()
h.suffix_suggest('do')
# ('doing', 'doth', 'doer', 'doings', 'doers', 'doest')

h.suffix_suggest('cat')
# ('cater', 'cats', "cat's", 'caters')

h.suffix_suggest('')  # ()
```
```

--------------------------------

### Basic Hunspell Usage

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/README.md

Demonstrates basic spell checking, suggestion retrieval, and word stemming using the Hunspell class. Ensure the 'en_US' dictionary is available.

```python
from hunspell import Hunspell

h = Hunspell('en_US')

# Check spelling
h.spell('correct')  # True
h.spell('incorect')  # False

# Get suggestions
h.suggest('incorect')  # ('incorrect', 'correction', ...)

# Extract stems
h.stem('running')  # ('run',)
```

--------------------------------

### Configuring Path Encoding for Hunspell

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/advanced-topics.md

Shows how to specify the encoding used for file paths when initializing Hunspell, separate from the dictionary encoding. This is crucial for handling non-ASCII characters in paths.

```python
from hunspell import Hunspell

# Path encoding (separate from dictionary encoding)
h = Hunspell(
    lang='en_US',
    hunspell_data_dir='/path/with/café',  # Path itself
    system_encoding='UTF-8'  # How to encode path
)
```

--------------------------------

### Memory Monitoring with tracemalloc

Source: https://github.com/mseal/cython_hunspell/blob/master/_autodocs/advanced-topics.md

Shows how to integrate Python's `tracemalloc` module to monitor memory usage associated with Hunspell instances. This can be useful for debugging memory leaks or understanding memory footprint.

```python
import tracemalloc
from hunspell import Hunspell

tracemalloc.start()

h = Hunspell('en_US')
```