### Installation and Basic Usage

Source: https://github.com/wojciechmula/pyahocorasick/blob/master/README.rst

Demonstrates how to install the library and perform basic operations like adding words to an automaton, checking for word existence, and retrieving associated values.

```APIDOC
## Installation

To install pyahocorasick, you need a C compiler.

```bash
pip install pyahocorasick
```

## Basic Automaton Usage

This section shows how to create an automaton, add words, check for their existence, and retrieve associated values.

### Method

Python

### Endpoint

N/A (Library Usage)

### Parameters

N/A

### Request Example

```python
import ahocorasick

# Create an automaton
automaton = ahocorasick.Automaton()

# Add words with associated values
for idx, key in enumerate('he her hers she'.split()):
    automaton.add_word(key, (idx, key))

# Check if a word exists
print(f"'he' in automaton: {'he' in automaton}")
print(f"'HER' in automaton: {'HER' in automaton}")

# Get associated value for a word
print(f"automaton.get('he'): {automaton.get('he')}")
print(f"automaton.get('she'): {automaton.get('she')}")
print(f"automaton.get('cat', 'not exists'): {automaton.get('cat', 'not exists')}")

# Attempt to get a non-existent word (will raise KeyError)
try:
    automaton.get('dog')
except KeyError as e:
    print(f"automaton.get('dog') raised: {e}")
```

### Response Example

```
'he' in automaton: True
'HER' in automaton: False
automaton.get('he'): (0, 'he')
automaton.get('she'): (3, 'she')
automaton.get('cat', 'not exists'): not exists
automaton.get('dog') raised: "dog"
```
```

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

### Initialize Automaton with Configuration

Source: https://github.com/wojciechmula/pyahocorasick/blob/master/docs/index.md

Examples of initializing the Automaton class with different value and key type constants.

```python
import ahocorasick
# Default initialization
A = ahocorasick.Automaton()
# Explicit configuration
C = ahocorasick.Automaton(ahocorasick.STORE_INTS, ahocorasick.KEY_STRING)
```

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

### Install pyahocorasick

Source: https://context7.com/wojciechmula/pyahocorasick/llms.txt

Install the pyahocorasick library using pip. This command fetches and installs the latest version of the library and its dependencies.

```bash
pip install pyahocorasick
```

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

### Check for prefix existence using match()

Source: https://github.com/wojciechmula/pyahocorasick/blob/master/docs/automaton_match.md

This example demonstrates how to initialize an Automaton, add a word, and verify prefix matches using the match() method. It shows that match() returns True for partial strings of an existing key and False for non-matching strings.

```python
import ahocorasick
A = ahocorasick.Automaton()
A.add_word("example", True)
print(A.match("e"))       # True
print(A.match("example"))  # True
print(A.match("python"))   # False
```

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

### Python: Basic Automaton Usage and Search

Source: https://github.com/wojciechmula/pyahocorasick/blob/master/README.rst

Demonstrates how to install pyahocorasick, create an Automaton, add words with associated values, check for word existence, retrieve values, convert the trie to an automaton, and iterate through matches in a haystack string. It also shows how to pickle and unpickle the automaton.

```python
import ahocorasick

# Create an Automaton
automaton = ahocorasick.Automaton()

# Add words with associated values (insertion index, original string)
for idx, key in enumerate('he her hers she'.split()):
  automaton.add_word(key, (idx, key))

# Check if a string exists in the trie
print(f"'he' in automaton: {'he' in automaton}")
print(f"'HER' in automaton: {'HER' in automaton}")

# Get associated values
print(f"automaton.get('he'): {automaton.get('he')}")
print(f"automaton.get('she'): {automaton.get('she')}")
print(f"automaton.get('cat', 'not exists'): {automaton.get('cat', 'not exists')}")

try:
    automaton.get('dog')
except KeyError:
    print("automaton.get('dog') raised KeyError as expected")

# Convert the trie to an Aho-Corasick automaton
automaton.make_automaton()

# Search for occurrences in a haystack string
haystack = "she sells seashells by the seashore"
print("\nSearching in haystack:", haystack)
for end_index, (insert_order, original_value) in automaton.iter(haystack):
    start_index = end_index - len(original_value) + 1
    print((start_index, end_index, (insert_order, original_value)))
    assert haystack[start_index:start_index + len(original_value)] == original_value

# Pickle and unpickle the automaton
import pickle
pickled = pickle.dumps(automaton)
B = pickle.loads(pickled)
print(f"\nB.get('he'): {B.get('he')}")
```

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

### find_all(string, callback, [start, [end]])

Source: https://github.com/wojciechmula/pyahocorasick/blob/master/docs/automaton_find_all.md

Performs an Aho-Corasick search on the input string and calls a callback function for each match found. Supports optional start and end indices to limit the search range.

```APIDOC
## find_all(string, callback, [start, [end]])

### Description
Performs the Aho-Corasick search procedure using the provided input `string` and iterates over the matching tuples (`end_index`, `value`) for keys found in the string. Invokes the `callback` callable for each matching tuple.

The callback callable must accept two positional arguments: `end_index` (the end index in the input string where a trie key string was found) and `value` (the value associated with the found key string).

The `start` and `end` optional arguments can be used to limit the search to an input string slice as in `string[start:end]`.

Equivalent to a loop on `iter()` calling a callable at each iteration.

### Method
N/A (This is a method of an AhoCorasick object, not a standalone API endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import ahocorasick

A = ahocorasick.Automaton()
for end, (keyword, value) in enumerate(keywords.items()):
    A.add_word(keyword, (end, value))
A.make_automaton()

def print_match(end_index, value):
    print(f"Found '{value[1]}' at index {end_index}")

A.find_all("test string with keywords", print_match)
```

