pyahocorasick

https://pyahocorasick.readthedocs.io/
Admin
pyahocorasick is a fast and memory-efficient Python library for exact and approximate multi-pattern...
Tokens:23,357
Snippets:222
Trust Score:9.6
Update:3 months ago
Show doc for...
Tokens:
Raw
### Build and Install Pyahocorasick from Source

Source: https://pyahocorasick.readthedocs.io/en/latest

To build from source, clone the repository or download the archive. Ensure you have a C compiler installed. Then, use pip to install the package.

```bash
pip install .

```

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

### Install pyahocorasick

Source: https://pyahocorasick.readthedocs.io/en/latest

Install the pyahocorasick library using pip. Ensure a C compiler is installed as the module is written in C.

```bash
pip install pyahocorasick

```

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

### Retrieve values using get()

Source: https://pyahocorasick.readthedocs.io/en/latest

Use the dict-like get() method to retrieve the value associated with a key. Provide a default value to handle cases where the key is not found, otherwise a KeyError is raised.

```python
automaton.get('he')
automaton.get('she')
automaton.get('cat', 'not exists')
automaton.get('dog')

```

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

### get

Source: https://pyahocorasick.readthedocs.io/en/latest

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

```APIDOC
## get

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

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

### Parameters
* **key** (string) - Required - The key string to retrieve the value for.
* **default** - Optional - The default value to return if the key is not found.
```

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

### Wildcard Search Examples

Source: https://pyahocorasick.readthedocs.io/en/latest

Demonstrates using wildcard characters in the keys method to match patterns. The wildcard character can be any character, but it cannot be escaped.

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

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

### get

Source: https://pyahocorasick.readthedocs.io/en/latest

Retrieves the value associated with a given key. If the key is not found, it returns a default value if provided.

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

### Description
Retrieves the value associated with a given key. If the key is not found, it returns a default value if provided.

### Parameters
* **key** (string) - The key whose value is to be retrieved.
* **default** - Optional - The value to return if the key is not found.

### Example
```python
import ahocorasick

A = ahocorasick.Automaton()
A.add_word('apple', 'fruit')

print(A.get('apple'))      # Output: fruit
print(A.get('orange', 'unknown')) # Output: unknown
```
```

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

### get

Source: https://pyahocorasick.readthedocs.io/en/latest

Retrieves the value associated with a key string. Raises KeyError if the key is not found and no default is provided.

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

### Description
Returns the value associated with the key string. Raises a `KeyError` exception if the key is not in the trie and no default is provided. Returns the optional default value if provided and the key is not in the trie.

### Parameters
* **key** (string) - Required - The key whose associated value is to be returned.
* **default** - Optional - The value to return if the key is not found in the trie.
```

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

### Retrieve Value Associated with Key

Source: https://pyahocorasick.readthedocs.io/en/latest

Demonstrates retrieving the value associated with a key using the `get()` method. It shows successful retrieval, handling of missing keys with a default value, and raising a KeyError for missing keys without a default.

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

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

### Get the number of keys in a trie

Source: https://pyahocorasick.readthedocs.io/

Shows how to retrieve the count of unique keys stored in the trie. Useful for monitoring the size of the dictionary.

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

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

### Run Pyahocorasick Tests

Source: https://pyahocorasick.readthedocs.io/en/latest

Tests for pyahocorasick can be run using pytest after installing the package in editable mode with testing dependencies.

```bash
pip installe -e .[testing] && pytest -vvs

```

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

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

Source: https://pyahocorasick.readthedocs.io/en/latest

Performs the Aho-Corasick search on an input string. It returns an iterator of tuples, where each tuple contains the end index of a found key in the string and its associated value. The search can be limited to a slice of the string and can optionally ignore whitespace.

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

