Coverage for src / ezpl / types / protocols / logger_protocol.py: 100.00%

1# /////////////////////////////////////////////////////////////// 

2# EZPL - Logger Protocol 

3# Project: ezpl 

4# /////////////////////////////////////////////////////////////// 

5 

6""" 

7Logger Protocol for Ezpl logging framework. 

8 

9This module defines the Protocol (abstract interface) that all logger 

10implementations must follow. It provides type checking and ensures 

11consistent API across different logger implementations. 

12""" 

13 

14from __future__ import annotations 

15 

16# /////////////////////////////////////////////////////////////// 

17# IMPORTS 

18# /////////////////////////////////////////////////////////////// 

19# Standard library imports 

20from pathlib import Path 

21from typing import Any, Protocol, runtime_checkable 

22 

23# /////////////////////////////////////////////////////////////// 

24# PROTOCOLS 

25# /////////////////////////////////////////////////////////////// 

26 

27 

28@runtime_checkable 

29class LoggerProtocol(Protocol): 

30 """ 

31 Protocol defining the interface for logger implementations. 

32 

33 All logger implementations must conform to this protocol to ensure 

34 consistent API and type safety. 

35 

36 **Required Methods:** 

37 - Logging methods: info(), debug(), success(), warning(), warn(), error(), critical(), trace(), bind() 

38 - Utility methods: set_level(), log(), add_separator() 

39 - Getter methods: get_logger(), get_log_file() 

40 

41 **Note:** 

42 This protocol is designed to be compatible with loguru.Logger 

43 while allowing custom implementations. 

44 """ 

45 

46 # /////////////////////////////////////////////////////////////// 

47 # CORE LOGGING METHODS (loguru-compatible) 

48 # /////////////////////////////////////////////////////////////// 

49 

50 def trace(self, message: Any, *args, **kwargs) -> None: 

51 """Log a trace message.""" 

52 ... 

53 

54 def debug(self, message: Any, *args, **kwargs) -> None: 

55 """Log a debug message.""" 

56 ... 

57 

58 def info(self, message: Any, *args, **kwargs) -> None: 

59 """Log an info message.""" 

60 ... 

61 

62 def success(self, message: Any, *args, **kwargs) -> None: 

63 """Log a success message.""" 

64 ... 

65 

66 def warning(self, message: Any, *args, **kwargs) -> None: 

67 """Log a warning message.""" 

68 ... 

69 

70 def warn(self, message: Any, *args, **kwargs) -> None: 

71 """Alias for warning(). Log a warning message.""" 

72 ... 

73 

74 def error(self, message: Any, *args, **kwargs) -> None: 

75 """Log an error message.""" 

76 ... 

77 

78 def critical(self, message: Any, *args, **kwargs) -> None: 

79 """Log a critical message.""" 

80 ... 

81 

82 def exception(self, message: Any, *args, **kwargs) -> None: 

83 """Log an exception with traceback.""" 

84 ... 

85 

86 # /////////////////////////////////////////////////////////////// 

87 # LOGURU-SPECIFIC METHODS 

88 # /////////////////////////////////////////////////////////////// 

89 

90 def bind(self, **kwargs: Any) -> Any: 

91 """Bind context variables to the logger.""" 

92 ... 

93 

94 def opt(self, **kwargs: Any) -> Any: 

95 """Configure logger options.""" 

96 ... 

97 

98 def patch(self, patcher: Any) -> Any: 

99 """Patch log records.""" 

100 ... 

101 

102 # /////////////////////////////////////////////////////////////// 

103 # EZPL-SPECIFIC METHODS 

104 # /////////////////////////////////////////////////////////////// 

105 

106 @property 

107 def level(self) -> str: 

108 """Get the current logging level.""" 

109 ... 

110 

111 def set_level(self, level: str) -> None: 

112 """Set the logging level.""" 

113 ... 

114 

115 def log(self, level: str, message: Any) -> None: 

116 """Log a message with specified level.""" 

117 ... 

118 

119 def add_separator(self) -> None: 

120 """Add a session separator to the log file.""" 

121 ... 

122 

123 def get_log_file(self) -> Path: 

124 """Get the current log file path.""" 

125 ... 

126 

127 def close(self) -> None: 

128 """Close the logger and release resources.""" 

129 ...