### Response
#### Success Response (N/A - callback is invoked)
This method does not return a value directly. Instead, it invokes a callback function for each match found.

#### Response Example
(Callback invocation examples)
```
Found 'test' at index 3
Found 'string' at index 9
```
```

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

### Get Value by Key with Default using PyAHOCORASICK

Source: https://context7.com/wojciechmula/pyahocorasick/llms.txt

Shows how to retrieve a value associated with a key using the get() method. It supports providing a default value to return if the key is not found, similar to Python's dictionary get() behavior. A KeyError is raised if the key is absent and no default is specified.

```python
import ahocorasick

A = ahocorasick.Automaton()
A.add_word("python", {"version": 3.9, "type": "language"})
A.add_word("java", {"version": 17, "type": "language"})

# Get existing key
print(A.get("python"))
# Output: {'version': 3.9, 'type': 'language'}

# Get with default for missing key
print(A.get("ruby", "not found"))
# Output: not found

# KeyError for missing key without default
try:
    A.get("rust")
except KeyError:
    print("Key 'rust' not found")
# Output: Key 'rust' not found
```

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

### Perform Longest Match Search with pyahocorasick

Source: https://github.com/wojciechmula/pyahocorasick/blob/master/docs/automaton_iter_long.md

This example demonstrates how to initialize an Automaton, add words to it, and use the iter_long method to find the longest matching keys in a target string. It compares the output of iter_long against the standard iter method to highlight the difference in results.

```python
import ahocorasick
A = ahocorasick.Automaton()
A.add_word("he", "he")
A.add_word("her", "her")
A.add_word("here", "here")
A.make_automaton()
needle = "he here her"
# Returns only the longest matches
print(list(A.iter_long(needle)))
# Returns all matches including substrings
print(list(A.iter(needle)))
```

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

### get(key[, default])

Source: https://context7.com/wojciechmula/pyahocorasick/llms.txt

Retrieves the value associated with a given key string from the automaton. If the key is not found and a default value is provided, it returns the default value. Otherwise, it raises a KeyError.

```APIDOC
## get(key[, default])

### Description
Return the value associated with a key string. Raises KeyError if the key is not found and no default is provided. Similar to dict.get() behavior.

### Method
GET

### Endpoint
`/api/ahocorasick/get/{key}`

### Parameters
#### Path Parameters
- **key** (string) - Required - The key to retrieve the value for.

#### Query Parameters
- **default** (any) - Optional - The default value to return if the key is not found.

#### Request Body
None

### Request Example
```python
import ahocorasick

A = ahocorasick.Automaton()
A.add_word("python", {"version": 3.9, "type": "language"})
A.add_word("java", {"version": 17, "type": "language"})

# Example API call (conceptual)
# response_python = api.get('/api/ahocorasick/get/python')
# response_ruby = api.get('/api/ahocorasick/get/ruby', params={'default': 'not found'})

# Direct library usage for demonstration:
print(A.get("python"))
print(A.get("ruby", "not found"))
try:
    A.get("rust")
except KeyError:
    print("Key 'rust' not found")
```

### Response
#### Success Response (200)
- **value** (any) - The value associated with the key, or the default value if provided and the key is not found.

#### Response Example
```json
{
  "value": {"version": 3.9, "type": "language"}
}
```

#### Error Response (404)
- **error** (string) - "Key not found"

#### Error Response Example
```json
{
  "error": "Key not found"
}
```
```

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

### iter(string, [start, [end]], ignore_white_space=False)

Source: https://context7.com/wojciechmula/pyahocorasick/llms.txt

Details the `iter` method for performing Aho-Corasick searches, returning all matches with their end positions and associated values. It also covers substring searching and whitespace handling.

```APIDOC
## iter(string, [start, [end]], ignore_white_space=False)

Perform Aho-Corasick search on the input string, returning an iterator of (end_index, value) tuples for each match found. The optional start and end parameters limit the search to a substring. Setting ignore_white_space=True skips whitespace characters.

### Parameters
#### Path Parameters
- **string** (string) - Required - The text to search within.
- **start** (int) - Optional - The starting index of the substring to search.
- **end** (int) - Optional - The ending index of the substring to search.
- **ignore_white_space** (bool) - Optional - If True, whitespace characters are ignored during the search. Defaults to False.

### Response
#### Success Response (200)
- **end_index** (int) - The index in the input string where the match ends.
- **value** (any) - The value associated with the matched key.