### Description
Perform the Aho-Corasick search procedure using the provided input string. Return an iterator of tuples (`end_index`, `value`) for keys found in string 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. The `start` and `end` optional arguments can be used to limit the search to an input string slice as in `string[start:end]`. The `ignore_white_space` optional arguments can be used to ignore white spaces from input string.

### Method
N/A (Python method)

### Parameters
#### Required Parameters
- **string** (string) - The input string to search within.

#### Optional Parameters
- **start** (integer) - Optional - The starting index for the search slice.
- **end** (integer) - Optional - The ending index for the search slice.
- **ignore_white_space** (bool) - Optional - If True, whitespace characters in the input string are ignored during the search. Defaults to False.

### Request Example
N/A

### Response
#### Success Response
- **iterator**: An iterator yielding tuples of (`end_index`, `value`) for each match found in the string.
```

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

### Get Automaton Statistics with get_stats

Source: https://pyahocorasick.readthedocs.io/

Retrieve statistics about the automaton's structure and memory usage. This includes node and word counts, longest word length, and memory footprint. Useful for understanding automaton complexity and optimizing memory.

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

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

### Create Automaton Instances

Source: https://pyahocorasick.readthedocs.io/en/latest

Demonstrates creating Automaton instances with default settings, with STORE_ANY, and with STORE_INTS and KEY_STRING.

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

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

### Prefix Searching with `keys` Method

Source: https://pyahocorasick.readthedocs.io/en/latest

Demonstrates using the `keys` method for prefix searching. It shows how to find keys matching a prefix and how to use wildcards for more flexible pattern matching.

```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 Method with Prefix Matches

Source: https://pyahocorasick.readthedocs.io/

Illustrates using the `keys` method with wildcard characters for at most and at least prefix matching.

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

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

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

### Keys Method with Exact Length Match

Source: https://pyahocorasick.readthedocs.io/

Demonstrates using the `keys` method to search for prefixes with an exact length match, using a wildcard character.

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

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

### Create and Populate Automaton

Source: https://pyahocorasick.readthedocs.io/

Create an Automaton instance and add string keys with associated values. The values here are tuples of (insertion index, original string).

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

```

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

### Clear Trie of All Keys

Source: https://pyahocorasick.readthedocs.io/en/latest

The `clear` method removes all entries from the trie, effectively resetting it. This operation invalidates any existing iterators. Use this when you need to start with an empty trie.

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

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

### Match prefixes in a trie

Source: https://pyahocorasick.readthedocs.io/

Demonstrates how to check for the presence of prefixes of a given key within the trie. Useful for validating partial word matches.

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

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

### Get Automaton Statistics

Source: https://pyahocorasick.readthedocs.io/en/latest

Retrieve statistics about the Aho-Corasick automaton, including node counts, word counts, and memory usage. This is helpful for understanding the automaton's complexity and resource consumption.

```python
import ahocorasick
A = ahocorasick.Automaton()
A.add_word("he", None)
A.add_word("her", None)
A.add_word("hers", None)
A.get_stats()
```

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

### load

Source: https://pyahocorasick.readthedocs.io/

Loads a previously saved automaton from disk. A deserializer callable can be provided for custom deserialization when the store type is `STORE_ANY`.

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

### Description
Load 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`.

### Parameters
#### Path Parameters
- **path** (string) - Required - The path to the file from which the automaton will be loaded.
- **deserializer** (callable) - Optional - A callable object used for deserialization, e.g., `pickle.loads`.

### Response
#### Success Response
- **Automaton** - The loaded automaton instance.
```

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

### Remove Word and Get Value from Trie

Source: https://pyahocorasick.readthedocs.io/en/latest

The `pop` method removes a word and returns its associated value. It raises a `KeyError` if the word is not found. This is useful for retrieving and removing items simultaneously.

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

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

### dump

Source: https://pyahocorasick.readthedocs.io/

Returns a three-tuple of lists describing the automaton as a graph, including nodes, edges, and failure links. Node IDs and labels are represented as numbers.

```APIDOC
## dump()

