PyAhoCorasick

https://github.com/wojciechmula/pyahocorasick
Admin
PyAhoCorasick is a fast and memory-efficient Python library for exact or approximate multi-pattern...
Tokens:24,816
Snippets:158
Trust Score:7.4
License:BSD-3-Clause
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Python example of match() method

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

Shows how to use the match() method on an Automaton instance. After adding the word 'example', match() returns True for all prefixes of 'example' and False for non-prefixes like 'examples' and 'python'.

```python
>>> import ahocorasick
>>> A = ahocorasick.Automaton()
>>> A.add_word("example", True)
True
>>> A.match("e")
True
>>> A.match("ex")
True
>>> A.match("exa")
True
>>> A.match("exam")
True
>>> A.match("examp")
True
>>> A.match("exampl")
True
>>> A.match("example")
True
>>> A.match("examples")
False
>>> A.match("python")
False
```

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

### Python example of Automaton.get()

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

Shows how to use the get method on an Automaton instance. It returns the value for an existing key, raises KeyError for a missing key without a default, and returns the provided default when the key is absent.

```python
>>> import ahocorasick
>>> A = ahocorasick.Automaton()
>>> A.add_word("cat", 42)
True
>>> A.get("cat")
42
>>> A.get("dog")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
KeyError
>>> A.get("dog", "good dog")
'good dog'
```

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

### Build and install pyahocorasick from source

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

Build and install pyahocorasick from the source archive or cloned repository. Requires a C compiler and pip with setuptools, typically run inside a virtualenv.

```bash
pip install .
```

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

### Wildcard search examples for Automaton.keys

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

Shows how to use the wildcard parameter in the keys method. The first example uses '?' as the wildcard to match any single character, while the second uses 'X' as the wildcard to match the literal '?' character in keys.

```default
automaton.keys("hi?", "?")  # would match "him", "his"
```

```default
automaton.keys("XX?", "X")  # would match "me?", "he?" or "it?"
```

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

### Install pyahocorasick with pip

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

Install the pyahocorasick package from PyPI. Requires a C compiler to build the native CPython extension.

```bash
pip install pyahocorasick
```

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

### Retrieve values with get()

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

Use the dict-like get() method to retrieve values. Returns the default if provided, otherwise raises KeyError when the key is missing.

```python
>>> automaton.get('he')
(0, 'he')
>>> automaton.get('she')
(3, 'she')
>>> automaton.get('cat', 'not exists')
'not exists'
>>> automaton.get('dog')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
KeyError
```

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

### Search all occurrences with iter()

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

Search all occurrences of the keys in an input string using iter(). Each result is a tuple of the end index and the associated value. The example prints start and end indices and verifies the match.

```python
>>> 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
...
(1, 2, (0, 'he'))
(1, 3, (1, 'her'))
(1, 4, (2, 'hers'))
(4, 6, (3, 'she'))
(5, 6, (0, 'he'))
```

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

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

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

Documentation for the find_all method of the Aho-Corasick automaton, which searches a string and invokes a callback for each match.

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

### Description
Performs the Aho-Corasick search procedure on the provided input string and invokes a callback for each matching tuple (end_index, value). The callback must accept two positional arguments: end_index (the end index in the input string where a trie key was found) and value (the value associated with the found key). Optional start and end arguments limit the search to a slice of the input string, equivalent to string[start:end].

### Method
Function call

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

### Parameters
- **string** (str) - Required - The input string to search.
- **callback** (callable) - Required - A callable invoked for each matching tuple; must accept two positional arguments: end_index and value.
- **start** (int) - Optional - Starting index for the search slice (as in string[start:end]).
- **end** (int) - Optional - Ending index for the search slice (as in string[start:end]).

### Callback Arguments
- **end_index** - The end index in the input string where a trie key string was found.
- **value** - The value associated with the found key string.

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

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

### Get Automaton statistics with get_stats()

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

