Coverage for /home/runner/work/bijux-cli/bijux-cli/src/bijux_cli/contracts/memory.py: 100%

1# SPDX-License-Identifier: MIT 

2# Copyright © 2025 Bijan Mousavi 

3 

4"""Defines the contract for the transient in-memory key-value service. 

5 

6This module specifies the `MemoryProtocol`, a formal interface that any 

7service providing a non-persistent, in-memory key-value store must 

8implement. This is used for managing ephemeral state within the CLI. 

9""" 

10 

11from __future__ import annotations 

12 

13from typing import Any, Protocol, TypeVar, runtime_checkable 

14 

15T = TypeVar("T") 

16 

17 

18@runtime_checkable 

19class MemoryProtocol(Protocol): 

20 """Defines the contract for a simple in-memory key-value store. 

21 

22 This interface specifies the essential methods for a basic key-value data 

23 storage service. It is used for managing ephemeral state within the CLI 

24 that does not need to persist across sessions. 

25 """ 

26 

27 def get(self, key: str) -> Any: 

28 """Retrieves a value by its key. 

29 

30 Args: 

31 key (str): The key of the value to retrieve. 

32 

33 Returns: 

34 Any: The value associated with the key. 

35 

36 Raises: 

37 KeyError: If the key does not exist in the store. 

38 """ 

39 ... 

40 

41 def set(self, key: str, value: Any) -> None: 

42 """Sets a key-value pair in the store. 

43 

44 If the key already exists, its value will be overwritten. 

45 

46 Args: 

47 key (str): The key for the value being set. 

48 value (Any): The value to store. 

49 

50 Returns: 

51 None: 

52 """ 

53 ... 

54 

55 def delete(self, key: str) -> None: 

56 """Deletes a key-value pair by its key. 

57 

58 Args: 

59 key (str): The key of the value to delete. 

60 

61 Raises: 

62 KeyError: If the key does not exist in the store. 

63 """ 

64 ... 

65 

66 def clear(self) -> None: 

67 """Removes all key-value pairs from the store.""" 

68 ... 

69 

70 def keys(self) -> list[str]: 

71 """Returns a list of all keys currently in the store. 

72 

73 Returns: 

74 list[str]: A list of all string keys. 

75 """ 

76 ...