tinytrie 0.1.0a0__py2.py3-none-any.whl

tinytrie-0.1.0a0.dist-info/METADATA

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: tinytrie
+Version: 0.1.0a0
+Summary: A minimal type-safe trie (prefix tree) implementation in Python.
+Author-email: Jifeng Wu <jifengwu2k@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jifengwu2k/tinytrie
+Project-URL: Bug Tracker, https://github.com/jifengwu2k/tinytrie/issues
+Keywords: trie,prefix tree,data structure,python
+Classifier: Programming Language :: Python :: 2
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=2
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# TinyTrie
+
+A minimal and type-safe trie (prefix tree) implementation for Python 2+.
+
+## Features
+
+- **Typed**: Works with arbitrary key and value types (`Generic[K, V]`)
+- **Minimal**: Only essential functionalities
+- **Efficient**: Memory-efficient with `__slots__`
+- **Iterable**: Easily traverse and list all stored sequences
+- **No external dependencies** (except `typing` on Python <3.5)
+
+## Basic Operations
+
+```python 
+from tinytrie import *
+
+# Create a trie with character (`str`) keys and integer values
+root = TrieNode[str, int]()
+
+# Insert some words with values
+update(root, "apple", 1)
+update(root, "app", 2)
+update(root, "banana", 3)
+update(root, "band", 4)
+
+# Search for existing words
+assert search(root, "apple").value == 1
+assert search(root, "app").value == 2
+assert search(root, "banana").value == 3
+
+# Search for non-existent words
+assert search(root, "orange") is None
+assert search(root, "appetizer") is None
+
+update(root, "apple", 10)
+assert search(root, "apple").value == 10  # Value updated
+
+# Insert a new word
+update(root, "orange", 5)
+assert search(root, "orange").value == 5
+
+# Delete "apple", "app" remains
+assert delete(root, "apple") is True
+assert search(root, "apple") is None
+assert delete(root, "apple") is False
+assert search(root, "app") is not None
+
+# Add back "apple", delete "app", "apple" remains
+update(root, "apple", 10)
+assert delete(root, "app") is True
+assert search(root, "app") is None
+assert delete(root, "app") is False
+assert search(root, "apple") is not None
+
+# Try to delete non-existent words
+assert delete(root, "ban") is False
+assert delete(root, "appetizer") is False
+
+# Get common prefix from root (no common prefix)
+prefix, node = longest_common_prefix(root)
+assert prefix == []  # No common prefix among all words
+
+# Get common prefix from "b" subtree
+prefix, node = longest_common_prefix(root.children["b"])
+assert prefix == ["a", "n"]  # Common between "banana" and "band" after "b"
+
+
+# Get all words in the trie
+words = ["".join(s) for s, _ in collect_sequences(root)]
+assert set(words) == {"apple", "banana", "band", "orange"}
+```
+
+## Non-String Keys Example
+
+```python
+from tinytrie import *
+
+# Create a trie with tuple keys
+trajectory_trie = TrieNode[Tuple[int, int], str]()
+update(trajectory_trie, [(1,2), (3,4)], "traj1")
+update(trajectory_trie, [(1,2), (5,6)], "traj2")
+
+assert search(trajectory_trie, [(1,2), (3,4)]).value == "traj1"
+assert search(trajectory_trie, [(1,2), (5,6)]).value == "traj2"
+assert search(trajectory_trie, [(1,2)]) is None  # Partial path
+
+prefix, _ = longest_common_prefix(trajectory_trie)
+assert prefix == [(1, 2)]
+```
+
+## Contributing
+
+Contributions are welcome! Please submit pull requests or open issues on the GitHub repository.
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

tinytrie-0.1.0a0.dist-info/RECORD

@@ -0,0 +1,6 @@
+tinytrie.py,sha256=hT5rc8cP9-CDVJ0-_Z-jT062gVDIBOlvpiqs6meAfpg,5063
+tinytrie-0.1.0a0.dist-info/licenses/LICENSE,sha256=FZ9XWedK_wQ4wfqVanrQVQpArRHDkxwxic2rgii1pZg,1066
+tinytrie-0.1.0a0.dist-info/METADATA,sha256=vmwIxccv50ZXy14D929swdPQcJEHXQYm9aGTRXkdPRU,3434
+tinytrie-0.1.0a0.dist-info/WHEEL,sha256=JNWh1Fm1UdwIQV075glCn4MVuCRs0sotJIq-J6rbxCU,109
+tinytrie-0.1.0a0.dist-info/top_level.txt,sha256=LmhFpKkudLkEcL3grI6tGPlXow6ouTLGawd4KyatyVw,9
+tinytrie-0.1.0a0.dist-info/RECORD,,

tinytrie-0.1.0a0.dist-info/WHEEL

@@ -0,0 +1,6 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py2-none-any
+Tag: py3-none-any
+

tinytrie-0.1.0a0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jifeng Wu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tinytrie-0.1.0a0.dist-info/top_level.txt

@@ -0,0 +1 @@
+tinytrie