Shows how to create an Automaton, add three words, and call get_stats() to retrieve a dictionary with node count, word count, longest word length, link count, node size, and total trie 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}
```

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

### get(key[, default])

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

Returns the value associated with a key, similar to dict.get().

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

### Description
Return the value associated with the `key` string. Similar to dict.get().

### Parameters
- **key** (string) - Required - The key to look up.
- **default** (any) - Optional - Value to return if key is not found.

### Returns
- The value associated with the key, or the default if not found.
```

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

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

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

Documentation for the iter method of the Aho-Corasick automaton, which searches for keys in an input string and returns an iterator of matches.

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

### Description
Perform the Aho-Corasick search procedure using the provided input string. Returns an iterator of tuples (`end_index`, `value`) for keys found in the string.

### Method
iter

### Parameters
#### Input String
- **string** (str) - Required - The input string to search.

#### Optional Arguments
- **start** (int) - Optional - The start index for the search slice, as in `string[start:end]`.
- **end** (int) - Optional - The end index for the search slice, as in `string[start:end]`.
- **ignore_white_space** (bool) - Optional - If True, white spaces are ignored from the input string. Default is False.

### Return Value
Returns an iterator of tuples (`end_index`, `value`) where:
- `end_index` (int) - The end index in the input string where a trie key string was found.
- `value` - The value associated with the found key string.
```

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

### Basic pyahocorasick automaton usage

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

Demonstrates basic pyahocorasick usage: adding words, checking membership, retrieving values, removing and popping words, then converting the trie to an automaton and iterating over matches. Shows that membership is case-sensitive, get() raises KeyError for missing keys unless a default is provided, and remove_word() returns False when the word is absent.

```python
>>> import ahocorasick
>>> A = ahocorasick.Automaton()

>>> # add some key words to trie
>>> for index, word in enumerate('he her hers she'.split()):
...   A.add_word(word, (index, word))

>>> # test that these key words exists in the trie all right
>>> 'he' in A
True
>>> 'HER' in A
False
>>> A.get('he')
(0, 'he')
>>> A.get('she')
(3, 'she')
>>> A.get('cat', '<not exists>')
'<not exists>'
>>> A.get('dog')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
KeyError
>>> A.remove_word('he')
True
>>> A.remove_word('he')
False
>>> A.pop('she')
(3, 'she')
>>> 'she' in A
False

>>> # convert the trie in an Aho-Corasick automaton
>>> A = ahocorasick.Automaton()
>>> for index, word in enumerate('he her hers she'.split()):
...   A.add_word(word, (index, word))
>>> A.make_automaton()

>>> # then find all occurrences of the stored keys in a string
>>> for item in A.iter('_hershe_'):
...  print(item)
...
(2, (0, 'he'))
(3, (1, 'her'))
(4, (2, 'hers'))
(6, (3, 'she'))
(6, (0, 'he'))
```

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

### Using len() with ahocorasick.Automaton

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

Shows how to get the number of distinct keys in an Automaton trie. The example creates an empty automaton, prints len(A) as 0, adds the word "python" with value 1, prints len(A) as 1, adds "elephant" with value True, and prints len(A) as 2. The output is shown in the comments after each len() call.

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

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

### Iterating over strings with A.iter()

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

Iterates over each string in a set, searching for matches with the iter method. This is the equivalent of the reset example that follows.

```python
>>> for string in string_set:
...     for index, value in A.iter(string)
...         print(index, '=>', value)
```

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

### Check key presence with exists() and 'in' operator

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

Shows how to use the exists() method and the 'in' keyword to check for key presence in an ahocorasick automaton. The example adds the word "cat" and then verifies that exists() returns True for "cat" and False for "dog", and that the 'in' operator works equivalently.

```python
>>> import ahocorasick
>>> A = ahocorasick.Automaton()
>>> A.add_word("cat", 1)
True
>>> A.exists("cat")
True
>>> A.exists("dog")
False
>>> 'elephant' in A
False
>>> 'cat' in A
True
```

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

### Create Automaton with different value_type and key_type

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

Shows how to create an empty Automaton with default settings, with STORE_ANY, and with STORE_INTS plus KEY_STRING. The output shows the object representations for each constructor call.

```python
>>> import ahocorasick
>>> A = ahocorasick.Automaton()
>>> A
<ahocorasick.Automaton object at 0x7f1da1bdf7f0>
>>> B = ahocorasick.Automaton(ahocorasick.STORE_ANY)
>>> B
<ahocorasick.Automaton object at 0x7f1da1bdf6c0>
>>> C = ahocorasick.Automaton(ahocorasick.STORE_INTS, ahocorasick.KEY_STRING)
>>> C
<ahocorasick.Automaton object at 0x7f1da1527f10>
```

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

### pyahocorasick keys() method with wildcard and match modes

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

Shows the keys() method with prefix search and wildcard matching. The wildcard character is '?' and can be any character. Demonstrates the three match modes: MATCH_EXACT_LENGTH, MATCH_AT_MOST_PREFIX, and MATCH_AT_LEAST_PREFIX, with their respective outputs.

```python
>>> import ahocorasick
>>> A = ahocorasick.Automaton()

