Coverage for src / ezplog / 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(), 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 error(self, message: Any, *args, **kwargs) -> None: 

71 """Log an error message.""" 

72 ... 

73 

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

75 """Log a critical message.""" 

76 ... 

77 

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

79 """Log an exception with traceback.""" 

80 ... 

81 

82 # /////////////////////////////////////////////////////////////// 

83 # LOGURU-SPECIFIC METHODS 

84 # /////////////////////////////////////////////////////////////// 

85 

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

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

88 ... 

89 

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

91 """Configure logger options.""" 

92 ... 

93 

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

95 """Patch log records.""" 

96 ... 

97 

98 # /////////////////////////////////////////////////////////////// 

99 # EZPL-SPECIFIC METHODS 

100 # /////////////////////////////////////////////////////////////// 

101 

102 @property 

103 def level(self) -> str: 

104 """Get the current logging level.""" 

105 ... 

106 

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

108 """Set the logging level.""" 

109 ... 

110 

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

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

113 ... 

114 

115 def add_separator(self) -> None: 

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

117 ... 

118 

119 def get_log_file(self) -> Path: 

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

121 ... 

122 

123 def close(self) -> None: 

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

125 ... 

126 

127 

128# /////////////////////////////////////////////////////////////// 

129# PUBLIC API 

130# /////////////////////////////////////////////////////////////// 

131 

132__all__ = [ 

133 "LoggerProtocol", 

134]