### Request Example
```python
import ahocorasick

A = ahocorasick.Automaton()
for idx, word in enumerate(['he', 'she', 'his', 'hers']):
    A.add_word(word, (idx, word))
A.make_automaton()

haystack = "ushers"

# Search and extract matches with positions
for end_index, (idx, word) in A.iter(haystack):
    start_index = end_index - len(word) + 1
    print(f"Found '{word}' at position {start_index}-{end_index}")
# Output:
# Found 'she' at position 1-3
# Found 'he' at position 2-3
# Found 'hers' at position 2-5

# Search within a substring (positions 0 to 3)
for end_index, (idx, word) in A.iter(haystack, 0, 4):
    print(f"Found '{word}' ending at {end_index}")
# Output:
# Found 'she' at position 3
# Found 'he' at position 3
```
```

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

### Get Longest Prefix Length using Aho-Corasick (Python)

Source: https://github.com/wojciechmula/pyahocorasick/blob/master/docs/automaton_longest_prefix.md

The longest_prefix function returns the length of the longest prefix of a given string that is present in the Aho-Corasick automaton. This is useful for pattern matching scenarios where you need to identify the longest valid starting sequence.

```Python
import ahocorasick
A = ahocorasick.Automaton()
A.add_word("he", True)
A.add_word("her", True)
A.add_word("hers", True)
print(A.longest_prefix("she"))
print(A.longest_prefix("herself"))
```

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

### Initialize Automaton instances with various configurations

Source: https://github.com/wojciechmula/pyahocorasick/blob/master/docs/automaton_constructor.md

Demonstrates how to create new Automaton objects using default settings or specific storage and key type constants. These instances are used as the base for building the trie structure for pattern matching.

```python
import ahocorasick

# Default initialization
A = ahocorasick.Automaton()

# Initialize with explicit value storage type
B = ahocorasick.Automaton(ahocorasick.STORE_ANY)

# Initialize with specific value and key types
C = ahocorasick.Automaton(ahocorasick.STORE_INTS, ahocorasick.KEY_STRING)
```

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

### Initialize Automaton in Python

Source: https://context7.com/wojciechmula/pyahocorasick/llms.txt

Demonstrates how to create an Automaton object with different configurations. Options include storing any Python object, storing only integers for memory efficiency, or automatically storing the length of each key. It also shows how to use integer sequences as keys.

```python
import ahocorasick

# Default automaton - stores any Python object as values
A = ahocorasick.Automaton()

# Automaton that only stores integers (more memory efficient)
B = ahocorasick.Automaton(ahocorasick.STORE_INTS)

# Automaton that auto-stores the length of each key as its value
C = ahocorasick.Automaton(ahocorasick.STORE_LENGTH)

# Automaton with integer sequences as keys instead of strings
D = ahocorasick.Automaton(ahocorasick.STORE_ANY, ahocorasick.KEY_SEQUENCE)
```

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

### GET /stats

Source: https://context7.com/wojciechmula/pyahocorasick/llms.txt

Retrieve internal statistics about the automaton structure.

```APIDOC
## GET /stats

### Description
Return a dictionary containing statistics about the automaton including node count, word count, and memory usage.

### Method
GET

### Endpoint
/stats

### Response
#### Success Response (200)
- **nodes_count** (int) - Number of nodes in the trie.
- **words_count** (int) - Number of words stored.
- **total_size** (int) - Total memory size in bytes.

#### Response Example
{
  "nodes_count": 8,
  "words_count": 4,
  "total_size": 376
}
```

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

### GET /iter

Source: https://github.com/wojciechmula/pyahocorasick/blob/master/docs/automaton_iter.md

Performs an Aho-Corasick search on a provided string and returns an iterator of matches.

```APIDOC
## GET /iter

### Description
Perform the Aho-Corasick search procedure using the provided input string to find all occurrences of keys stored in the trie.

### Method
GET

### Endpoint
/iter

### Parameters
#### Query Parameters
- **string** (string) - Required - The input string to search within.
- **start** (integer) - Optional - The starting index for the search slice.
- **end** (integer) - Optional - The ending index for the search slice.
- **ignore_white_space** (boolean) - Optional - Whether to ignore white spaces in the input string. Defaults to False.

### Request Example
GET /iter?string=example_text&start=0&end=10

### Response
#### Success Response (200)
- **iterator** (tuple) - Returns an iterator of (end_index, value) tuples where end_index is the position in the string and value is the associated key value.

#### Response Example
[
  [5, "value1"],
  [12, "value2"]
]
```

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

### Automaton Constructor

Source: https://context7.com/wojciechmula/pyahocorasick/llms.txt

Demonstrates how to create an Automaton object with different configurations for storing values and keys.

```APIDOC
## Automaton Constructor

Create a new empty Automaton with optional value_type (STORE_ANY, STORE_INTS, STORE_LENGTH) and key_type (KEY_STRING, KEY_SEQUENCE). The default configuration stores any Python object as values with string keys.

### Request Example
```python
import ahocorasick

# Default automaton - stores any Python object as values
A = ahocorasick.Automaton()

# Automaton that only stores integers (more memory efficient)
B = ahocorasick.Automaton(ahocorasick.STORE_INTS)

# Automaton that auto-stores the length of each key as its value
C = ahocorasick.Automaton(ahocorasick.STORE_LENGTH)

# Automaton with integer sequences as keys instead of strings
D = ahocorasick.Automaton(ahocorasick.STORE_ANY, ahocorasick.KEY_SEQUENCE)
```
```

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

### Create and Populate Automaton

Source: https://github.com/wojciechmula/pyahocorasick/blob/master/docs/index.md

Initialize an Automaton instance and populate it with keys and associated values to act as a trie.

```python
import ahocorasick
automaton = ahocorasick.Automaton()
for idx, key in enumerate('he her hers she'.split()):
    automaton.add_word(key, (idx, key))