### Description
Return a three-tuple of lists describing the Automaton as a graph of **nodes** , **edges** , **failure links**.
  * nodes: each item is a pair (node id, end of word marker)
  * edges: each item is a triple (node id, label char, child node id)
  * failure links: each item is a pair (source node id, node if connected by fail node)

For each of these, the node id is a unique number and a label is a number.

### Response
#### Success Response
- **tuple** - A tuple containing three lists: `nodes`, `edges`, and `failure_links`.
```

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

### Iterate over matches in a haystack

Source: https://pyahocorasick.readthedocs.io/en/latest

Use the iter() method to find all occurrences of the stored keys within a given input string (haystack). It returns tuples of the end index and the associated value. The example also includes an assertion to verify the correctness of the match.

```python
haystack = 'sheherhe'
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

```

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

### Add Word to Automaton (STORE_ANY)

Source: https://pyahocorasick.readthedocs.io/en/latest

Shows how to add a word to an Automaton configured with STORE_ANY. A value is required, and attempting to add a word without a value will raise a ValueError. Existing words can have their values updated.

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

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

### Saving Automaton with Pickle

Source: https://pyahocorasick.readthedocs.io/en/latest

Use this method for convenient saving and loading of Automaton states. Be aware of potentially high memory requirements.

```python
import ahocorasick
import pickle

# build automaton

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

# 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)

```

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

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

Source: https://pyahocorasick.readthedocs.io/en/latest

Returns an iterator over (key, value) tuples. Filtering by prefix, wildcard, and matching strategy is supported, similar to the `keys()` method.

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

### Description
Return 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 (Python method)

### Parameters
#### Optional Parameters
- **prefix** (string) - Optional - If provided, only yield items where the key starts with this prefix.
- **wildcard** (string) - Optional - A single character string used as a wildcard in the prefix pattern.
- **how** (integer) - Optional - Controls the matching strategy. Possible values: `ahocorasick.MATCH_EXACT_LENGTH` (default), `ahocorasick.MATCH_AT_LEAST_PREFIX`, `ahocorasick.MATCH_AT_MOST_PREFIX`.

### Request Example
N/A

### Response
#### Success Response
- **iterator**: An iterator yielding (key, value) tuples that match the specified criteria.
```

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

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

Source: https://pyahocorasick.readthedocs.io/

Returns an iterator over the keys in the trie. Optionally, keys can be filtered by a prefix, a wildcard pattern, or specific matching strategies.

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

### Description
Return an iterator on keys. If the optional `prefix` string is provided, only yield keys starting with this prefix. If the optional `wildcard` is provided as a single character string, then the prefix is treated as a simple pattern using this character as a wildcard. The optional `how` argument is used to control how strings are matched.

### Method
N/A (Python method)

### Parameters
#### Path Parameters
N/A

#### Query 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** (integer) - Optional - Controls matching strategy. Possible values:
  * `ahocorasick.MATCH_EXACT_LENGTH` (default)
  * `ahocorasick.MATCH_AT_LEAST_PREFIX`
  * `ahocorasick.MATCH_AT_MOST_PREFIX`

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response
- **iterator**: An iterator yielding keys from the trie, potentially filtered by the provided arguments.

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

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

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

Source: https://pyahocorasick.readthedocs.io/en/latest

Returns an iterator over the keys in the trie. Optionally, keys can be filtered by a prefix, a wildcard pattern, or a specific matching strategy (exact length, at least prefix, at most prefix).

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

### Description
Return an iterator on keys. If the optional `prefix` string is provided, only yield keys starting with this prefix. If the optional `wildcard` is provided as a single character string, then the prefix is treated as a simple pattern using this character as a wildcard. The optional `how` argument is used to control how strings are matched using one of these possible values: `ahocorasick.MATCH_EXACT_LENGTH` (default), `ahocorasick.MATCH_AT_LEAST_PREFIX`, `ahocorasick.MATCH_AT_MOST_PREFIX`.

