Coverage for sources/librovore/interfaces.py: 50%

1# vim: set filetype=python fileencoding=utf-8: 

2# -*- coding: utf-8 -*- 

3 

4#============================================================================# 

5# # 

6# Licensed under the Apache License, Version 2.0 (the "License"); # 

7# you may not use this file except in compliance with the License. # 

8# You may obtain a copy of the License at # 

9# # 

10# http://www.apache.org/licenses/LICENSE-2.0 # 

11# # 

12# Unless required by applicable law or agreed to in writing, software # 

13# distributed under the License is distributed on an "AS IS" BASIS, # 

14# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 

15# See the License for the specific language governing permissions and # 

16# limitations under the License. # 

17# # 

18#============================================================================# 

19 

20 

21''' Common enumerations and interfaces. ''' 

22 

23 

24from . import __ 

25 

26 

27class FilterCapability( __.immut.DataclassObject ): 

28 ''' Describes a filter supported by a processor. ''' 

29 

30 name: str 

31 description: str 

32 type: str # "string", "enum", "boolean" 

33 values: __.typx.Optional[ list[ str ] ] = None # For enums 

34 required: bool = False 

35 

36 

37class DisplayFormat( __.enum.Enum ): 

38 ''' Enumeration for CLI display formats. ''' 

39 

40 JSON = 'json' 

41 Markdown = 'markdown' 

42 

43 

44class ProcessorGenera( __.enum.Enum ): 

45 ''' Enumeration for processor types/genera. ''' 

46 

47 Inventory = 'inventory' 

48 Structure = 'structure' 

49 

50 

51 

52class MatchMode( str, __.enum.Enum ): 

53 ''' Enumeration for different term matching modes. ''' 

54 

55 Exact = 'exact' 

56 Similar = 'similar' 

57 Pattern = 'pattern' 

58 

59 

60class SearchBehaviors( __.immut.DataclassObject ): 

61 ''' Search behavior configuration for the search engine. ''' 

62 

63 match_mode: MatchMode = MatchMode.Similar 

64 similarity_score_min: int = 50 

65 contains_term: __.typx.Annotated[ 

66 bool, 

67 __.ddoc.Doc( 

68 "Enable substring matching in Exact and Similar modes. " 

69 "When enabled, allows terms to match as substrings." ), 

70 ] = True 

71 case_sensitive: __.typx.Annotated[ 

72 bool, 

73 __.ddoc.Doc( 

74 "Enable case-sensitive matching. When False, " 

75 "performs case-insensitive matching (default)." ), 

76 ] = False 

77 

78 

79_search_behaviors_default = SearchBehaviors( ) 

80_filters_default = __.immut.Dictionary[ str, __.typx.Any ]( ) 

81 

82 

83class ProcessorCapabilities( __.immut.DataclassObject ): 

84 ''' Complete capability description for a processor. ''' 

85 

86 processor_name: str 

87 version: str 

88 supported_filters: list[ FilterCapability ] 

89 results_limit_max: __.typx.Optional[ int ] = None 

90 response_time_typical: __.typx.Optional[ str ] = None # "fast", etc. 

91 notes: __.typx.Optional[ str ] = None 

92 

93 def render_as_json( self ) -> dict[ str, __.typx.Any ]: 

94 ''' Renders capabilities as JSON-compatible dictionary. ''' 

95 return { 

96 'processor_name': self.processor_name, 

97 'version': self.version, 

98 'supported_filters': [ 

99 { 

100 'name': filter_cap.name, 

101 'type': filter_cap.type, 

102 'required': filter_cap.required, 

103 'description': filter_cap.description, 

104 } 

105 for filter_cap in self.supported_filters 

106 ], 

107 'results_limit_max': self.results_limit_max, 

108 'response_time_typical': self.response_time_typical, 

109 'notes': self.notes, 

110 } 

111 

112 def render_as_markdown( self ) -> tuple[ str, ... ]: 

113 ''' Renders capabilities as Markdown lines for display. ''' 

114 lines = [ f"**Version:** {self.version}" ] 

115 if self.results_limit_max: 

116 lines.append( f"**Max results:** {self.results_limit_max}" ) 

117 if self.response_time_typical: 

118 lines.append( f"**Response time:** {self.response_time_typical}" ) 

119 if self.notes: 

120 lines.append( f"**Notes:** {self.notes}" ) 

121 if self.supported_filters: 

122 lines.append( "" ) 

123 lines.append( "**Supported filters:**" ) 

124 for filter_cap in self.supported_filters: 

125 filter_line = f"- `{filter_cap.name}` ({filter_cap.type})" 

126 if filter_cap.required: 

127 filter_line += " *required*" 

128 if filter_cap.description: 

129 filter_line += f": {filter_cap.description}" 

130 lines.append( filter_line ) 

131 return tuple( lines )