Coverage for src/gentrie/trie/trie_mixins.py: 100%

1"""Protocol for all GeneralizedTrie trie mixins.""" 

2 

3from typing import Any, Iterator, Optional, Protocol 

4 

5from ..nodes import Node 

6from ..protocols import GeneralizedKey, TrieKeyToken 

7from ..types import TrieId, TrieEntry 

8 

9 

10class TrieMixinsInterface(Protocol): 

11 """ 

12 Protocol defining the complete public API and shared private state 

13 for all mixins used within the GeneralizedTrie implementation. 

14 """ 

15 # --- Shared Private State --- 

16 # These attributes are the "contract" for the shared data model. 

17 runtime_validation: bool 

18 _ident_counter: int 

19 _trie_index: dict[TrieId, Node] 

20 _trie_entries: dict[TrieId, TrieEntry] 

21 children: dict[TrieKeyToken, Node] 

22 ident: Optional[TrieId] 

23 parent: Optional["TrieMixinsInterface"] 

24 token: Optional[TrieKeyToken] 

25 value: Any 

26 

27 # --- Shared Public API --- 

28 # These methods form the "contract" for the shared behavior. 

29 # Any method that one mixin needs to call from another must be here. 

30 

31 # pylint: disable=missing-function-docstring 

32 

33 # From storage.py 

34 def add(self, key: GeneralizedKey, value: Optional[Any] = None) -> TrieId: ... 

35 def update(self, key: GeneralizedKey, value: Optional[Any] = None) -> TrieId: ... 

36 

37 # From access.py 

38 def __getitem__(self, key: TrieId | GeneralizedKey) -> TrieEntry: ... 

39 def __contains__(self, key_or_ident: TrieId | GeneralizedKey) -> bool: ... 

40 def get(self, key: TrieId | GeneralizedKey, default: Any = None) -> TrieEntry | Any: ... 

41 

42 # From removal.py 

43 def remove(self, key: TrieId | GeneralizedKey) -> None: ... 

44 def __delitem__(self, key: TrieId | GeneralizedKey) -> None: ... 

45 

46 # From traversal.py 

47 def prefixes(self, key: GeneralizedKey) -> Iterator[TrieEntry]: ... 

48 def prefixed_by(self, key: GeneralizedKey, depth: int = -1) -> Iterator[TrieEntry]: ... 

49 

50 # From collection.py 

51 def __iter__(self) -> Iterator[TrieId]: ... 

52 def __len__(self) -> int: ... 

53 

54 # --- Private Implementation Details --- 

55 # These are included for type-checking purposes for methods that are 

56 # defined and called within the same mixin, but where the public-facing 

57 # methods use the protocol for `self`. They are not considered part of 

58 # the public API of the final class. 

59 def _store_entry(self, key: GeneralizedKey, value: Any, allow_value_update: bool) -> TrieId: ...