```

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

### GET /values

Source: https://context7.com/wojciechmula/pyahocorasick/llms.txt

Retrieve an iterator over values associated with keys in the automaton, with optional filtering by prefix.

```APIDOC
## GET /values

### Description
Returns an iterator over values associated with keys. Supports optional prefix, wildcard, and how arguments.

### Method
GET

### Endpoint
/values

### Parameters
#### Query Parameters
- **prefix** (string) - Optional - Filter keys starting with this prefix.
- **wildcard** (string) - Optional - Character to treat as a wildcard.
- **how** (int) - Optional - Iteration mode.

### Request Example
GET /values?prefix=d

### Response
#### Success Response (200)
- **values** (list) - List of values associated with the filtered keys.

#### Response Example
[
  {"species": "canine", "legs": 4},
  {"species": "avian", "legs": 2}
]
```

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

### Save and Load Automaton

Source: https://context7.com/wojciechmula/pyahocorasick/llms.txt

Demonstrates persisting the automaton to disk using custom serializers and deserializers.

```python
import ahocorasick
import pickle

A = ahocorasick.Automaton()
A.add_word("python", {"id": 1})
A.make_automaton()

# Save to file
A.save("automaton.bin", pickle.dumps)

# Load from file
B = ahocorasick.load("automaton.bin", pickle.loads)
```

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

### GET /automaton/stats

Source: https://github.com/wojciechmula/pyahocorasick/blob/master/docs/automaton_get_stats.md

Retrieves internal statistics for the current Automaton instance, including node counts, word counts, and memory usage.

```APIDOC
## GET /automaton/stats

### Description
Returns a dictionary containing statistics about the current Automaton trie structure, including node counts, word counts, and memory footprint.

### Method
GET

### Endpoint
/automaton/stats

### Parameters
None

### Request Example
N/A (Method call on object)

### Response
#### Success Response (200)
- **nodes_count** (int) - Total number of nodes in the trie.
- **words_count** (int) - Number of distinct words inserted.
- **longest_word** (int) - Length of the longest word in the automaton.
- **links_count** (int) - Number of edges between nodes.
- **sizeof_node** (int) - Size of a single node in bytes.
- **total_size** (int) - Total estimated size of the trie in bytes.

#### Response Example
{
  "nodes_count": 5,
  "words_count": 3,
  "longest_word": 4,
  "links_count": 4,
  "sizeof_node": 40,
  "total_size": 232
}
```

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

### iter_long(string, [start, [end]])

Source: https://context7.com/wojciechmula/pyahocorasick/llms.txt

Explains the `iter_long` method, which finds the longest non-overlapping matches in the input string, preventing shorter matches within longer ones at the same position.

```APIDOC
## iter_long(string, [start, [end]])

Perform modified Aho-Corasick search that returns only the longest non-overlapping matches. Unlike iter(), this method won't return shorter substrings when a longer match is found at the same position.

### Parameters
#### Path Parameters
- **string** (string) - Required - The text to search within.
- **start** (int) - Optional - The starting index of the substring to search.
- **end** (int) - Optional - The ending index of the substring to search.

### Response
#### Success Response (200)
- **end_index** (int) - The index in the input string where the match ends.
- **value** (any) - The value associated with the matched key.

### Request Example
```python
import ahocorasick

A = ahocorasick.Automaton()
A.add_word("he", "he")
A.add_word("her", "her")
A.add_word("here", "here")
A.make_automaton()

needle = "he here her"

# Standard iter() returns all matches including overlapping
print("iter() results:", list(A.iter(needle)))
# Output: [(1, 'he'), (4, 'he'), (5, 'her'), (6, 'here'), (9, 'he'), (10, 'her')]

# iter_long() returns only the longest non-overlapping matches
print("iter_long() results:", list(A.iter_long(needle)))
# Output: [(1, 'he'), (6, 'here'), (10, 'her')]
```
```

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

### Persist Automaton State with Pickle

Source: https://github.com/wojciechmula/pyahocorasick/blob/master/docs/index.md

Illustrates how to save and load an Automaton instance using the standard Python pickle protocol.

```python
import ahocorasick
import pickle

# save current state
with open(path, 'wb') as f:
    pickle.dump(A, f)

# load saved state
with open(path, 'rb') as f:
    B = pickle.load(f)
```

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

### Perform Advanced Key Searches with Wildcards

Source: https://github.com/wojciechmula/pyahocorasick/blob/master/docs/index.md

Demonstrates searching for keys in the automaton using wildcard characters and different matching constraints.

```python
import ahocorasick
A = ahocorasick.Automaton()
for index, word in enumerate('cat catastropha rat rate bat'.split()):
    A.add_word(word, (index, word))

# Search with wildcards
list(A.keys('?at', '?', ahocorasick.MATCH_EXACT_LENGTH))
list(A.keys('?at?', '?', ahocorasick.MATCH_AT_MOST_PREFIX))
```

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

### Retrieve Values by Prefix

Source: https://context7.com/wojciechmula/pyahocorasick/llms.txt

Demonstrates how to retrieve values associated with keys in the automaton, optionally filtering by a prefix.

```python
import ahocorasick

