@@ -1,3 +1,20 @@
1+'''
2+searx is free software: you can redistribute it and/or modify
3+it under the terms of the GNU Affero General Public License as published by
4+the Free Software Foundation, either version 3 of the License, or
5+(at your option) any later version.
6+
7+searx is distributed in the hope that it will be useful,
8+but WITHOUT ANY WARRANTY; without even the implied warranty of
9+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
10+GNU Affero General Public License for more details.
11+
12+You should have received a copy of the GNU Affero General Public License
13+along with searx. If not, see < http://www.gnu.org/licenses/ >.
14+
15+(C) 2013- by Adam Tauber, <asciimoo@gmail.com>
16+'''
17+
118import grequests
219from itertools import izip_longest, chain
320from datetime import datetime
@@ -9,46 +26,67 @@ from searx.engines import (
926from searx.languages import language_codes
1027from searx.utils import gen_useragent
1128
29+
1230number_of_searches = 0
1331
1432
33+# get default reqest parameter
1534def default_request_params():
1635 return {
1736 'method': 'GET', 'headers': {}, 'data': {}, 'url': '', 'cookies': {}}
1837
1938
39+# create a callback wrapper for the search engine results
2040def make_callback(engine_name, results, suggestions, callback, params):
41+
2142 # creating a callback wrapper for the search engine results
2243 def process_callback(response, **kwargs):
2344 cb_res = []
2445 response.search_params = params
46+
47+ # update stats with current page-load-time
2548 engines[engine_name].stats['page_load_time'] += \
2649 (datetime.now() - params['started']).total_seconds()
50+
2751 try:
2852 search_results = callback(response)
2953 except Exception, e:
54+ # increase errors stats
3055 engines[engine_name].stats['errors'] += 1
3156 results[engine_name] = cb_res
57+
58+ # print engine name and specific error message
3259 print '[E] Error with engine "{0}":\n\t{1}'.format(
3360 engine_name, str(e))
3461 return
62+
3563 for result in search_results:
3664 result['engine'] = engine_name
65+
66+ # if it is a suggestion, add it to list of suggestions
3767 if 'suggestion' in result:
3868 # TODO type checks
3969 suggestions.add(result['suggestion'])
4070 continue
71+
72+ # append result
4173 cb_res.append(result)
74+
4275 results[engine_name] = cb_res
76+
4377 return process_callback
4478
4579
80+# score results and remove duplications
4681def score_results(results):
82+ # calculate scoring parameters
4783 flat_res = filter(
4884 None, chain.from_iterable(izip_longest(*results.values())))
4985 flat_len = len(flat_res)
5086 engines_len = len(results)
87+
5188 results = []
89+
5290 # deduplication + scoring
5391 for i, res in enumerate(flat_res):
5492
@@ -62,34 +100,54 @@ def score_results(results):
62100 res['engines'] = [res['engine']]
63101 weight = 1.0
64102
103+ # get weight of this engine if possible
65104 if hasattr(engines[res['engine']], 'weight'):
66105 weight = float(engines[res['engine']].weight)
67106
107+ # calculate score for that engine
68108 score = int((flat_len - i) / engines_len) * weight + 1
109+
69110 duplicated = False
70111
112+ # check for duplicates
71113 for new_res in results:
114+ # remove / from the end of the url if required
72115 p1 = res['parsed_url'].path[:-1] if res['parsed_url'].path.endswith('/') else res['parsed_url'].path # noqa
73116 p2 = new_res['parsed_url'].path[:-1] if new_res['parsed_url'].path.endswith('/') else new_res['parsed_url'].path # noqa
117+
118+ # check if that result is a duplicate
74119 if res['host'] == new_res['host'] and\
75120 unquote(p1) == unquote(p2) and\
76121 res['parsed_url'].query == new_res['parsed_url'].query and\
77122 res.get('template') == new_res.get('template'):
78123 duplicated = new_res
79124 break
125+
126+ # merge duplicates together
80127 if duplicated:
128+ # using content with more text
81129 if res.get('content') > duplicated.get('content'):
82130 duplicated['content'] = res['content']
131+
132+ # increase result-score
83133 duplicated['score'] += score
134+
135+ # add engine to list of result-engines
84136 duplicated['engines'].append(res['engine'])
137+
138+ # using https if possible
85139 if duplicated['parsed_url'].scheme == 'https':
86140 continue
87141 elif res['parsed_url'].scheme == 'https':
88142 duplicated['url'] = res['parsed_url'].geturl()
89143 duplicated['parsed_url'] = res['parsed_url']
144+
145+ # if there is no duplicate found, append result
90146 else:
91147 res['score'] = score
92148 results.append(res)
149+
150+ # return results sorted by score
93151 return sorted(results, key=itemgetter('score'), reverse=True)
94152
95153
@@ -98,6 +156,7 @@ class Search(object):
98156 """Search information container"""
99157
100158 def __init__(self, request):
159+ # init vars
101160 super(Search, self).__init__()
102161 self.query = None
103162 self.engines = []
@@ -105,18 +164,23 @@ class Search(object):
105164 self.paging = False
106165 self.pageno = 1
107166 self.lang = 'all'
167+
168+ # set blocked engines
108169 if request.cookies.get('blocked_engines'):
109170 self.blocked_engines = request.cookies['blocked_engines'].split(',') # noqa
110171 else:
111172 self.blocked_engines = []
173+
112174 self.results = []
113175 self.suggestions = []
114176 self.request_data = {}
115177
178+ # set specific language if set
116179 if request.cookies.get('language')\
117180 and request.cookies['language'] in (x[0] for x in language_codes):
118181 self.lang = request.cookies['language']
119182
183+ # set request method
120184 if request.method == 'POST':
121185 self.request_data = request.form
122186 else:
@@ -126,51 +190,72 @@ class Search(object):
126190 if not self.request_data.get('q'):
127191 raise Exception('noquery')
128192
193+ # set query
129194 self.query = self.request_data['q']
130195
196+ # set pagenumber
131197 pageno_param = self.request_data.get('pageno', '1')
132198 if not pageno_param.isdigit() or int(pageno_param) < 1:
133199 raise Exception('wrong pagenumber')
134200
135201 self.pageno = int(pageno_param)
136202
203+ # parse query, if tags are set, which change the serch engine or search-language
137204 self.parse_query()
138205
139206 self.categories = []
140207
208+ # if engines are calculated from query, set categories by using that informations
141209 if self.engines:
142210 self.categories = list(set(engine['category']
143211 for engine in self.engines))
212+
213+ # otherwise, using defined categories to calculate which engines should be used
144214 else:
215+ # set used categories
145216 for pd_name, pd in self.request_data.items():
146217 if pd_name.startswith('category_'):
147218 category = pd_name[9:]
219+ # if category is not found in list, skip
148220 if not category in categories:
149221 continue
222+
223+ # add category to list
150224 self.categories.append(category)
225+
226+ # if no category is specified for this search, using user-defined default-configuration which (is stored in cookie)
151227 if not self.categories:
152228 cookie_categories = request.cookies.get('categories', '')
153229 cookie_categories = cookie_categories.split(',')
154230 for ccateg in cookie_categories:
155231 if ccateg in categories:
156232 self.categories.append(ccateg)
233+
234+ # if still no category is specified, using general as default-category
157235 if not self.categories:
158236 self.categories = ['general']
159237
238+ # using all engines for that search, which are declared under the specific categories
160239 for categ in self.categories:
161240 self.engines.extend({'category': categ,
162241 'name': x.name}
163242 for x in categories[categ]
164243 if not x.name in self.blocked_engines)
165244
245+ # parse query, if tags are set, which change the serch engine or search-language
166246 def parse_query(self):
167247 query_parts = self.query.split()
168248 modified = False
249+
250+ # check if language-prefix is set
169251 if query_parts[0].startswith(':'):
170252 lang = query_parts[0][1:].lower()
171253
254+ # check if any language-code equal with declared language-codes
172255 for lc in language_codes:
173256 lang_id, lang_name, country = map(str.lower, lc)
257+
258+ # if correct language-code is found, set it as new search-language
174259 if lang == lang_id\
175260 or lang_id.startswith(lang)\
176261 or lang == lang_name\
@@ -179,56 +264,78 @@ class Search(object):
179264 modified = True
180265 break
181266
267+ # check if category/engine prefix is set
182268 elif query_parts[0].startswith('!'):
183269 prefix = query_parts[0][1:].replace('_', ' ')
184270
271+ # check if prefix equal with engine shortcut
185272 if prefix in engine_shortcuts\
186273 and not engine_shortcuts[prefix] in self.blocked_engines:
187274 modified = True
188275 self.engines.append({'category': 'none',
189276 'name': engine_shortcuts[prefix]})
277+
278+ # check if prefix equal with engine name
190279 elif prefix in engines\
191280 and not prefix in self.blocked_engines:
192281 modified = True
193282 self.engines.append({'category': 'none',
194283 'name': prefix})
284+
285+ # check if prefix equal with categorie name
195286 elif prefix in categories:
196287 modified = True
288+ # using all engines for that search, which are declared under that categorie name
197289 self.engines.extend({'category': prefix,
198290 'name': engine.name}
199291 for engine in categories[prefix]
200292 if not engine in self.blocked_engines)
293+
294+ # if language, category or engine were specificed in this query, search for more tags which does the same
201295 if modified:
202296 self.query = self.query.replace(query_parts[0], '', 1).strip()
203297 self.parse_query()
204298
299+ # do search-request
205300 def search(self, request):
206301 global number_of_searches
302+
303+ # init vars
207304 requests = []
208305 results = {}
209306 suggestions = set()
307+
308+ # increase number of active searches
210309 number_of_searches += 1
310+
311+ # set default useragent
211312 #user_agent = request.headers.get('User-Agent', '')
212313 user_agent = gen_useragent()
213314
315+ # start search-reqest for all selected engines
214316 for selected_engine in self.engines:
215317 if selected_engine['name'] not in engines:
216318 continue
217319
218320 engine = engines[selected_engine['name']]
219321
322+ # if paging is not supported, skip
220323 if self.pageno > 1 and not engine.paging:
221324 continue
222325
326+ # if search-language is set and engine does not provide language-support, skip
223327 if self.lang != 'all' and not engine.language_support:
224328 continue
225329
330+ # set default request parameters
226331 request_params = default_request_params()
227332 request_params['headers']['User-Agent'] = user_agent
228333 request_params['category'] = selected_engine['category']
229334 request_params['started'] = datetime.now()
230335 request_params['pageno'] = self.pageno
231336 request_params['language'] = self.lang
337+
338+ # update request parameters dependent on search-engine (contained in engines folder)
232339 request_params = engine.request(self.query.encode('utf-8'),
233340 request_params)
234341
@@ -236,6 +343,7 @@ class Search(object):
236343 # TODO add support of offline engines
237344 pass
238345
346+ # create a callback wrapper for the search engine results
239347 callback = make_callback(
240348 selected_engine['name'],
241349 results,
@@ -244,6 +352,7 @@ class Search(object):
244352 request_params
245353 )
246354
355+ # create dictionary which contain all informations about the request
247356 request_args = dict(
248357 headers=request_params['headers'],
249358 hooks=dict(response=callback),
@@ -251,6 +360,7 @@ class Search(object):
251360 timeout=engine.timeout
252361 )
253362
363+ # specific type of request (GET or POST)
254364 if request_params['method'] == 'GET':
255365 req = grequests.get
256366 else:
@@ -261,17 +371,25 @@ class Search(object):
261371 if not request_params['url']:
262372 continue
263373
374+ # append request to list
264375 requests.append(req(request_params['url'], **request_args))
376+
377+ # send all search-request
265378 grequests.map(requests)
379+
380+ # update engine-specific stats
266381 for engine_name, engine_results in results.items():
267382 engines[engine_name].stats['search_count'] += 1
268383 engines[engine_name].stats['result_count'] += len(engine_results)
269384
385+ # score results and remove duplications
270386 results = score_results(results)
271387
388+ # update engine stats, using calculated score
272389 for result in results:
273390 for res_engine in result['engines']:
274391 engines[result['engine']]\
275392 .stats['score_count'] += result['score']
276393
394+ # return results and suggestions
277395 return results, suggestions