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

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

2

3 from typing import Any, Iterator, Optional, Protocol

4

5 from ..nodes import Node

6 from ..protocols import GeneralizedKey, TrieKeyToken

7 from ..types import TrieId, TrieEntry

8

9

10 class 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: ...