A = ahocorasick.Automaton()
A.add_word("dog", {"species": "canine", "legs": 4})
A.add_word("cat", {"species": "feline", "legs": 4})
A.add_word("duck", {"species": "avian", "legs": 2})

# Get all values
print(list(A.values()))

# Get values for keys starting with 'd'
print(list(A.values("d")))
```

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

### Clear Trie Data Structure

Source: https://github.com/wojciechmula/pyahocorasick/blob/master/docs/index.md

The clear() method removes all keys from the trie, invalidating any existing iterators. This is useful for resetting the automaton before adding new words or starting a fresh search.

```python
>>> import ahocorasick
>>> A = ahocorasick.Automaton()
>>> A.add_word("cat", 1)
True
>>> A.add_word("dog", 2)
True
>>> A.add_word("elephant", 3)
True
>>> len(A)
3
>>> A.clear()
>>> len(A)
0
```

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

### Get Automaton Memory Size

Source: https://github.com/wojciechmula/pyahocorasick/blob/master/docs/index.md

This method returns the approximate memory size in bytes occupied by the Automaton instance. This excludes the size of associated objects when the Automaton is created with Automaton() or Automaton(ahocorasick.STORE_ANY).

```python
>>> import ahocorasick
>>> A = ahocorasick.Automaton()
>>> A.add_word("example", 1)
>>> A.make_automaton()
>>> size_in_bytes = A.get_size()
>>> isinstance(size_in_bytes, int)
True
>>> size_in_bytes > 0
True
```

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

### Serialize and Load Automaton State

Source: https://github.com/wojciechmula/pyahocorasick/blob/master/docs/index.md

Demonstrates how to persist an automaton to a file and reload it. This requires a serialization callable like pickle.loads when using STORE_ANY.

```python
import ahocorasick
import pickle

# Saving an automaton
A.save(path, pickle.dumps)

# Loading an automaton
B = ahocorasick.load(path, pickle.loads)
```

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

### Perform incremental searching with AutomatonSearchIter

Source: https://context7.com/wojciechmula/pyahocorasick/llms.txt

Demonstrates how to search for patterns across multiple string chunks while maintaining the automaton state, or resetting it for independent searches.

```python
import ahocorasick

A = ahocorasick.Automaton()
A.add_word("error", "ERROR")
A.add_word("warning", "WARNING")
A.make_automaton()

chunks = ["This is an err", "or message with war", "ning inside"]
it = A.iter("")
for chunk in chunks:
    it.set(chunk)
    for end_idx, value in it:
        print(f"Found: {value}")

strings = ["error occurred", "warning issued", "all clear"]
it = A.iter("")
for s in strings:
    it.set(s, reset=True)
    for end_idx, value in it:
        print(f"In '{s}': found {value}")
```

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

### Get Trie Size with len() in Python

Source: https://github.com/wojciechmula/pyahocorasick/blob/master/docs/automaton_len.md

Demonstrates how to use the len() function to retrieve the number of distinct keys currently stored in a Pyahocorasick automaton. This function is essential for tracking the number of words or patterns added to the trie.

```Python
import ahocorasick
A = ahocorasick.Automaton()
len(A)
# Output: 0
A.add_word("python", 1)
len(A)
# Output: 1
A.add_word("elephant", True)
len(A)
# Output: 2
```

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

### add_word(key, [value])

Source: https://context7.com/wojciechmula/pyahocorasick/llms.txt

Explains how to add keys (strings or sequences) to the automaton and associate them with values. It also details the return value and behavior for existing keys.

```APIDOC
## add_word(key, [value]) -> bool

Add a key string to the trie and associate it with a value. Returns True if the key was newly inserted, False if it already existed (value is replaced). The value parameter is required for STORE_ANY, optional for STORE_INTS (defaults to insertion order), and not allowed for STORE_LENGTH.

### Parameters
#### Path Parameters
- **key** (string or sequence) - Required - The key to add to the automaton.
- **value** (any) - Optional - The value associated with the key. Behavior depends on Automaton configuration.

### Request Example
```python
import ahocorasick

A = ahocorasick.Automaton()

# Add words with associated values (any Python object)
A.add_word("python", ("lang", 1))
# Returns: True

A.add_word("java", ("lang", 2))
# Returns: True

A.add_word("javascript", ("lang", 3))
# Returns: True

# Adding existing key returns False, but updates the value
A.add_word("python", ("updated", 100))
# Returns: False

# With STORE_INTS, value is optional (auto-increments)
B = ahocorasick.Automaton(ahocorasick.STORE_INTS)
B.add_word("cat")  # value = 1
B.add_word("dog")  # value = 2
B.add_word("bird", 42)  # explicit value = 42
```
```

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

### keys([prefix, [wildcard, [how]]])

Source: https://github.com/wojciechmula/pyahocorasick/blob/master/docs/automaton_keys.md

Returns an iterator over the keys stored in the automaton. Supports filtering by prefix, wildcard matching, and different matching strategies.

```APIDOC
## GET /keys

### Description
Retrieves an iterator for all keys within the Aho-Corasick automaton. This method allows for flexible filtering based on prefixes, wildcards, and specific matching lengths.

### Method
GET

### Endpoint
/keys

