Coverage for src/local_deep_research/settings/base.py: 70%

1""" 

2Base interface for settings management. 

3 

4This module defines the abstract base class that all settings managers 

5must implement, ensuring a consistent interface. 

6""" 

7 

8from abc import ABC, abstractmethod 

9from typing import Any, Dict, Optional, Union 

10 

11 

12class ISettingsManager(ABC): 

13 """Abstract base class for settings managers.""" 

14 

15 @abstractmethod 

16 def get_setting( 

17 self, key: str, default: Any = None, check_env: bool = True 

18 ) -> Any: 

19 """ 

20 Get a setting value. 

21 

22 Args: 

23 key: Setting key 

24 default: Default value if setting is not found 

25 check_env: If true, check environment variables first 

26 

27 Returns: 

28 Setting value or default if not found 

29 

30 Raises: 

31 SettingsValueError: The selected value cannot be converted to its 

32 declared type, or that type is unsupported. 

33 """ 

34 pass 

35 

36 @abstractmethod 

37 def set_setting(self, key: str, value: Any, commit: bool = True) -> bool: 

38 """ 

39 Set a setting value. 

40 

41 Args: 

42 key: Setting key 

43 value: Setting value 

44 commit: Whether to commit the change 

45 

46 Returns: 

47 True if successful, False otherwise 

48 """ 

49 pass 

50 

51 @abstractmethod 

52 def get_all_settings( 

53 self, 

54 bypass_cache: bool = False, 

55 include_environment_overrides: bool = True, 

56 strict: bool = False, 

57 ) -> Dict[str, Any]: 

58 """ 

59 Get all settings. 

60 

61 Args: 

62 bypass_cache: If true, bypass any implementation cache. 

63 include_environment_overrides: If true, overlay current LDR_* values. 

64 strict: If true, propagate database and enum query failures. 

65 

66 Returns: 

67 Dictionary of all settings with metadata 

68 

69 Raises: 

70 SettingsValueError: With ``include_environment_overrides``, any 

71 effective value cannot be converted to its declared type, or 

72 that type is unsupported. 

73 """ 

74 pass 

75 

76 @abstractmethod 

77 def create_or_update_setting( 

78 self, setting: Union[Dict[str, Any], Any], commit: bool = True 

79 ) -> Optional[Any]: 

80 """ 

81 Create or update a setting. 

82 

83 Args: 

84 setting: Setting object or dictionary 

85 commit: Whether to commit the change 

86 

87 Returns: 

88 The created or updated Setting model, or None if failed 

89 """ 

90 pass 

91 

92 @abstractmethod 

93 def delete_setting( 

94 self, key: str, commit: bool = True, override_locked: bool = False 

95 ) -> bool: 

96 """ 

97 Delete a setting. 

98 

99 Args: 

100 key: Setting key 

101 commit: Whether to commit the change 

102 override_locked: Delete even when settings are locked. 

103 

104 Returns: 

105 True if successful, False otherwise 

106 """ 

107 pass 

108 

109 @abstractmethod 

110 def get_bool_setting( 

111 self, key: str, default: bool = False, check_env: bool = True 

112 ) -> bool: 

113 """ 

114 Get a setting value as a boolean. 

115 

116 Args: 

117 key: Setting key 

118 default: Default boolean value if setting is not found 

119 check_env: If true, check environment variables first 

120 

121 Returns: 

122 Boolean value of the setting 

123 """ 

124 pass 

125 

126 @abstractmethod 

127 def get_settings_snapshot(self, strict: bool = False) -> Dict[str, Any]: 

128 """ 

129 Get a simplified settings snapshot with just key-value pairs. 

130 

131 Args: 

132 strict: If true, propagate database and enum query failures. 

133 

134 Returns: 

135 Dictionary with setting keys mapped to their values 

136 """ 

137 pass 

138 

139 @abstractmethod 

140 def load_from_defaults_file( 

141 self, 

142 commit: bool = True, 

143 preserve_environment_locked: bool = False, 

144 ) -> None: 

145 """ 

146 Import settings from the defaults settings file. 

147 

148 Deliberately does not accept ``**kwargs``: forwarding them would 

149 expose ``import_settings``' settings-lock bypass 

150 (``override_locked``) through this wrapper (#5841). Trusted 

151 bootstrap callers spend the bypass via direct ``import_settings`` 

152 calls. 

153 

154 Args: 

155 commit: Whether to commit changes to database 

156 preserve_environment_locked: Preserve stored values for 

157 settings with active environment overrides while imported 

158 metadata is refreshed 

159 """ 

160 pass 

161 

162 @abstractmethod 

163 def import_settings( 

164 self, 

165 settings_data: Dict[str, Any], 

166 commit: bool = True, 

167 overwrite: bool = True, 

168 delete_extra: bool = False, 

169 preserve_environment_locked: bool = False, 

170 override_locked: bool = False, 

171 ) -> None: 

172 """ 

173 Import settings from a dictionary. 

174 

175 Args: 

176 settings_data: The raw settings data to import 

177 commit: Whether to commit the DB after loading 

178 overwrite: If true, overwrite existing settings 

179 delete_extra: If true, delete settings not in settings_data 

180 preserve_environment_locked: If true, preserve the stored value 

181 for settings with active environment overrides while imported 

182 metadata may refresh 

183 override_locked: Import even when settings are locked. 

184 """ 

185 pass