>>> # add some key words to trie
>>> for index, word in enumerate('cat catastropha rat rate bat'.split()):
...   A.add_word(word, (index, word))

>>> # Search some prefix
>>> list(A.keys('cat'))
['cat', 'catastropha']

>>> # Search with a wildcard: here '?' is used as a wildcard. You can use any character you like.
>>> list(A.keys('?at', '?', ahocorasick.MATCH_EXACT_LENGTH))
['bat', 'cat', 'rat']

>>> list(A.keys('?at?', '?', ahocorasick.MATCH_AT_MOST_PREFIX))
['bat', 'cat', 'rat', 'rate']

>>> list(A.keys('?at?', '?', ahocorasick.MATCH_AT_LEAST_PREFIX))
['rate']
```

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

### keys([prefix, [wildcard, [how]]]) => yield strings

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

Returns an iterator over keys, optionally filtered by prefix and wildcard.

```APIDOC
## keys([prefix, [wildcard, [how]]]) => yield strings

### Description
Return an iterator on keys. Supports optional prefix and wildcard filtering.

### Parameters
- **prefix** (string) - Optional - Only keys starting with this prefix are returned.
- **wildcard** (string) - Optional - A character used as a wildcard in the prefix.
- **how** (constant) - Optional - One of `ahocorasick.MATCH_EXACT_LENGTH`, `ahocorasick.MATCH_AT_MOST_PREFIX`, or `ahocorasick.MATCH_AT_LEAST_PREFIX`.

### Returns
- Iterator of strings (keys).

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

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

### match(key) => bool

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

Checks if there is a prefix (or key) equal to the given key in the trie.

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

### Description
Return True if there is a prefix (or key) equal to `key` present in the trie.

### Parameters
- **key** (string) - Required - The key to match.

### Returns
- **bool** - True if a matching prefix or key exists.
```

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

### Resetting iterator with set(it, True)

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

Resets the iterator with set(it, True) before processing each string, restarting the search. This is equivalent to the previous example that uses A.iter(string) directly.

```python
>>> it = A.iter(b"")
>>> for string in string_set:
...     it.set(it, True)
...     for index, value in it:
...         print(index, '=>', value)
```

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

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

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

Returns an iterator on values associated with each key. Keys are matched optionally to the prefix using the same logic and arguments as in the keys() method.

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

### Description
Returns an iterator on values associated with each key. Keys are matched optionally to the prefix using the same logic and arguments as in the keys() method.

### Method
values

### Parameters
- **prefix** (string) - Optional - Only yield values whose key starts with this prefix.
- **wildcard** (string) - Optional - A single character used as a wildcard in the prefix pattern.
- **how** (int) - Optional - Matching mode, one of:
  - `ahocorasick.MATCH_EXACT_LENGTH` (default) - Yield matches that have the same exact length as the prefix length.
  - `ahocorasick.MATCH_AT_LEAST_PREFIX` - Yield matches that have a length greater or equal to the prefix length.
  - `ahocorasick.MATCH_AT_MOST_PREFIX` - Yield matches that have a length lesser or equal to the prefix length.

### Returns
- **iterator** - An iterator over values.

### Example
```python
>>> import ahocorasick
>>> A = ahocorasick.Automaton()
>>> A.add_word("cat", 1)
True
>>> A.add_word("dog", 2)
True
>>> list(A.values())
[1, 2]
```
```

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