### Method
N/A (Python method)

### 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** (integer) - Optional - Controls the matching strategy. Possible values: `ahocorasick.MATCH_EXACT_LENGTH` (default), `ahocorasick.MATCH_AT_LEAST_PREFIX`, `ahocorasick.MATCH_AT_MOST_PREFIX`.

### Request Example
N/A

### Response
#### Success Response
- **iterator**: An iterator yielding keys that match the specified criteria.
```

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

### Automaton Class Constructor

Source: https://pyahocorasick.readthedocs.io/

Creates a new empty Automaton. Optionally specify the value type and key type for the automaton.

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

### Description
Creates a new empty Automaton. Optionally passing a `value_type` to indicate what is the type of associated values (default to any Python object type). It can be 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. The optional argument `key_type` can be `ahocorasick.KEY_STRING` or `ahocorasick.KEY_SEQUENCE`. In the latter case keys will be tuples of integers.
```

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

### Saving Automaton with Custom Methods

Source: https://pyahocorasick.readthedocs.io/en/latest

Utilize custom save/load methods for potentially lower memory footprints compared to pickling. Requires specifying serialization/deserialization callables.

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

```

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

### load

Source: https://pyahocorasick.readthedocs.io/en/latest

Loads an automaton from a file path using a specified deserializer. Returns a new Automaton object.

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

### Description
Loads an automaton from a file path using a specified deserializer. Returns a new Automaton object.

### Parameters
* **path** (string) - The file path from which to load the automaton.
* **deserializer** (callable) - A function or method used to deserialize the automaton's data.

### Returns
* **Automaton** - A new Automaton object loaded with the saved data.
```

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

### Basic Automaton Operations

Source: https://pyahocorasick.readthedocs.io/en/latest

Demonstrates adding words to an automaton, checking for their existence, retrieving associated values, and removing words. Use this for basic trie manipulation and verification.

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

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

### match

Source: https://pyahocorasick.readthedocs.io/en/latest

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

```APIDOC
## match

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

### Method
`match(key)`

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

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

### match

Source: https://pyahocorasick.readthedocs.io/en/latest

Checks if a given key exists as a complete word in the automaton. Returns true if it matches, false otherwise.

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

### Description
Checks if a given key exists as a complete word in the automaton. Returns true if it matches, false otherwise.

### Parameters
* **key** (string) - The key to check for a match.

### Returns
* **bool** - True if the key is found as a complete word, False otherwise.

### Examples
```python
import ahocorasick

A = ahocorasick.Automaton()
A.add_word('apple', 'fruit')

print(A.match('apple')) # Output: True
print(A.match('app'))   # Output: False (if 'app' was not added as a separate word)
```
```

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

### dump

Source: https://pyahocorasick.readthedocs.io/en/latest

Returns a string representation of the automaton's internal structure, useful for debugging.

```APIDOC
## dump()

### Description
Returns a string representation of the automaton's internal structure, useful for debugging.

### Returns
* **string** - A detailed string representation of the automaton.
```

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

### Iterating with AutomatonSearchIter

Source: https://pyahocorasick.readthedocs.io/en/latest

Shows how to use the AutomatonSearchIter class to process data in chunks. The set method can be used to update the string being searched, optionally resetting the 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)
```

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

### match(key)

Source: https://pyahocorasick.readthedocs.io/en/latest

Checks if any key present in the trie is a prefix of the given key. This method returns True if a key exists that matches the provided key exactly or is a prefix of it.

```APIDOC
## match(key)

### Description
Return True if there is a prefix (or key) equal to key present in the trie. For example if the key ‘example’ has been added to the trie, then calls to match(‘e’), match(‘ex’), …, match(‘exampl’) or match(‘example’) all return True. But exists() is True only when calling exists(‘example’).

