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

1"""Key-Value Storage protocols. 

2 

3This module defines the protocols for Key-Value storage backends. 

4""" 

5 

6from __future__ import annotations 

7 

8from enum import StrEnum 

9from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable 

10 

11if TYPE_CHECKING: 

12 from lexigram.contracts.core import HealthCheckResult 

13 

14 

15class StorageType(StrEnum): 

16 """Types of storage backends.""" 

17 

18 MEMORY = "memory" 

19 FILE = "file" 

20 REDIS = "redis" 

21 DATABASE = "database" 

22 S3 = "s3" 

23 OTHER = "other" 

24 

25 

26@runtime_checkable 

27class StorageBackendProtocol(Protocol): 

28 """Protocol for Key-Value storage backends. 

29 

30 Defines the interface for simple KV storage operations with 

31 support for namespacing and TTL. 

32 """ 

33 

34 @property 

35 def storage_type(self) -> StorageType: 

36 """Get the type of storage backend.""" 

37 ... 

38 

39 async def connect(self) -> None: 

40 """Initialize connection to storage backend.""" 

41 ... 

42 

43 async def disconnect(self) -> None: 

44 """Close connection to storage backend.""" 

45 ... 

46 

47 async def get(self, key: str, namespace: str | None = None) -> Any | None: 

48 """Get value by key. 

49 

50 Args: 

51 key: Storage key. 

52 namespace: Optional namespace. 

53 

54 Returns: 

55 Stored value or None if not found. 

56 """ 

57 ... 

58 

59 async def set( 

60 self, 

61 key: str, 

62 value: Any, 

63 namespace: str | None = None, 

64 ttl: int | None = None, 

65 ) -> bool: 

66 """Set value by key. 

67 

68 Args: 

69 key: Storage key. 

70 value: Value to store (must be serializable). 

71 namespace: Optional namespace. 

72 ttl: Time-to-live in seconds. 

73 

74 Returns: 

75 True if successful. 

76 """ 

77 ... 

78 

79 async def delete(self, key: str, namespace: str | None = None) -> bool: 

80 """Delete value by key. 

81 

82 Args: 

83 key: Storage key. 

84 namespace: Optional namespace. 

85 

86 Returns: 

87 True if deleted, False if not found. 

88 """ 

89 ... 

90 

91 async def exists(self, key: str, namespace: str | None = None) -> bool: 

92 """Check if key exists. 

93 

94 Args: 

95 key: Storage key. 

96 namespace: Optional namespace. 

97 

98 Returns: 

99 True if exists. 

100 """ 

101 ... 

102 

103 async def list_keys( 

104 self, 

105 pattern: str | None = None, 

106 namespace: str | None = None, 

107 ) -> list[str]: 

108 """List keys matching pattern. 

109 

110 Args: 

111 pattern: Glob-style pattern (e.g., "user:*"). 

112 namespace: Optional namespace. 

113 

114 Returns: 

115 List of matching keys. 

116 """ 

117 ... 

118 

119 async def clear(self, namespace: str | None = None) -> bool: 

120 """Clear all keys in namespace. 

121 

122 Args: 

123 namespace: Optional namespace. 

124 

125 Returns: 

126 True if successful. 

127 """ 

128 ... 

129 

130 async def health_check(self, timeout: float = 5.0) -> HealthCheckResult: 

131 """Check storage health. 

132 

133 Returns: 

134 Health check result. 

135 """ 

136 ... 

137 

138 

139__all__ = ["StorageBackendProtocol", "StorageType"]