[doc] Add doc-strings to searx.exceptions

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>

docs/src/searx.exceptions.rst

@@ -0,0 +1,8 @@
+.. _searx.exceptions:
+
+==================
+SearXNG Exceptions
+==================
+
+.. automodule:: searx.exceptions
+  :members:

searx/exceptions.py

@@ -1,29 +1,19 @@
-'''
+# -*- coding: utf-8 -*-
-searx is free software: you can redistribute it and/or modify
+# SPDX-License-Identifier: AGPL-3.0-or-later
-it under the terms of the GNU Affero General Public License as published by
+# lint: pylint
-the Free Software Foundation, either version 3 of the License, or
+"""Exception types raised by SearXNG modules.
-(at your option) any later version.
+"""
-
-searx is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-GNU Affero General Public License for more details.
-
-You should have received a copy of the GNU Affero General Public License
-along with searx. If not, see < http://www.gnu.org/licenses/ >.
-
-(C) 2017- by Alexandre Flament, <alex@al-f.net>
-'''
-
 
 from typing import Optional, Union
 
 
 class SearxException(Exception):
-    pass
+    """Base SearXNG exception."""
 
 
 class SearxParameterException(SearxException):
+    """Raised when query miss a required paramater"""
+
     def __init__(self, name, value):
         if value == '' or value is None:
             message = 'Empty ' + name + ' parameter'
@@ -70,14 +60,17 @@ class SearxEngineAccessDeniedException(SearxEngineResponseException):
     """The website is blocking the access"""
 
     SUSPEND_TIME_SETTING = "search.suspended_times.SearxEngineAccessDenied"
-    """This settings contains the default suspended time"""
+    """This settings contains the default suspended time (default 86400 sec / 1
+    day)."""
 
     def __init__(self, suspended_time: int = None, message: str = 'Access denied'):
-        """Generic exception to raise when an engine denies access to the results
+        """Generic exception to raise when an engine denies access to the results.
 
-        Args:
+        :param suspended_time: How long the engine is going to be suspended in
-            suspended_time (int, optional): How long the engine is going to be suspended in second. Defaults to None.
+            second. Defaults to None.
-            message (str, optional): Internal message. Defaults to 'Access denied'.
+        :type suspended_time: int, None
+        :param message: Internal message.  Defaults to ``Access denied``
+        :type message: str
         """
         suspended_time = suspended_time or self._get_default_suspended_time()
         super().__init__(message + ', suspended_time=' + str(suspended_time))
@@ -85,18 +78,17 @@ class SearxEngineAccessDeniedException(SearxEngineResponseException):
         self.message = message
 
     def _get_default_suspended_time(self):
-        from searx import get_setting
+        from searx import get_setting  # pylint: disable=C0415
 
         return get_setting(self.SUSPEND_TIME_SETTING)
 
 
 class SearxEngineCaptchaException(SearxEngineAccessDeniedException):
-    """The website has returned a CAPTCHA
+    """The website has returned a CAPTCHA."""
-
-    By default, searx stops sending requests to this engine for 1 day.
-    """
 
     SUSPEND_TIME_SETTING = "search.suspended_times.SearxEngineCaptcha"
+    """This settings contains the default suspended time (default 86400 sec / 1
+    day)."""
 
     def __init__(self, suspended_time=None, message='CAPTCHA'):
         super().__init__(message=message, suspended_time=suspended_time)
@@ -109,6 +101,8 @@ class SearxEngineTooManyRequestsException(SearxEngineAccessDeniedException):
     """
 
     SUSPEND_TIME_SETTING = "search.suspended_times.SearxEngineTooManyRequests"
+    """This settings contains the default suspended time (default 3660 sec / 1
+    hour)."""
 
     def __init__(self, suspended_time=None, message='Too many request'):
         super().__init__(message=message, suspended_time=suspended_time)