### Example: iter_long vs iter

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

Demonstrates the difference between iter_long and iter on a set of words {he, her, here} and needle 'he here her'. iter_long returns only the longest matches, while iter returns all occurrences.

```python
>>> import ahocorasick
>>> A = ahocorasick.Automaton()
>>> A.add_word("he", "he")
True
>>> A.add_word("her", "her")
True
>>> A.add_word("here", "here")
True
>>> A.make_automaton()
>>> needle = "he here her"
>>> list(A.iter_long(needle))
[(1, 'he'), (6, 'here'), (10, 'her')]
>>> list(A.iter(needle))
[(1, 'he'), (4, 'he'), (5, 'her'), (6, 'here'), (9, 'he'), (10, 'her')]
```

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

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

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

Performs the modified Aho-Corasick search procedure which matches the longest words from the set. Returns an iterator of tuples (`end_index`, `value`) for keys found in the input string.

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

### Description
Performs the modified Aho-Corasick search procedure which matches the longest words from the set. Returns an iterator of tuples (`end_index`, `value`) for keys found in the input string.

### Method
iter_long

### Parameters
- **string** (str) - Required - The input string to search.
- **start** (int) - Optional - The start index for the search slice, as in `string[start:end]`.
- **end** (int) - Optional - The end index for the search slice, as in `string[start:end]`.

### Returns
- Iterator of tuples (`end_index`, `value`) where `end_index` is the end index in the input string where a trie key string was found, and `value` is the value associated with the found key string.

### Example
```python
>>> import ahocorasick
>>> A = ahocorasick.Automaton()
>>> A.add_word("he", "he")
True
>>> A.add_word("her", "her")
True
>>> A.add_word("here", "here")
True
>>> A.make_automaton()
>>> needle = "he here her"
>>> list(A.iter_long(needle))
[(1, 'he'), (6, 'here'), (10, 'her')]
```
```

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

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

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

Returns an iterator on tuples of (key, value). Keys are matched optionally to the prefix using the same logic and arguments as in the keys() method.

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

### Description
Returns an iterator on tuples of (key, value). Keys are matched optionally to the prefix using the same logic and arguments as in the keys() method.

### Method
N/A (method call)

### Endpoint
N/A (method call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
N/A

### Response
#### Success Response
- Returns an iterator of tuples, each containing a key and its associated value.

#### Response Example
N/A

### Error Handling
No explicit error handling documented.
```

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

### Clear Automaton Trie with ahocorasick.clear()

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

Removes all keys from the trie and invalidates all iterators. The example adds three words, confirms the length is 3, calls clear(), and verifies the length becomes 0.

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

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

### dump()

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

Documentation for the dump() method of the Automaton class, which returns a three-tuple of lists describing the automaton graph.

```APIDOC
## dump()

### Description
Returns a three-tuple of lists describing the Automaton as a graph of nodes, edges, and failure links.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response
- **nodes**: list of pairs (node id, end of word marker)
- **edges**: list of triples (node id, label char, child node id)
- **failure links**: list of pairs (source node id, node id connected by fail node)

#### Response Example
N/A
```

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

### Remove words from ahocorasick.Automaton with remove_word

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

Demonstrates the remove_word method on an ahocorasick.Automaton instance. Shows that removing an existing word returns True, and removing the same word again returns False. The example adds words "cat" and "dog" with values 1 and 2 before removal.

