Coverage for src / lexigram / contracts / core / context.py: 0%

1"""Context protocols for Lexigram Framework. 

2 

3Provides protocol definitions for request-scoped context management. 

4 

5For implementations, see ``lexigram.core.context``. 

6""" 

7 

8from __future__ import annotations 

9 

10from typing import TYPE_CHECKING, Any, Protocol, Self, runtime_checkable 

11 

12if TYPE_CHECKING: 

13 import types 

14 

15 

16@runtime_checkable 

17class ContextProtocol(Protocol): 

18 """Protocol for string-keyed context variable access.""" 

19 

20 @classmethod 

21 def register_key(cls, key: str) -> None: 

22 """Explicitly register a new context key to prevent memory leaks.""" 

23 ... 

24 

25 @classmethod 

26 def set(cls, key: str, value: Any) -> Any: 

27 """Set a context value for a registered key.""" 

28 ... 

29 

30 @classmethod 

31 def get(cls, key: str, default: Any = None) -> Any: 

32 """Get a context value.""" 

33 ... 

34 

35 @classmethod 

36 def reset(cls, key: str, token: Any) -> None: 

37 """Reset a context value using a token from ``set()``.""" 

38 ... 

39 

40 @classmethod 

41 def get_all(cls) -> dict[str, Any]: 

42 """Snapshot of all non-None context values.""" 

43 ... 

44 

45 

46@runtime_checkable 

47class RequestContextProtocol(Protocol): 

48 """Protocol for request-scoped context managers. 

49 

50 Handles proper cleanup via tokens, even if nested. 

51 """ 

52 

53 request_id: str | None 

54 method: str | None 

55 path: str | None 

56 start_time: float | None 

57 trace_id: str | None 

58 span_id: str | None 

59 trace_flags: str | None 

60 correlation_id: str | None 

61 causation_id: str | None 

62 user_id: str | None 

63 tenant_id: str | None 

64 

65 def __init__( 

66 self, 

67 request_id: str | None = None, 

68 method: str | None = None, 

69 path: str | None = None, 

70 correlation_id: str | None = None, 

71 causation_id: str | None = None, 

72 user_id: str | None = None, 

73 tenant_id: str | None = None, 

74 ) -> None: 

75 """Initialize request context.""" 

76 ... 

77 

78 def __enter__(self) -> Self: 

79 """Enter the context scope.""" 

80 ... 

81 

82 def __exit__( 

83 self, 

84 exc_type: type[BaseException] | None, 

85 exc_val: BaseException | None, 

86 exc_tb: types.TracebackType | None, 

87 ) -> None: 

88 """Exit the context scope and cleanup.""" 

89 ... 

90 

91 

92__all__ = [ 

93 "ContextProtocol", 

94 "RequestContextProtocol", 

95]