Coverage for src / ezplog / __init__.py: 92.59%

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

2# EZPL - Main Module 

3# Project: ezpl 

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

5 

6""" 

7Ezpl - Modern Python logging framework. 

8 

9Ezpl is a modern Python library for advanced log management, using **Rich** 

10for console output and **loguru** for file logging, with a simple and typed API, 

11suitable for professional and industrial applications. 

12 

13**Main Features:** 

14 - Singleton pattern for global logging instance 

15 - Rich-based console output with colors and formatting 

16 - Loguru-based file logging with rotation support 

17 - Contextual indentation management 

18 - Pattern-based logging (SUCCESS, ERROR, WARN, TIP, etc.) 

19 - JSON display support 

20 - Robust error handling 

21 

22**Two usage modes:** 

23 

24*App mode* — configure once at application level: 

25 

26 >>> from ezplog import Ezpl 

27 >>> ezpl = Ezpl(log_file="app.log", hook_logger=True, lock_config=True) 

28 >>> ezpl.info("Application started") # direct facade 

29 >>> ezpl.get_printer().success("Ready") # advanced usage 

30 

31*Lib mode* — passive proxies for library authors: 

32 

33 >>> from ezplog.lib_mode import get_logger, get_printer 

34 >>> log = get_logger(__name__) 

35 >>> printer = get_printer() 

36 >>> log.info("Library initialized") # silent without host config 

37 >>> printer.success("Library initialized") # silent without host config 

38""" 

39 

40from __future__ import annotations 

41 

42# /////////////////////////////////////////////////////////////// 

43# IMPORTS 

44# /////////////////////////////////////////////////////////////// 

45# Standard library imports 

46import sys 

47 

48# Local imports 

49from ._version import __version__ 

50from .app_mode import InterceptHandler 

51from .config import ConfigurationManager 

52from .core.exceptions import ( 

53 ConfigurationError, 

54 EzplError, 

55 FileOperationError, 

56 HandlerError, 

57 InitializationError, 

58 LoggingError, 

59 ValidationError, 

60) 

61from .ezpl import Ezpl 

62from .handlers import EzLogger, EzPrinter, RichWizard 

63from .handlers.wizard.dynamic import DynamicLayeredProgress, StageConfig 

64from .lib_mode import get_logger, get_printer 

65from .types import ( 

66 PATTERN_COLORS, 

67 LoggerProtocol, 

68 LogLevel, 

69 Pattern, 

70 PrinterProtocol, 

71 get_pattern_color, 

72 get_pattern_color_by_name, 

73) 

74 

75# /////////////////////////////////////////////////////////////// 

76# META INFORMATIONS 

77# /////////////////////////////////////////////////////////////// 

78 

79__author__ = "Neuraaak" 

80__maintainer__ = "Neuraaak" 

81__description__ = "A module for easier logging" 

82__python_requires__ = ">=3.11" 

83__keywords__ = ["logging", "rich", "loguru", "console", "file"] 

84__url__ = "https://github.com/neuraaak/ezplog" 

85__repository__ = "https://github.com/neuraaak/ezplog" 

86 

87# /////////////////////////////////////////////////////////////// 

88# PYTHON VERSION CHECK 

89# /////////////////////////////////////////////////////////////// 

90 

91if sys.version_info < (3, 11): # noqa: UP036 91 ↛ 92line 91 didn't jump to line 92 because the condition on line 91 was never true

92 raise RuntimeError( 

93 f"Ezpl {__version__} requires Python 3.11 or higher. " 

94 f"Current version: {sys.version}" 

95 ) 

96 

97# /////////////////////////////////////////////////////////////// 

98# TYPE ALIASES 

99# /////////////////////////////////////////////////////////////// 

100 

101Printer = EzPrinter 

102"""Type alias for EzPrinter (console printer handler). 

103Use this type when you want to annotate a variable that represents a printer. 

104 

105Example: 

106 >>> from ezplog import Ezpl, Printer 

107 >>> ezpl = Ezpl() 

108 >>> printer: Printer = ezpl.get_printer() 

109 >>> printer.info("Hello!") 

110 >>> printer.success("Done!") 

111 >>> printer.print_json({"key": "value"}) 

112""" 

113 

114Logger = EzLogger 

115"""Type alias for EzLogger (file logger handler). 

116Use this type when you want to annotate a variable that represents a logger. 

117 

118Example: 

119 >>> from ezplog import Ezpl, Logger 

120 >>> ezpl = Ezpl() 

121 >>> logger: Logger = ezpl.get_logger() 

122 >>> logger.info("Logged to file") 

123""" 

124 

125# /////////////////////////////////////////////////////////////// 

126# PUBLIC API 

127# /////////////////////////////////////////////////////////////// 

128 

129__all__ = [ 

130 # Main class exports 

131 "Ezpl", 

132 # App mode — stdlib interception 

133 "InterceptHandler", 

134 # Lib mode — passive proxies for library authors 

135 "get_logger", 

136 "get_printer", 

137 # Handler class exports 

138 "EzPrinter", 

139 "EzLogger", 

140 "RichWizard", 

141 "DynamicLayeredProgress", 

142 "StageConfig", 

143 # Configuration exports 

144 "ConfigurationManager", 

145 # Type aliases exports 

146 "Printer", 

147 "Logger", 

148 # Type & pattern exports 

149 "LogLevel", 

150 "Pattern", 

151 "PATTERN_COLORS", 

152 "get_pattern_color", 

153 "get_pattern_color_by_name", 

154 # Protocol exports 

155 "PrinterProtocol", 

156 "LoggerProtocol", 

157 # Exception exports 

158 "EzplError", 

159 "ConfigurationError", 

160 "LoggingError", 

161 "ValidationError", 

162 "InitializationError", 

163 "FileOperationError", 

164 "HandlerError", 

165]