### Method
N/A (Python method)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response
- **bool**: True if a matching prefix or key is found, False otherwise.

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

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

### add_word

Source: https://pyahocorasick.readthedocs.io/en/latest

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

```APIDOC
## add_word

### Description
Adds a key string to the dict-like trie and associates it with a value.

### Method
`add_word(key, [value])`

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

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

### make_automaton

Source: https://pyahocorasick.readthedocs.io/en/latest

Finalizes the trie and creates the Aho-Corasick automaton, preparing it for searching.

```APIDOC
## make_automaton

### Description
Finalize and create the Aho-Corasick automaton. This method must be called before performing searches.

### Method
`make_automaton()`
```

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

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

Source: https://pyahocorasick.readthedocs.io/en/latest

Returns an iterator over the values associated with keys in the trie. Filtering by prefix, wildcard, and matching strategy is supported, similar to the `keys()` method.

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

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

### Method
N/A (Python method)

### Parameters
#### Optional Parameters
- **prefix** (string) - Optional - If provided, only yield values where the key starts with this prefix.
- **wildcard** (string) - Optional - A single character string used as a wildcard in the prefix pattern.
- **how** (integer) - Optional - Controls the matching strategy. Possible values: `ahocorasick.MATCH_EXACT_LENGTH` (default), `ahocorasick.MATCH_AT_LEAST_PREFIX`, `ahocorasick.MATCH_AT_MOST_PREFIX`.

### Request Example
N/A

### Response
#### Success Response
- **iterator**: An iterator yielding values associated with keys that match the specified criteria.
```

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

### Automaton Dictionary-like methods

Source: https://pyahocorasick.readthedocs.io/

Methods that allow the Automaton to be used with dictionary-like syntax for accessing and managing words and their associated values.

```APIDOC
## Wildcard search

### Description
This section likely refers to advanced search capabilities that might involve wildcards, though specific methods for this are not detailed in the provided API reference. Users might need to refer to examples or external documentation for wildcard implementation details.
```

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

### Automaton

Source: https://pyahocorasick.readthedocs.io/en/latest

Creates a new empty Automaton. The value_type and key_type parameters are optional and determine how data is stored.

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

### Description
Creates a new empty Automaton. Both `value_type` and `key_type` are optional.
`value_type` can be `ahocorasick.STORE_ANY` (default), `ahocorasick.STORE_LENGTH`, or `ahocorasick.STORE_INTS`.
`key_type` can be `ahocorasick.KEY_STRING` (default) or `ahocorasick.KEY_SEQUENCE`.

### Parameters
* **value_type** (enum) - Optional - Specifies how values are stored. Defaults to `ahocorasick.STORE_ANY`.
* **key_type** (enum) - Optional - Specifies the type of keys that can be stored. Defaults to `ahocorasick.KEY_STRING`.
```

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

### save

Source: https://pyahocorasick.readthedocs.io/en/latest

Saves the automaton to a file path using a specified serializer.

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

### Description
Saves the automaton to a file path using a specified serializer.

### Parameters
* **path** (string) - The file path where the automaton will be saved.
* **serializer** (callable) - A function or method used to serialize the automaton's data.
```

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

### clear

Source: https://pyahocorasick.readthedocs.io/en/latest

Removes all words and values from the automaton, making it empty.

```APIDOC
## clear()

### Description
Removes all words and values from the automaton, making it empty.

### Examples
```python
import ahocorasick

A = ahocorasick.Automaton()
A.add_word('apple', 'fruit')
A.add_word('banana', 'fruit')

A.clear()
print(len(A)) # Output: 0
```
```

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

### make_automaton

Source: https://pyahocorasick.readthedocs.io/en/latest

Finalizes the automaton construction, making it ready for searching. This method should be called after adding all words.

```APIDOC
## make_automaton()

### Description
Finalizes the automaton construction, making it ready for searching. This method should be called after adding all words.

### Examples
```python
import ahocorasick