tinytrie.py

@@ -0,0 +1,162 @@
+# tinytrie: A minimal and type-safe trie (prefix tree) implementation in Python.
+# Copyright (c) 2025 Jifeng Wu
+# Licensed under the MIT License. See LICENSE file in the project root for full license information.
+from typing import TypeVar, Generic, Dict, Optional, Sequence, List, Tuple, Iterator
+
+K = TypeVar("K")
+V = TypeVar("V")
+
+class TrieNode(Generic[K, V]):
+    """A node in the trie structure.
+
+    Attributes:
+        children: Dictionary mapping keys to child nodes
+        is_end: Boolean indicating if this node completes a sequence
+        value: Optional value associated with this node if is_end is True"""
+    __slots__ = ("children", "is_end", "value")
+
+    def __init__(self):
+        self.children = {} # type: Dict[K, TrieNode[K, V]]
+
+        self.is_end = False # type: bool
+        self.value = None # type: Optional[V]
+
+
+def search(root, sequence, index=0):
+    # type: (TrieNode[K, V], Sequence[K], int) -> Optional[TrieNode[K, V]]
+    """Search for a sequence in the trie.
+
+    Args:
+        root: Root node of the trie
+        sequence: Sequence of keys to search for
+        index: Current index in sequence (used internally for recursion)
+
+    Returns:
+        The terminal node if found, None otherwise
+
+    Time complexity: O(n) where n is length of sequence"""
+    if index >= len(sequence):
+        if root.is_end:
+            return root
+        else:
+            return None
+    else:
+        key = sequence[index]
+        if key not in root.children:
+            return None
+        else:
+            return search(root.children[key], sequence, index + 1)
+
+
+def update(root, sequence, value=None, index=0):
+    # type: (TrieNode[K, V], Sequence[K], Optional[V], int) -> TrieNode[K, V]
+    """Search for a sequence, creating nodes if not found, and set a value for the terminal node.
+
+    Args:
+        root: Root node of the trie
+        sequence: Sequence of keys to insert
+        value: Value to associate with the terminal node
+        index: Current index in sequence (used internally for recursion)
+
+    Returns:
+        The terminal node for the sequence
+
+    Time complexity: O(n) where n is length of sequence"""
+    if index >= len(sequence):
+        if not root.is_end:
+            root.is_end = True
+
+        root.value = value
+        return root
+    else:
+        key = sequence[index]
+        if key not in root.children:
+            root.children[key] = TrieNode()
+        return update(root.children[key], sequence, value, index + 1)
+
+
+def delete(root, sequence, index=0):
+    # type: (TrieNode[K, V], Sequence[K], int) -> bool
+    """Delete a sequence from the trie.
+
+    Args:
+        root: Root node of the trie
+        sequence: Sequence to delete
+        index: Current index in sequence (used internally for recursion)
+
+    Returns:
+        True if sequence was found and deleted, False otherwise
+
+    Time complexity: O(n) where n is length of sequence"""
+    if index >= len(sequence):
+        if not root.is_end:
+            return False  # Sequence not found
+        else:
+            root.is_end = False
+            root.value = None
+            return True  # Sequence found and marked as deleted
+    else:
+        key = sequence[index]
+        if key not in root.children:
+            return False  # Sequence not found
+        else:
+            child = root.children[key]
+            deleted = delete(child, sequence, index + 1)
+
+        if not deleted:
+            return False
+        else:
+            # Prune the child if it's now a leaf node and not a terminal
+            if not child.is_end and not child.children:
+                del root.children[key]
+
+            return True
+
+
+def longest_common_prefix(root):
+    # type: (TrieNode[K, V]) -> Tuple[Sequence[K], TrieNode[K, V]]
+    """Find the longest sequence that is a prefix of all sequences in the trie.
+
+    Args:
+        root: Root node of the trie
+
+    Returns:
+        Tuple of (prefix sequence, terminal node)
+
+    Time complexity: O(m) where m is length of longest common prefix"""
+    prefix = []
+    node = root
+
+    while True:
+        # Stop if node is end of word or has multiple children
+        if node.is_end or len(node.children) != 1:
+            break
+        # Get the only child
+        key, next_node = next(iter(node.children.items()))
+        prefix.append(key)
+        node = next_node
+
+    return prefix, node
+
+
+def collect_sequences(root, prefix=None):
+    # type: (TrieNode[K, V], Optional[List[K]]) -> Iterator[Tuple[List[K], TrieNode[K, V]]]
+    """Generate all sequences stored in the trie.
+    Args:
+        root: Root node of the trie
+        prefix: Current prefix (used internally for recursion)
+
+    Yields:
+        Tuples of (sequence, terminal node) for all stored sequences
+
+    Time complexity: O(n) per sequence where n is average sequence length"""
+    if prefix is None:
+        prefix = []
+
+    if root.is_end:
+        yield prefix.copy(), root
+
+    for key, child in root.children.items():
+        prefix.append(key)
+        yield from collect_sequences(child, prefix)
+        prefix.pop()