Coverage for src / ezpl / core / interfaces.py: 100.00%

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

2# EZPL - Core Interfaces 

3# Project: ezpl 

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

5 

6""" 

7Core interfaces for Ezpl logging framework. 

8 

9This module defines the core abstract base classes and protocols used 

10throughout the application. ABCs provide strict interfaces with runtime 

11enforcement for handler implementations, while Protocols provide structural 

12typing for flexible, duck-typed configuration management. 

13""" 

14 

15from __future__ import annotations 

16 

17# /////////////////////////////////////////////////////////////// 

18# IMPORTS 

19# /////////////////////////////////////////////////////////////// 

20# Standard library imports 

21from abc import ABC, abstractmethod 

22from contextlib import AbstractContextManager 

23from pathlib import Path 

24from typing import Any, Protocol 

25 

26# /////////////////////////////////////////////////////////////// 

27# ABSTRACT BASE CLASSES 

28# /////////////////////////////////////////////////////////////// 

29 

30 

31class LoggingHandler(ABC): 

32 """ 

33 Abstract base class for logging handlers. 

34 

35 All logging handlers (EzPrinter, EzLogger) must inherit from this class 

36 and implement the required methods. 

37 """ 

38 

39 @property 

40 @abstractmethod 

41 def level(self) -> str: 

42 """Get the current logging level.""" 

43 ... 

44 

45 @abstractmethod 

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

47 """Log a message with the specified level.""" 

48 ... 

49 

50 @abstractmethod 

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

52 """Set the logging level.""" 

53 ... 

54 

55 

56class IndentationManager(ABC): 

57 """ 

58 Abstract base class for indentation management. 

59 

60 Handlers that support indentation (e.g., EzPrinter) must inherit from 

61 this class and implement the required methods. 

62 """ 

63 

64 @abstractmethod 

65 def get_indent(self) -> str: 

66 """Get the current indentation string.""" 

67 ... 

68 

69 @abstractmethod 

70 def add_indent(self) -> None: 

71 """Increase the indentation level.""" 

72 ... 

73 

74 @abstractmethod 

75 def del_indent(self) -> None: 

76 """Decrease the indentation level.""" 

77 ... 

78 

79 @abstractmethod 

80 def reset_indent(self) -> None: 

81 """Reset the indentation level to zero.""" 

82 ... 

83 

84 @abstractmethod 

85 def manage_indent(self) -> AbstractContextManager[None]: 

86 """Context manager for temporary indentation.""" 

87 ... 

88 

89 

90# /////////////////////////////////////////////////////////////// 

91# PROTOCOLS 

92# /////////////////////////////////////////////////////////////// 

93 

94 

95class ConfigurationManager(Protocol): 

96 """ 

97 Protocol for configuration management. 

98 

99 This structural typing protocol defines the interface for configuration 

100 managers. Implementations can support different configuration sources 

101 (files, environment, in-memory) without coupling to a specific backend. 

102 """ 

103 

104 def get(self, key: str, default: Any = None) -> Any: 

105 """Get a configuration value.""" 

106 ... 

107 

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

109 """Set a configuration value.""" 

110 ... 

111 

112 def get_log_level(self) -> str: 

113 """Get the current log level.""" 

114 ... 

115 

116 def get_log_file(self) -> Path: 

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

118 ... 

119 

120 def get_printer_level(self) -> str: 

121 """Get the current printer level.""" 

122 ... 

123 

124 def get_file_logger_level(self) -> str: 

125 """Get the current file logger level.""" 

126 ... 

127 

128 def save(self) -> None: 

129 """Save configuration to file.""" 

130 ...