### Parameters
#### Query Parameters
- **prefix** (string) - Optional - If provided, only keys starting with this prefix are yielded.
- **wildcard** (string) - Optional - A single character string used as a wildcard within the prefix pattern.
- **how** (integer) - Optional - Controls the matching strategy. Possible values:
  - `ahocorasick.MATCH_EXACT_LENGTH` (default): Yields matches with the exact length of the prefix.
  - `ahocorasick.MATCH_AT_LEAST_PREFIX`: Yields matches with a length greater than or equal to the prefix length.
  - `ahocorasick.MATCH_AT_MOST_PREFIX`: Yields matches with a length less than or equal to the prefix length.

### Request Example
```json
{
  "prefix": "app",
  "wildcard": "?",
  "how": 1
}
```

### Response
#### Success Response (200)
- **iterator** (iterator) - An iterator yielding matching keys (strings).

#### Response Example
```json
["apple", "apply", "application"]
```
```

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

### Stream Searching with AutomatonSearchIter

Source: https://github.com/wojciechmula/pyahocorasick/blob/master/docs/index.md

Shows how to use the AutomatonSearchIter class to process data streams by updating the search string while maintaining the automaton state.

```python
it = A.iter(b"")
while True:
    buffer = receive(server_address, 4096)
    if not buffer:
        break
    it.set(buffer)
    for index, value in it:
        print(index, '=>', value)
```

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

### Persist Automaton State with Custom Save/Load

Source: https://github.com/wojciechmula/pyahocorasick/blob/master/docs/index.md

Demonstrates using the built-in save method with a serializer to reduce memory overhead compared to standard pickling.

```python
import ahocorasick
import pickle

# save current state
A.save(path, pickle.dumps)
```

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

### Get Automaton Statistics using Python

Source: https://github.com/wojciechmula/pyahocorasick/blob/master/docs/automaton_get_stats.md

This Python code snippet demonstrates how to use the get_stats() method of an ahocorasick.Automaton object. It initializes an automaton, adds words, and then retrieves and prints statistics such as node count, word count, longest word, link count, and total size.

```python
>>> import ahocorasick
>>> A = ahocorasick.Automaton()
>>> A.add_word("he", None)
True
>>> A.add_word("her", None)
True
>>> A.add_word("hers", None)
True
>>> A.get_stats()
{'nodes_count': 5, 'words_count': 3, 'longest_word': 4, 'links_count': 4, 'sizeof_node': 40, 'total_size': 232}
```

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

### Persistence Methods

Source: https://github.com/wojciechmula/pyahocorasick/blob/master/docs/index.md

Methods for saving and loading the state of an Automaton instance.

```APIDOC
## Persistence

### Description
Save and load the Automaton state using pickle or custom save/load methods.

### Methods
- `save(path, serializer)`: Save the automaton to a file.
- `load(path, deserializer)`: Load the automaton from a file.

### Warning
Loaded data is not inherently safe; ensure the source is trusted.
```

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

### Perform Wildcard Search in Automaton

Source: https://github.com/wojciechmula/pyahocorasick/blob/master/docs/index.md

Demonstrates how to use the keys method with a wildcard character to perform pattern matching similar to glob or regex.

```python
automaton.keys("hi?", "?")  # would match "him", "his"
automaton.keys("XX?", "X")  # would match "me?", "he?" or "it?"
```

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

### Iterate Matches with iter() in Python

Source: https://context7.com/wojciechmula/pyahocorasick/llms.txt

Demonstrates how to use the iter() method for Aho-Corasick search. It returns an iterator of (end_index, value) tuples for all matches found in the input string. Optional start and end parameters can limit the search range, and ignore_white_space can be set to True to skip whitespace.

```python
import ahocorasick

A = ahocorasick.Automaton()
for idx, word in enumerate(['he', 'she', 'his', 'hers']):
    A.add_word(word, (idx, word))
A.make_automaton()

haystack = "ushers"

# Search and extract matches with positions
for end_index, (idx, word) in A.iter(haystack):
    start_index = end_index - len(word) + 1
    print(f"Found '{word}' at position {start_index}-{end_index}")
# Output:
# Found 'she' at position 1-3
# Found 'he' at position 2-3
# Found 'hers' at position 2-5

# Search within a substring (positions 0 to 3)
for end_index, (idx, word) in A.iter(haystack, 0, 4):
    print(f"Found '{word}' ending at {end_index}")
# Output:
# Found 'she' at position 3
# Found 'he' at position 3
```

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

### Method: set(string, reset=False)

Source: https://github.com/wojciechmula/pyahocorasick/blob/master/docs/automaton_search_iter_set.md

Configures the automaton with a new string to search, supporting both single-pass and chunked processing.

```APIDOC
## POST /automaton/set

### Description
Sets a new string to be searched by the Aho-Corasick automaton. This method allows for processing large strings in smaller chunks by maintaining the internal state.

### Method
POST

### Endpoint
/automaton/set

### Parameters
#### Request Body
- **string** (string) - Required - The input string to search.
- **reset** (boolean) - Optional - If True, resets the automaton state and index. Defaults to False.

### Request Example
{
  "string": "search_text_chunk",
  "reset": false
}

### Response
#### Success Response (200)
- **status** (string) - Indicates the operation was successful.