```python
>>> import ahocorasick
>>> A = ahocorasick.Automaton()
>>> A.add_word("cat", 1)
True
>>> A.add_word("dog", 2)
True
>>> A.remove_word("cat")
True
>>> A.remove_word("cat")
False
>>> A.remove_word("dog")
True
>>> A.remove_word("dog")
False
>>>
```

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

### Using save/load methods

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

Saves and loads an Automaton using the custom save/load methods. The save method requires a callable to serialize values when the store type is STORE_ANY; the load method always requires a callable to deserialize bytes back into Python objects.

```python
import ahocorasick
import pickle

# build automaton

A = ahocorasick.Automaton()
# ... A.add_data, A.make_automaton

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

# load saved state
B = ahocorasick.load(path, pickle.loads)
```

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

### add_word() with default Automaton (STORE_ANY)

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

Demonstrates add_word() with a default Automaton (STORE_ANY). The value is required; omitting it raises ValueError. Adding a new key returns True, replacing an existing key returns False and updates the value.

```python
>>> import ahocorasick
>>> A = ahocorasick.Automaton()
>>> A.add_word("pyahocorasick")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: A value object is required as second argument.
>>> A.add_word("pyahocorasick", (42, 'text'))
True
>>> A.get("pyhocorasick")
(42, 'text')
>>> A.add_word("pyahocorasick", 12)
False
>>> A.get("pyhocorasick")
12
```

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

### Automaton constructor

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

Creates a new empty Automaton with optional value_type and key_type parameters.

```APIDOC
## Automaton([value_type], [key_type])

### Description
Create a new empty Automaton optionally passing a value_type to indicate what is the type of associated values (default to any Python object type). The optional argument key_type can be `ahocorasick.KEY_STRING` or `ahocorasick.KEY_SEQUENCE`.

### Parameters
- **value_type** (constant) - Optional - One of `ahocorasick.STORE_ANY`, `ahocorasick.STORE_INTS`, or `ahocorasick.STORE_LENGTH`. In the last case the length of the key will be stored in the automaton.
- **key_type** (constant) - Optional - `ahocorasick.KEY_STRING` or `ahocorasick.KEY_SEQUENCE`. In the latter case keys will be tuples of integers.

### Notes
Automaton instances are pickle-able, allowing creation ahead of time and reuse as a persistent multi-string search index.
```

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

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

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

Returns an iterator over keys in the automaton. Optionally filters by prefix, supports wildcard pattern matching, and controls matching length via the 'how' argument.

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

### Description
Returns an iterator on keys. If the optional `prefix` string is provided, only keys starting with this prefix are yielded. If the optional `wildcard` is provided as a single character string, the prefix is treated as a simple pattern using this character as a wildcard. The optional `how` argument controls how strings are matched.

### Method
keys

### Parameters
#### Optional Parameters
- **prefix** (string) - Optional - If provided, only yield keys starting with this prefix.
- **wildcard** (string) - Optional - A single character string used as a wildcard in the prefix pattern.
- **how** (enum) - Optional - Controls matching length. Possible values:
  - `ahocorasick.MATCH_EXACT_LENGTH` (default): Yield matches that have the same exact length as the prefix length.
  - `ahocorasick.MATCH_AT_LEAST_PREFIX`: Yield matches that have a length greater or equal to the prefix length.
  - `ahocorasick.MATCH_AT_MOST_PREFIX`: Yield matches that have a length lesser or equal to the prefix length.

### Returns
An iterator over keys.
```

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

### save(path, serializer)

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

Documentation for the save method of the automaton class, which persists the automaton to a file.

```APIDOC
## save(path, serializer)

### Description
Saves the content of the automaton to a file on disk. The serializer is a callable object used when the automaton store type is `STORE_ANY`, converting a Python object into bytes (e.g., `pickle.dumps`).

### Method
save

### Parameters
- **path** (string) - Required - The file path where the automaton will be saved.
- **serializer** (callable) - Required - A callable that converts the automaton object to bytes, used when store type is `STORE_ANY`.