A = ahocorasick.Automaton()
A.add_word('apple', 'fruit')
A.make_automaton() # Now the automaton is ready for search operations
```
```

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

### Automaton Class Constructor

Source: https://pyahocorasick.readthedocs.io/en/latest

Creates a new empty Automaton. Optionally accepts a value_type to specify the type of associated values (default is any Python object). The key_type can also be specified as KEY_STRING or KEY_SEQUENCE.

```APIDOC
## Automaton

### Description
Creates a new empty Automaton. Optionally accepts a value_type to specify the type of associated values (default is any Python object). The key_type can also be specified as KEY_STRING or KEY_SEQUENCE.

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

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

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

Source: https://pyahocorasick.readthedocs.io/

Returns an iterator over the values associated with keys in the trie. Filtering and matching logic is the same as the `keys()` method.

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

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

### Method
N/A (Python method)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
- **prefix** (string) - Optional - If provided, only yield values for keys starting with this prefix.
- **wildcard** (string) - Optional - A single character string used as a wildcard in the prefix pattern.
- **how** (integer) - Optional - Controls matching strategy. Possible values:
  * `ahocorasick.MATCH_EXACT_LENGTH` (default)
  * `ahocorasick.MATCH_AT_LEAST_PREFIX`
  * `ahocorasick.MATCH_AT_MOST_PREFIX`

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response
- **iterator**: An iterator yielding values from the trie, potentially filtered by the provided arguments.

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

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

### __reduce__

Source: https://pyahocorasick.readthedocs.io/en/latest

Returns a tuple used for pickling the automaton object.

```APIDOC
## __reduce__()

### Description
Returns a tuple used for pickling the automaton object. This method is part of Python's pickling protocol.

### Returns
* A tuple that enables the serialization of the automaton.
```

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

### find_all

Source: https://pyahocorasick.readthedocs.io/

Performs the Aho-Corasick search procedure on the input string and iterates over matching tuples. For each match, it invokes a provided callback function with the end index and value of the found key. The search can be limited to a specific slice of the string.

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

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

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.

### Parameters
#### Path Parameters
- **string** (string) - Required - The input string to search within.
- **callback** (callable) - Required - A function to be called for each match, accepting `end_index` and `value`.
- **start** (int) - Optional - The starting index for the search slice.
- **end** (int) - Optional - The ending index for the search slice.

### Response
This method does not return a value directly but invokes the `callback` for each match found.
```

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

### Check for Prefix Existence in Trie

Source: https://pyahocorasick.readthedocs.io/en/latest

Use the `match` method to determine if any added word has a prefix equal to the provided key. This is useful for prefix-based lookups.

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

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

### set

Source: https://pyahocorasick.readthedocs.io/en/latest

Sets a string in the automaton, potentially resetting it. This is an internal method and typically not used directly by users.

```APIDOC
## set(string, reset=False)

### Description
Sets a string in the automaton, potentially resetting it. This is an internal method and typically not used directly by users.

### Parameters
* **string** (string) - The string to set.
* **reset** (bool) - Optional - Whether to reset the automaton before setting the string. Defaults to False.
```

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

### match(key)

Source: https://pyahocorasick.readthedocs.io/

Checks if any prefix of the given key exists in the trie. This method returns True if a key that is a prefix of the input `key` has been added to the trie.

```APIDOC
## match(key)

### Description
Return True if there is a prefix (or key) equal to key present in the trie. For example if the key ‘example’ has been added to the trie, then calls to match(‘e’), match(‘ex’), …, match(‘exampl’) or match(‘example’) all return True. But exists() is True only when calling exists(‘example’).

### Method
N/A (Python method)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response
- **bool**: True if a prefix of the key exists in the trie, False otherwise.

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

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

### Saving and loading automaton

Source: https://pyahocorasick.readthedocs.io/

Methods and mechanisms for persisting and restoring the state of an Automaton object.

```APIDOC
## Pickle

