[py]: PEP257 compliant consistent docstrings throughout. Include in linting recipe

Author: symonk

py/selenium/common/exceptions.py

@@ -15,18 +15,14 @@
 # specific language governing permissions and limitations
 # under the License.
 
-"""
-Exceptions that may happen in all the webdriver code.
-"""
+"""Exceptions that may happen in all the webdriver code."""
 
 from typing import Optional
 from typing import Sequence
 
 
 class WebDriverException(Exception):
-    """
-    Base webdriver exception.
-    """
+    """Base webdriver exception."""
 
     def __init__(
         self, msg: Optional[str] = None, screen: Optional[str] = None, stacktrace: Optional[Sequence[str]] = None
@@ -47,32 +43,25 @@ def __str__(self) -> str:
 
 
 class InvalidSwitchToTargetException(WebDriverException):
-    """
-    Thrown when frame or window target to be switched doesn't exist.
-    """
+    """Thrown when frame or window target to be switched doesn't exist."""
 
 
 class NoSuchFrameException(InvalidSwitchToTargetException):
-    """
-    Thrown when frame target to be switched doesn't exist.
-    """
+    """Thrown when frame target to be switched doesn't exist."""
 
 
 class NoSuchWindowException(InvalidSwitchToTargetException):
-    """
-    Thrown when window target to be switched doesn't exist.
+    """Thrown when window target to be switched doesn't exist.
 
     To find the current set of active window handles, you can get a list
     of the active window handles in the following way::
 
         print driver.window_handles
-
     """
 
 
 class NoSuchElementException(WebDriverException):
-    """
-    Thrown when element could not be found.
+    """Thrown when element could not be found.
 
     If you encounter this exception, you may want to check the following:
         * Check your selector used in your find_by...
@@ -83,25 +72,22 @@ class NoSuchElementException(WebDriverException):
 
 
 class NoSuchAttributeException(WebDriverException):
-    """
-    Thrown when the attribute of element could not be found.
+    """Thrown when the attribute of element could not be found.
 
-    You may want to check if the attribute exists in the particular browser you are
-    testing against.  Some browsers may have different property names for the same
-    property.  (IE8's .innerText vs. Firefox .textContent)
+    You may want to check if the attribute exists in the particular
+    browser you are testing against.  Some browsers may have different
+    property names for the same property.  (IE8's .innerText vs. Firefox
+    .textContent)
     """
 
 
 class NoSuchShadowRootException(WebDriverException):
-    """
-    Thrown when trying to access the shadow root of an element when it does not
-    have a shadow root attached.
-    """
+    """Thrown when trying to access the shadow root of an element when it does
+    not have a shadow root attached."""
 
 
 class StaleElementReferenceException(WebDriverException):
-    """
-    Thrown when a reference to an element is now "stale".
+    """Thrown when a reference to an element is now "stale".
 
     Stale means the element no longer appears on the DOM of the page.
 
@@ -118,19 +104,19 @@ class StaleElementReferenceException(WebDriverException):
 
 
 class InvalidElementStateException(WebDriverException):
-    """
-    Thrown when a command could not be completed because the element is in an invalid state.
+    """Thrown when a command could not be completed because the element is in
+    an invalid state.
 
-    This can be caused by attempting to clear an element that isn't both editable and resettable.
+    This can be caused by attempting to clear an element that isn't both
+    editable and resettable.
     """
 
 
 class UnexpectedAlertPresentException(WebDriverException):
-    """
-    Thrown when an unexpected alert has appeared.
+    """Thrown when an unexpected alert has appeared.
 
-    Usually raised when  an unexpected modal is blocking the webdriver from executing
-    commands.
+    Usually raised when  an unexpected modal is blocking the webdriver
+    from executing commands.
     """
 
     def __init__(
@@ -148,156 +134,123 @@ def __str__(self) -> str:
 
 
 class NoAlertPresentException(WebDriverException):
-    """
-    Thrown when switching to no presented alert.
+    """Thrown when switching to no presented alert.
 
-    This can be caused by calling an operation on the Alert() class when an alert is
-    not yet on the screen.
+    This can be caused by calling an operation on the Alert() class when
+    an alert is not yet on the screen.
     """
 
 
 class ElementNotVisibleException(InvalidElementStateException):
-    """
-    Thrown when an element is present on the DOM, but
-    it is not visible, and so is not able to be interacted with.
+    """Thrown when an element is present on the DOM, but it is not visible, and
+    so is not able to be interacted with.
 
-    Most commonly encountered when trying to click or read text
-    of an element that is hidden from view.
+    Most commonly encountered when trying to click or read text of an
+    element that is hidden from view.
     """
 
 
 class ElementNotInteractableException(InvalidElementStateException):
-    """
-    Thrown when an element is present in the DOM but interactions
-    with that element will hit another element due to paint order
-    """
+    """Thrown when an element is present in the DOM but interactions with that
+    element will hit another element due to paint order."""
 
 
 class ElementNotSelectableException(InvalidElementStateException):
-    """
-    Thrown when trying to select an unselectable element.
+    """Thrown when trying to select an unselectable element.
 
     For example, selecting a 'script' element.
     """
 
 
 class InvalidCookieDomainException(WebDriverException):
-    """
-    Thrown when attempting to add a cookie under a different domain
-    than the current URL.
-    """
+    """Thrown when attempting to add a cookie under a different domain than the
+    current URL."""
 
 
 class UnableToSetCookieException(WebDriverException):
-    """
-    Thrown when a driver fails to set a cookie.
-    """
+    """Thrown when a driver fails to set a cookie."""
 
 
 class TimeoutException(WebDriverException):
-    """
-    Thrown when a command does not complete in enough time.
-    """
+    """Thrown when a command does not complete in enough time."""
 
 
 class MoveTargetOutOfBoundsException(WebDriverException):
-    """
-    Thrown when the target provided to the `ActionsChains` move()
-    method is invalid, i.e. out of document.
-    """
+    """Thrown when the target provided to the `ActionsChains` move() method is
+    invalid, i.e. out of document."""
 
 
 class UnexpectedTagNameException(WebDriverException):
-    """
-    Thrown when a support class did not get an expected web element.
-    """
+    """Thrown when a support class did not get an expected web element."""
 
 
 class InvalidSelectorException(WebDriverException):
-    """
-    Thrown when the selector which is used to find an element does not return
-    a WebElement. Currently this only happens when the selector is an xpath
-    expression and it is either syntactically invalid (i.e. it is not a
-    xpath expression) or the expression does not select WebElements
-    (e.g. "count(//input)").
+    """Thrown when the selector which is used to find an element does not
+    return a WebElement.
+
+    Currently this only happens when the selector is an xpath expression
+    and it is either syntactically invalid (i.e. it is not a xpath
+    expression) or the expression does not select WebElements (e.g.
+    "count(//input)").
     """
 
 
 class ImeNotAvailableException(WebDriverException):
-    """
-    Thrown when IME support is not available. This exception is thrown for every IME-related
-    method call if IME support is not available on the machine.
+    """Thrown when IME support is not available.
+
+    This exception is thrown for every IME-related method call if IME
+    support is not available on the machine.
     """
 
 
 class ImeActivationFailedException(WebDriverException):
-    """
-    Thrown when activating an IME engine has failed.
-    """
+    """Thrown when activating an IME engine has failed."""
 
 
 class InvalidArgumentException(WebDriverException):
-    """
-    The arguments passed to a command are either invalid or malformed.
-    """
+    """The arguments passed to a command are either invalid or malformed."""
 
 
 class JavascriptException(WebDriverException):
-    """
-    An error occurred while executing JavaScript supplied by the user.
-    """
+    """An error occurred while executing JavaScript supplied by the user."""
 
 
 class NoSuchCookieException(WebDriverException):
-    """
-    No cookie matching the given path name was found amongst the associated cookies of the
-    current browsing context's active document.
-    """
+    """No cookie matching the given path name was found amongst the associated
+    cookies of the current browsing context's active document."""
 
 
 class ScreenshotException(WebDriverException):
-    """
-    A screen capture was made impossible.
-    """
+    """A screen capture was made impossible."""
 
 
 class ElementClickInterceptedException(WebDriverException):
-    """
-    The Element Click command could not be completed because the element receiving the events
-    is obscuring the element that was requested to be clicked.
-    """
+    """The Element Click command could not be completed because the element
+    receiving the events is obscuring the element that was requested to be
+    clicked."""
 
 
 class InsecureCertificateException(WebDriverException):
-    """
-    Navigation caused the user agent to hit a certificate warning, which is usually the result
-    of an expired or invalid TLS certificate.
-    """
+    """Navigation caused the user agent to hit a certificate warning, which is
+    usually the result of an expired or invalid TLS certificate."""
 
 
 class InvalidCoordinatesException(WebDriverException):
-    """
-    The coordinates provided to an interaction's operation are invalid.
-    """
+    """The coordinates provided to an interaction's operation are invalid."""
 
 
 class InvalidSessionIdException(WebDriverException):
-    """
-    Occurs if the given session id is not in the list of active sessions, meaning the session
-    either does not exist or that it's not active.
-    """
+    """Occurs if the given session id is not in the list of active sessions,
+    meaning the session either does not exist or that it's not active."""
 
 
 class SessionNotCreatedException(WebDriverException):
-    """
-    A new session could not be created.
-    """
+    """A new session could not be created."""
 
 
 class UnknownMethodException(WebDriverException):
-    """
-    The requested command matched a known URL but did not match any methods for that URL.
-    """
+    """The requested command matched a known URL but did not match any methods
+    for that URL."""
 
 
 class SeleniumManagerException(WebDriverException):

py/selenium/webdriver/chrome/service.py

@@ -22,8 +22,8 @@
 
 
 class Service(service.ChromiumService):
-    """A Service class that is responsible for the starting and stopping
-    of `chromedriver`.
+    """A Service class that is responsible for the starting and stopping of
+    `chromedriver`.
 
     :param executable_path: install path of the chromedriver executable, defaults to `chromedriver`.
     :param port: Port for the service to run on, defaults to 0 where the operating system will decide.

py/selenium/webdriver/chrome/webdriver.py

@@ -29,8 +29,8 @@
 
 
 class WebDriver(ChromiumDriver):
-    """
-    Controls the ChromeDriver and allows you to drive the browser.
+    """Controls the ChromeDriver and allows you to drive the browser.
+
     You will need to download the ChromeDriver executable from
     http://chromedriver.storage.googleapis.com/index.html
     """
@@ -47,9 +47,8 @@ def __init__(
         service: Service = None,
         keep_alive=DEFAULT_KEEP_ALIVE,
     ) -> None:
-        """
-        Creates a new instance of the chrome driver.
-        Starts the service and then creates new instance of chrome driver.
+        """Creates a new instance of the chrome driver. Starts the service and
+        then creates new instance of chrome driver.
 
         :Args:
          - executable_path - Deprecated: path to the executable. If the default is used it assumes the executable is in the $PATH

py/selenium/webdriver/chromium/options.py

@@ -91,9 +91,8 @@ def _decode(file_data: BinaryIO) -> str:
         return encoded_extensions + self._extensions
 
     def add_extension(self, extension: str) -> None:
-        """
-        Adds the path to the extension to a list that will be used to extract it
-        to the ChromeDriver
+        """Adds the path to the extension to a list that will be used to
+        extract it to the ChromeDriver.
 
         :Args:
          - extension: path to the \\*.crx file
@@ -108,9 +107,8 @@ def add_extension(self, extension: str) -> None:
             raise ValueError("argument can not be null")
 
     def add_encoded_extension(self, extension: str) -> None:
-        """
-        Adds Base64 encoded string with extension data to a list that will be used to extract it
-        to the ChromeDriver
+        """Adds Base64 encoded string with extension data to a list that will
+        be used to extract it to the ChromeDriver.
 
         :Args:
          - extension: Base64 encoded string with extension data
@@ -128,8 +126,7 @@ def experimental_options(self) -> dict:
         return self._experimental_options
 
     def add_experimental_option(self, name: str, value: Union[str, int, dict, List[str]]) -> None:
-        """
-        Adds an experimental option which is passed to chromium.
+        """Adds an experimental option which is passed to chromium.
 
         :Args:
           name: The experimental option name.

py/selenium/webdriver/chromium/service.py

@@ -20,8 +20,8 @@
 
 
 class ChromiumService(service.Service):
-    """A Service class that is responsible for the starting and stopping
-    the WebDriver instance of the ChromiumDriver.
+    """A Service class that is responsible for the starting and stopping the
+    WebDriver instance of the ChromiumDriver.
 
     :param executable_path: install path of the executable.
     :param port: Port for the service to run on, defaults to 0 where the operating system will decide.