### Request Example
```python
# Example usage
automaton.save('automaton.bin', pickle.dumps)
```

### Response
No return value.
```

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

### values([prefix, [wildcard, [how]]]) => yield object

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

Returns an iterator over values associated with each key.

```APIDOC
## values([prefix, [wildcard, [how]]]) => yield object

### Description
Return an iterator over values associated with each key. Supports optional prefix and wildcard filtering.

### Parameters
- **prefix** (string) - optional - Only values for keys starting with this prefix are returned.
- **wildcard** (string) - optional - A character used as a wildcard in the prefix.
- **how** (constant) - optional - One of `ahocorasick.MATCH_EXACT_LENGTH`, `ahocorasick.MATCH_AT_MOST_PREFIX`, or `ahocorasick.MATCH_AT_LEAST_PREFIX`.

### Returns
- Iterator of objects (value).
```

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

### Aho-Corasick Methods

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

Documentation for the main Aho-Corasick methods of the Automaton class, including search methods, attributes, saving/loading, and utility methods.

```APIDOC
## make_automaton()

### Description
Finalize and create the Aho-Corasick automaton. This method must be called after adding all keys and before performing any searches.

### Method
make_automaton

### Parameters
None

### Returns
None
```

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

### Description
Perform the Aho-Corasick search procedure using the provided input string. Returns an iterator of tuples (end_index, value) for keys found in the string.

### Method
iter

### Parameters
- **string** (str/bytes) - Required - The input string to search.
- **start** (int) - Optional - The starting index in the string.
- **end** (int) - Optional - The ending index in the string.

### Returns
Iterator of tuples (end_index, value) for keys found in the string.
```

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

### Description
Returns an iterator (object of class AutomatonSearchIterLong) that searches for longest, non-overlapping matches.

### Method
iter_long

### Parameters
- **string** (str/bytes) - Required - The input string to search.
- **start** (int) - Optional - The starting index in the string.
- **end** (int) - Optional - The ending index in the string.

### Returns
AutomatonSearchIterLong iterator for longest, non-overlapping matches.
```

```APIDOC
## AutomatonSearchIter.set(string, [reset]) => None

### Description
Set a new string to search, optionally keeping the current Automaton state to continue searching for the next chunk of a string. When reset is True, processing is restarted.

### Method
set

### Parameters
- **string** (str/bytes) - Required - The new string to search.
- **reset** (bool) - Optional - If True, restart processing.

### Returns
None
```

```APIDOC
## Automaton.kind [readonly]

### Description
Return the state of the Automaton instance.

### Method
kind

### Parameters
None

### Returns
The state of the Automaton instance.
```

```APIDOC
## Automaton.store [readonly]

### Description
Return the type of values stored in the Automaton as specified at creation.

### Method
store

### Parameters
None

### Returns
The type of values stored in the Automaton.
```

```APIDOC
## Automaton.save(path, callable)

### Description
Save the automaton to a file using a custom serialization method. The callable serializes Python objects into bytes; required if the automaton type is STORE_ANY.

### Method
save

### Parameters
- **path** (str) - Required - The file path to save the automaton.
- **callable** (callable) - Required for STORE_ANY - A callable that serializes Python objects into bytes.

### Returns
None
```

```APIDOC
## ahocorasick.load(path, callable)

### Description
Load an automaton from a file using a custom deserialization method. The callable converts bytes back into Python values.

### Method
load

### Parameters
- **path** (str) - Required - The file path to load the automaton from.
- **callable** (callable) - Required - A callable that converts bytes into Python values.

### Returns
Automaton instance
```

```APIDOC
## Automaton.dump() => (list of nodes, list of edges, list of fail links)

### Description
Return a three-tuple of lists describing the Automaton as a graph of (nodes, edges, failure links). Useful for visualization.

### Method
dump

### Parameters
None

### Returns
A three-tuple of lists: nodes, edges, and fail links.
```

```APIDOC
## Automaton.get_stats() => dict

### Description
Return a dictionary containing Automaton statistics. Note that the real size occupied by the data structure could be larger due to internal memory fragmentation.