### Description
Utilizes Python's `pickle` module for serializing and deserializing Automaton objects, enabling saving and loading of the automaton's state.
```

```APIDOC
## Save/load methods

### Description
Provides explicit methods (`save` and `load`) for saving the automaton to a file and loading it back, offering a structured way to manage persistence.
```

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

### items

Source: https://pyahocorasick.readthedocs.io/en/latest

Returns an iterator over the (key, value) pairs in the automaton, optionally filtered by a prefix and wildcard.

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

### Description
Returns an iterator over the (key, value) pairs in the automaton, optionally filtered by a prefix and wildcard.

### Parameters
* **prefix** (string) - Optional - If provided, only items with keys starting with this prefix are returned.
* **wildcard** (string) - Optional - Specifies a wildcard character.
* **how** (int) - Optional - Specifies the iteration order.

### Returns
* An iterator yielding (key, value) pairs from the automaton.
```

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

### Find Longest Prefix Length in Trie

Source: https://pyahocorasick.readthedocs.io/en/latest

Illustrates using the `longest_prefix()` method to find the length of the longest prefix of a given string that exists as a key in the trie. This is useful for prefix matching scenarios.

```python
>>> import ahocorasick
>>> A = ahocorasick.Automaton()
>>> A.add_word("he", True)
True
>>> A.add_word("her", True)
True
>>> A.add_word("hers", True)
True
>>> A.longest_prefix("she")
0
>>> A.longest_prefix("herself")
4
```

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

### Add Word to Automaton (STORE_INTS)

Source: https://pyahocorasick.readthedocs.io/en/latest

Demonstrates adding words to an Automaton configured with STORE_INTS. Values are optional and default to the insertion order index if not provided. Existing words can have their integer values updated.

```python
>>> import ahocorasick
>>> B = ahocorasick.Automaton(ahocorasick.STORE_INTS)
>>> B.add_word("cat")
True
>>> B.get()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
IndexError: tuple index out of range
>>> B.get("cat")
1
>>> B.add_word("dog")
True
>>> B.get("dog")
2
>>> B.add_word("tree", 42)
True
>>> B.get("tree")
42
>>> B.add_word("cat", 43)
False
>>> B.get("cat")
43
```

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

### keys

Source: https://pyahocorasick.readthedocs.io/en/latest

Returns an iterator over the keys in the trie, optionally filtered by prefix, wildcard, and search method.

```APIDOC
## keys

### Description
Returns an iterator on keys. Can be filtered by prefix and wildcard.

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

### Parameters
* **prefix** (string) - Optional - A prefix to filter keys.
* **wildcard** (string) - Optional - A character to use as a wildcard.
* **how** - Optional - Specifies the matching strategy (e.g., `ahocorasick.MATCH_EXACT_LENGTH`).
```

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

### get_stats

Source: https://pyahocorasick.readthedocs.io/en/latest

Returns a dictionary containing statistics about the automaton, such as the number of states and transitions.

```APIDOC
## get_stats() -> dict

### Description
Returns a dictionary containing statistics about the automaton, such as the number of states and transitions.

### Returns
* **dict** - A dictionary with automaton statistics.

### Examples
```python
import ahocorasick

A = ahocorasick.Automaton()
A.add_word('apple', 'fruit')
A.make_automaton()

stats = A.get_stats()
print(stats)
# Example Output:
# {'states': 6, 'transitions': 5, 'edges': 5}
```
```

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

### keys

Source: https://pyahocorasick.readthedocs.io/en/latest

Returns an iterator over the keys (words) in the automaton, optionally filtered by a prefix and wildcard.

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

### Description
Returns an iterator over the keys (words) in the automaton, optionally filtered by a prefix and wildcard.

