Coverage for src / lexigram / contracts / infra / state.py: 0%

1"""State storage protocols for Lexigram Framework.""" 

2 

3from __future__ import annotations 

4 

5from typing import Any, Protocol, runtime_checkable 

6 

7 

8@runtime_checkable 

9class StateStoreProtocol(Protocol): 

10 """Persistent key-value store for arbitrary application state. 

11 

12 Supports bulk read/write operations on top of the basic get/set/delete 

13 primitives. Implementations may use any persistent backend (SQL, Redis, 

14 blob storage) that satisfies the interface. 

15 

16 Typical usage:: 

17 

18 state = await container.resolve(StateStoreProtocol) 

19 await state.set("session:abc123", {"user_id": "u-1"}, ttl=3600) 

20 data = await state.get("session:abc123") 

21 """ 

22 

23 async def get(self, key: str) -> Any | None: 

24 """Get a value by key. 

25 

26 Args: 

27 key: The key to retrieve. 

28 

29 Returns: 

30 The value if found, None otherwise. 

31 """ 

32 ... 

33 

34 async def set(self, key: str, value: Any, ttl: int | None = None) -> None: 

35 """Set a value with optional TTL. 

36 

37 Args: 

38 key: The key to set. 

39 value: The value to store. 

40 ttl: Optional time-to-live in seconds. 

41 """ 

42 ... 

43 

44 async def delete(self, key: str) -> bool: 

45 """Delete a key. 

46 

47 Args: 

48 key: The key to delete. 

49 

50 Returns: 

51 True if deleted, False if not found. 

52 """ 

53 ... 

54 

55 async def exists(self, key: str) -> bool: 

56 """Check if a key exists. 

57 

58 Args: 

59 key: The key to check. 

60 

61 Returns: 

62 True if exists, False otherwise. 

63 """ 

64 ... 

65 

66 async def expire(self, key: str, ttl: int) -> bool: 

67 """Set expiration on a key. 

68 

69 Args: 

70 key: The key to expire. 

71 ttl: Time-to-live in seconds. 

72 

73 Returns: 

74 True if timeout was set, False if key doesn't exist. 

75 """ 

76 ... 

77 

78 async def ttl(self, key: str) -> int: 

79 """Get remaining TTL for a key. 

80 

81 Args: 

82 key: The key to check. 

83 

84 Returns: 

85 TTL in seconds, -1 if no expiry, -2 if key doesn't exist. 

86 """ 

87 ... 

88 

89 async def get_many(self, keys: list[str]) -> dict[str, Any]: 

90 """Return a mapping of *keys* → values for all keys that exist. 

91 

92 Args: 

93 keys: List of storage keys to fetch. 

94 

95 Returns: 

96 Dict containing only keys that were found; absent keys are omitted. 

97 """ 

98 ... 

99 

100 async def set_many(self, items: dict[str, Any], ttl: int | None = None) -> None: 

101 """Persist multiple key-value pairs in a single operation. 

102 

103 Args: 

104 items: Mapping of storage keys to JSON-serializable values. 

105 ttl: Optional time-to-live in seconds applied to all entries. 

106 """ 

107 ... 

108 

109 

110__all__ = ["StateStoreProtocol"]