### Method
get_stats

### Parameters
None

### Returns
A dictionary containing Automaton statistics.
```

```APIDOC
## Automaton.__sizeof__() => int

### Description
Return the approximate size in bytes occupied by the Automaton instance. Also available by calling sys.getsizeof(automaton instance).

### Method
__sizeof__

### Parameters
None

### Returns
Approximate size in bytes.
```

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

### load(path, deserializer) => Automaton

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

Loads an automaton previously stored on disc using the save method. The deserializer is a callable that converts bytes back into a Python object, such as pickle.loads.

```APIDOC
## load(path, deserializer) => Automaton

### Description
Loads an automaton previously stored on disc using the `save` method. The `deserializer` is a callable object that converts bytes back into a Python object, such as `pickle.loads`.

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

### Returns
- **Automaton** - The loaded automaton instance.

### Example
```python
import pickle
from pyahocorasick import Automaton

automaton = Automaton.load('automaton.bin', pickle.loads)
```
```

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

### pop(word)

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

Documentation for the pop method of the Automaton class in the pyahocorasick library.

```APIDOC
## pop(word)

### Description
Remove given word from a trie and return associated values. Raise a `KeyError` if the word was not found.

### Method
pop

### Parameters
- **word** (string) - Required - The word to remove from the trie.

### Returns
- The value associated with the word, if found.

### Exceptions
- `KeyError` - If the word is not found in the trie.

### Example
```python
>>> import ahocorasick
>>> A = ahocorasick.Automaton()
>>> A.add_word("cat", 1)
True
>>> A.add_word("dog", 2)
True
>>> A.pop("elephant")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
KeyError
>>> A.pop("cat")
1
>>> A.pop("dog")
2
>>> A.pop("cat")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
KeyError
```
```

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

### Automaton(value_type=ahocorasick.STORE_ANY, [key_type])

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

Constructor for creating a new empty Automaton instance. The value_type and key_type parameters are optional and control the storage behavior and accepted key types.

```APIDOC
## Automaton(value_type=ahocorasick.STORE_ANY, [key_type])

### Description
Creates a new empty Automaton. Both `value_type` and `key_type` are optional.

### Parameters
- **value_type** (constant) - Optional - One of `ahocorasick.STORE_ANY` (default), `ahocorasick.STORE_LENGTH`, or `ahocorasick.STORE_INTS`.
- **key_type** (constant) - Optional - One of `ahocorasick.KEY_STRING` (default) or `ahocorasick.KEY_SEQUENCE`.

### Example
```python
>>> import ahocorasick
>>> A = ahocorasick.Automaton()
>>> A
<ahocorasick.Automaton object at 0x7f1da1bdf7f0>
>>> B = ahocorasick.Automaton(ahocorasick.STORE_ANY)
>>> B
<ahocorasick.Automaton object at 0x7f1da1bdf6c0>
>>> C = ahocorasick.Automaton(ahocorasick.STORE_INTS, ahocorasick.KEY_STRING)
>>> C
<ahocorasick.Automaton object at 0x7f1da1527f10>
```
```

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

### __reduce__()

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

Returns pickle-able data for this automaton instance.

```APIDOC
## __reduce__()

### Description
Returns pickle-able data for this automaton instance.

### Method
__reduce__

### Returns
Pickle-able data for this automaton instance.
```

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

### Create an Automaton

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

Import the ahocorasick module and create an Automaton instance. The Automaton can be used as a trie before conversion to an automaton.

```python
>>> import ahocorasick
>>> automaton = ahocorasick.Automaton()
```

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

### add_word(key, [value]) => bool

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

Adds a key string to the trie and associates it with a value.

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

### Description
Add a `key` string to the dict-like trie and associate this key with a `value`.

### Parameters
- **key** (string) - Required - The key to add.
- **value** (any) - Optional - The value to associate with the key.

### Returns
- **bool** - True if the key was added successfully.
```
Tokens:
Raw