### Parameters
* **prefix** (string) - Optional - If provided, only keys starting with this prefix are returned.
* **wildcard** (string) - Optional - Specifies a wildcard character.
* **how** (int) - Optional - Specifies the iteration order.

### Returns
* An iterator yielding keys from the automaton.
```

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

### Automaton Class Initialization

Source: https://pyahocorasick.readthedocs.io/en/latest

Initializes an Automaton object. It can store any value type or specific key types. The default value type is ahocorasick.STORE_ANY.

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

### Description
Initializes an Automaton object. It can store any value type or specific key types. The default value type is ahocorasick.STORE_ANY.

### Parameters
* **value_type** (int) - Optional - Specifies the type of values to store. Defaults to `ahocorasick.STORE_ANY`.
* **key_type** (int) - Optional - Specifies the type of keys to store.

### Examples
```python
import ahocorasick

# Initialize with default settings
A = ahocorasick.Automaton()

# Initialize to store integers as values
A = ahocorasick.Automaton(value_type=ahocorasick.STORE_INTS)
```
```

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

### Aho-Corasick methods

Source: https://pyahocorasick.readthedocs.io/

Core methods for performing Aho-Corasick searches within strings.

```APIDOC
## AutomatonSearchIter class

### Description
An iterator class used internally for efficient searching within the automaton. It yields match results during iteration.
```

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

### exists

Source: https://pyahocorasick.readthedocs.io/en/latest

Checks if a key is present in the trie. This is equivalent to using the 'in' keyword.

```APIDOC
## exists(key)

### Description
Returns True if the `key` is present in the trie. This is the same as using the ‘in’ keyword.

### Parameters
* **key** (string) - Required - The key to check for existence in the trie.
```

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

### Create an Automaton

Source: https://pyahocorasick.readthedocs.io/en/latest

Initialize an Automaton object from the pyahocorasick library. This object can be used as a trie.

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

```

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

### set

Source: https://pyahocorasick.readthedocs.io/

Sets a new string to search within the automaton. The `reset` parameter controls whether the internal state and end index are reset. Setting `reset` to `False` allows for searching large strings in smaller chunks.

```APIDOC
## set(string, reset=False)

### Description
Set a new string to search. When the reset argument is False (default) then the Aho-Corasick procedure is continued and the internal state of the Automaton and end index of the string being searched are not reset. This allow to search for large strings in multiple smaller chunks.

### Parameters
#### Path Parameters
- **string** (string) - Required - The new string to set for searching.
- **reset** (boolean) - Optional - If `False` (default), the search continues without resetting state. If `True`, the state is reset.
```

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

### Finding All Occurrences

Source: https://pyahocorasick.readthedocs.io/en/latest

Shows how to convert a trie into an Aho-Corasick automaton and then find all occurrences of stored keys within a given string. This is useful for multi-pattern searching.

```python
>>> # 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'))
```

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

### items

Source: https://pyahocorasick.readthedocs.io/en/latest

Returns an iterator over (key, value) tuples in the trie, optionally filtered by prefix, wildcard, and search method.

```APIDOC
## items

### Description
Returns an iterator on tuples of (key, value). Can be filtered by prefix and wildcard.

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

### Parameters
* **prefix** (string) - Optional - A prefix to filter items.
* **wildcard** (string) - Optional - A character to use as a wildcard.
* **how** - Optional - Specifies the matching strategy (e.g., `ahocorasick.MATCH_EXACT_LENGTH`).
```

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

### len

Source: https://pyahocorasick.readthedocs.io/en/latest

Returns the number of words currently stored in the automaton.

```APIDOC
## len() -> integer

### Description
Returns the number of words currently stored in the automaton.

### Returns
* **integer** - The total number of words in the automaton.

### Examples
```python
import ahocorasick

A = ahocorasick.Automaton()
A.add_word('apple', 'fruit')
A.add_word('banana', 'fruit')

print(len(A)) # Output: 2
```
```
Tokens:
Raw