#### Response Example
{
  "status": "success"
}
```

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

### keys([prefix, [wildcard, [how]]])

Source: https://context7.com/wojciechmula/pyahocorasick/llms.txt

Returns an iterator over all keys in the trie. Supports optional filtering by prefix, wildcard pattern matching, and control over match behavior.

```APIDOC
## keys([prefix, [wildcard, [how]]])

### Description
Return an iterator over all keys in the trie. Optional prefix filters keys, wildcard enables pattern matching, and how controls match behavior (MATCH_EXACT_LENGTH, MATCH_AT_LEAST_PREFIX, MATCH_AT_MOST_PREFIX).

### Method
GET

### Endpoint
`/api/ahocorasick/keys`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **prefix** (string) - Optional - Filters keys that start with this prefix.
- **wildcard** (string) - Optional - A character used for wildcard matching (e.g., '?').
- **how** (string) - Optional - Controls match behavior. Possible values: "MATCH_EXACT_LENGTH", "MATCH_AT_LEAST_PREFIX", "MATCH_AT_MOST_PREFIX".

#### Request Body
None

### Request Example
```python
import ahocorasick

A = ahocorasick.Automaton()
for word in ['cat', 'car', 'card', 'care', 'careful', 'bat', 'bar']:
    A.add_word(word, word)

# Example API calls (conceptual)
# response_all = api.get('/api/ahocorasick/keys')
# response_prefix = api.get('/api/ahocorasick/keys', params={'prefix': 'car'})
# response_wildcard = api.get('/api/ahocorasick/keys', params={'prefix': '?at', 'wildcard': '?'})
# response_at_most = api.get('/api/ahocorasick/keys', params={'prefix': '???', 'wildcard': '?', 'how': 'MATCH_AT_MOST_PREFIX'})

# Direct library usage for demonstration:
print(list(A.keys()))
print(list(A.keys("car")))
print(list(A.keys("?at", "?")))
print(list(A.keys("???", "?", ahocorasick.MATCH_AT_MOST_PREFIX)))
print(list(A.keys("car?", "?", ahocorasick.MATCH_AT_LEAST_PREFIX)))
```

### Response
#### Success Response (200)
- **keys** (array of strings) - An array of keys matching the criteria.

#### Response Example
```json
{
  "keys": ["bat", "bar", "cat", "car", "card", "care", "careful"]
}
```
```

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

### Check key existence in Automaton

Source: https://github.com/wojciechmula/pyahocorasick/blob/master/docs/automaton_exists.md

Demonstrates how to verify if a string exists in an Automaton instance using both the exists() method and the 'in' keyword. This requires an initialized Automaton object with added words.

```python
import ahocorasick
A = ahocorasick.Automaton()
A.add_word("cat", 1)

# Using exists method
print(A.exists("cat")) # True
print(A.exists("dog")) # False

# Using 'in' keyword
print('cat' in A)      # True
print('elephant' in A) # False
```

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

### load(path, deserializer)

Source: https://github.com/wojciechmula/pyahocorasick/blob/master/docs/module_load.md

Loads a previously stored automaton from the specified path. A deserializer function is required to convert bytes back into a Python object.

```APIDOC
## load(path, deserializer)

### Description
Loads automaton previously stored on disc using `save` method.

`Deserializer` is a callable object which converts bytes back into python object; it can be `pickle.loads`.

### Method
Not applicable (this is a function call, not an HTTP endpoint)

### Endpoint
Not applicable

### Parameters
#### Path Parameters
- **path** (string) - Required - The file path to the saved automaton.
- **deserializer** (callable) - Required - A function that takes bytes and returns a Python object (e.g., `pickle.loads`).

### Request Example
```python
import pickle
import ahocorasick

automaton = ahocorasick.load('path/to/saved/automaton', pickle.loads)
```

### Response
#### Success Response (200)
- **automaton** (Automaton) - The loaded automaton object.

#### Response Example
```python
# Assuming the loaded automaton is stored in the 'automaton' variable
print(automaton.get(b'some_key')) 
```
```

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

### Manage Trie and Automaton Operations

Source: https://github.com/wojciechmula/pyahocorasick/blob/master/docs/index.md

Shows how to add words to a trie, verify existence, remove entries, and convert the trie into an Aho-Corasick automaton for pattern matching.

```python
import ahocorasick
A = ahocorasick.Automaton()
for index, word in enumerate('he her hers she'.split()):
    A.add_word(word, (index, word))

# Check existence and retrieve
'he' in A
A.get('he')

# Convert to automaton and search
A.make_automaton()
for item in A.iter('_hershe_'):
    print(item)
```

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

### Check existence and retrieve values

Source: https://github.com/wojciechmula/pyahocorasick/blob/master/docs/index.md

Methods for verifying if a key exists in the trie and retrieving its associated value. Supports default values for missing keys.

```python
import ahocorasick
A = ahocorasick.Automaton()
A.add_word("cat", 1)
exists = A.exists("cat")
value = A.get("cat")
default_val = A.get("dog", "good dog")
```

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

### match(key) -> bool

Source: https://context7.com/wojciechmula/pyahocorasick/llms.txt

Determines if any prefix of the input string exists as a key or a prefix of a key in the trie. Returns True if a match is found, False otherwise.

```APIDOC
## match(key) -> bool

### Description
Return True if there is a prefix (or complete key) equal to the input string present in the trie. Unlike exists(), this returns True for partial prefixes of stored keys.

### Method
GET

### Endpoint
`/api/ahocorasick/match/{key}`

### Parameters
#### Path Parameters
- **key** (string) - Required - The string to check for prefix matches.

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import ahocorasick

A = ahocorasick.Automaton()
A.add_word("example", True)

# Example API call (conceptual)
# response_e = api.get('/api/ahocorasick/match/e')
# response_exam = api.get('/api/ahocorasick/match/exam')
# response_examples = api.get('/api/ahocorasick/match/examples')

# Direct library usage for demonstration:
print(A.match("e"))
print(A.match("ex"))
print(A.match("exam"))
print(A.match("example"))
print(A.match("examples"))
print(A.match("python"))
print(A.exists("exam"))
print(A.exists("example"))
```

### Response
#### Success Response (200)
- **match** (boolean) - True if a prefix match is found, False otherwise.

#### Response Example
```json
{
  "match": true
}
```
```

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

### Load Automaton from File

Source: https://github.com/wojciechmula/pyahocorasick/blob/master/docs/index.md

The load() method reconstructs an automaton from a previously saved file. It requires the file path and a deserializer function (like pickle.loads) to convert the bytes back into a Python object.

```python
>>> import ahocorasick
>>> import pickle
>>> # Assuming 'automaton.pkl' was created using save()
>>> A = ahocorasick.Automaton()
>>> A.load("automaton.pkl", pickle.loads)
>>> list(A.items())
[('data', 1)]
```

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

### Pickling and Unpickling Automaton

Source: https://github.com/wojciechmula/pyahocorasick/blob/master/README.rst

Shows how to serialize an Aho-Corasick automaton to a byte string using `pickle` and then deserialize it back, allowing for the reuse of pre-built automatons.

```APIDOC
## Pickling and Unpickling Automaton

This section demonstrates how to save and load an automaton using Python's `pickle` module.

### Method

Python

### Endpoint

N/A (Library Usage)

### Parameters

N/A

### Request Example

```python
import ahocorasick
import pickle

# Create and populate automaton
haystack = "he her hers she he"
automaton = ahocorasick.Automaton()
for idx, key in enumerate('he her hers she'.split()):
    automaton.add_word(key, (idx, key))
automaton.make_automaton()

# Pickle the automaton to a string
pickled_automaton = pickle.dumps(automaton)
print("Automaton pickled successfully.")

# Unpickle the automaton
loaded_automaton = pickle.loads(pickled_automaton)
print("Automaton unpickled successfully.")

# Use the loaded automaton to search
print(f"Searching with loaded automaton in: '{haystack}'")
for end_index, (insert_order, original_value) in loaded_automaton.iter(haystack):
    start_index = end_index - len(original_value) + 1
    print((start_index, end_index, (insert_order, original_value)))

# Verify a direct lookup on the loaded automaton
print(f"loaded_automaton.get('he'): {loaded_automaton.get('he')}")
```

### Response Example

```
Automaton pickled successfully.
Automaton unpickled successfully.
Searching with loaded automaton in: 'he her hers she he'
(1, 2, (0, 'he'))
(1, 3, (1, 'her'))
(1, 4, (2, 'hers'))
(4, 6, (3, 'she'))
(5, 6, (0, 'he'))
loaded_automaton.get('he'): (0, 'he')
```
```

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

### Add Key-Value Pair to Automaton (STORE_ANY)

Source: https://github.com/wojciechmula/pyahocorasick/blob/master/docs/automaton_add_word.md

Demonstrates adding a key with a mandatory value to an Automaton initialized with STORE_ANY. The method returns True if the key is new, False otherwise, and replaces the value for existing keys. It requires a value to be provided.

```python
import ahocorasick
A = ahocorasick.Automaton()
A.add_word("pyahocorasick", (42, 'text'))
# Expected output: True
A.get("pyhocorasick")
# Expected output: (42, 'text')
A.add_word("pyahocorasick", 12)
# Expected output: False
A.get("pyhocorasick")
# Expected output: 12
```

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

### Iterate Keys with Filtering using PyAHOCORASICK

Source: https://context7.com/wojciechmula/pyahocorasick/llms.txt

Explains the keys() method for iterating over all keys in the trie. It supports optional arguments for filtering by prefix, using wildcards for pattern matching, and controlling the matching behavior (exact length, at least prefix, at most prefix).

```python
import ahocorasick

A = ahocorasick.Automaton()
for word in ['cat', 'car', 'card', 'care', 'careful', 'bat', 'bar']:
    A.add_word(word, word)

# Get all keys
print(list(A.keys()))
# Output: ['bat', 'bar', 'cat', 'car', 'card', 'care', 'careful']

# Get keys with prefix
print(list(A.keys("car")))
# Output: ['car', 'card', 'care', 'careful']

# Wildcard pattern: '?' matches any single character
print(list(A.keys("?at", "?")))
# Output: ['bat', 'cat']

# Match keys with at most prefix length (3 chars)
print(list(A.keys("???", "?", ahocorasick.MATCH_AT_MOST_PREFIX)))
# Output: ['bat', 'bar', 'cat', 'car']

# Match keys with at least prefix length
print(list(A.keys("car?", "?", ahocorasick.MATCH_AT_LEAST_PREFIX)))
# Output: ['card', 'care', 'careful']
```