[py] Fix D205 ruff warnings for docstrings and add type hints (#16537)

Co-authored-by: Corey Goldberg <[email protected]>

Author: iampopovich

py/generate.py

@@ -216,7 +216,7 @@ class CdpProperty:
     deprecated: bool
 
     @property
-    def py_name(self):
+    def py_name(self)->str:
         ''' Get this property's Python name. '''
         return snake_case(self.name)
 
@@ -590,7 +590,7 @@ class CdpCommand:
     domain: str
 
     @property
-    def py_name(self):
+    def py_name(self) -> str:
         ''' Get a Python name for this command. '''
         return snake_case(self.name)
 
@@ -794,7 +794,7 @@ class CdpDomain:
     events: List[CdpEvent]
 
     @property
-    def module(self):
+    def module(self) -> str:
         ''' The name of the Python module for this CDP domain. '''
         return snake_case(self.domain)
 

py/generate_api_module_listing.py

@@ -16,12 +16,13 @@
 # under the License.
 
 
-"""This script recursively scans the `selenium` package directory
-to find all modules, then generates the `py/docs/source/api.rst`
-file containing a listing of all modules in separate sections.
-The `api.rst` file is later used by `sphinx-autogen` to generate
-sphinx autodoc stub pages used in the Python API documentation.
-See `py/tox.ini` for how it is invoked.
+"""This script recursively scans the `selenium` package directory and generates an API listing.
+
+Recursively scans the `selenium` package directory to find all modules,
+then generates the `py/docs/source/api.rst` file containing a listing of all
+modules in separate sections. The `api.rst` file is later used by
+`sphinx-autogen` to generate sphinx autodoc stub pages used in the Python API
+documentation. See `py/tox.ini` for how it is invoked.
 """
 
 import os

py/pyproject.toml

@@ -154,7 +154,6 @@ extend-ignore = [
     "D104", # Missing docstring in public package
     "D105", # Missing docstring in magic method
     "D107", # Missing docstring in `__init__`
-    "D205", # 1 blank line required between summary line and description
     "D212", # Multi-line docstring summary should start at the first line
 ]
 

py/selenium/common/exceptions.py

@@ -91,9 +91,7 @@ class NoSuchAttributeException(WebDriverException):
 
 
 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):
@@ -121,11 +119,9 @@ def __init__(
 
 
 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.
     """
 
 
@@ -159,11 +155,9 @@ class NoAlertPresentException(WebDriverException):
 
 
 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.
     """
 
     def __init__(
@@ -175,9 +169,7 @@ def __init__(
 
 
 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 element interactions will hit another element due to paint order."""
 
     def __init__(
         self, msg: Optional[Any] = None, screen: Optional[str] = None, stacktrace: Optional[Sequence[str]] = None
@@ -195,9 +187,7 @@ class ElementNotSelectableException(InvalidElementStateException):
 
 
 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."""
 
 
 class UnableToSetCookieException(WebDriverException):
@@ -209,23 +199,17 @@ class TimeoutException(WebDriverException):
 
 
 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."""
 
 
 class InvalidSelectorException(WebDriverException):
-    """Thrown when the selector which is used to find an element does not
-    return a WebElement.
+    """Thrown when the selector 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)").
+    Currently this only happens when the XPath expression is syntactically invalid or does not select WebElements.
     """
 
     def __init__(
@@ -257,20 +241,15 @@ class JavascriptException(WebDriverException):
 
 
 class NoSuchCookieException(WebDriverException):
-    """No cookie matching the given path name was found amongst the associated
-    cookies of the current browsing context's active document.
-    """
+    """Thrown when no cookie matching the given path name was found."""
 
 
 class ScreenshotException(WebDriverException):
     """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.
-    """
+    """Thrown when element click fails because another element obscures it."""
 
     def __init__(
         self, msg: Optional[Any] = None, screen: Optional[str] = None, stacktrace: Optional[Sequence[str]] = None
@@ -281,19 +260,15 @@ def __init__(
 
 
 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.
-    """
+    """Thrown when the user agent hits a certificate warning (expired or invalid TLS certificate)."""
 
 
 class InvalidCoordinatesException(WebDriverException):
     """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.
-    """
+    """Thrown when the given session id is not in the list of active sessions."""
 
     def __init__(
         self, msg: Optional[Any] = None, screen: Optional[str] = None, stacktrace: Optional[Sequence[str]] = None
@@ -315,9 +290,7 @@ def __init__(
 
 
 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 NoSuchDriverException(WebDriverException):

py/selenium/webdriver/chrome/service.py

@@ -24,8 +24,7 @@
 
 
 class Service(service.ChromiumService):
-    """A Service class that is responsible for the starting and stopping of
-    `chromedriver`.
+    """Service class responsible for starting and stopping the chromedriver executable.
 
     Args:
         executable_path: Install path of the chromedriver executable, defaults
@@ -65,6 +64,7 @@ def command_line_args(self) -> list[str]:
 
     @property
     def service_args(self) -> Sequence[str]:
+        """Returns the sequence of service arguments."""
         return self._service_args
 
     @service_args.setter

py/selenium/webdriver/chromium/options.py

@@ -38,10 +38,7 @@ def __init__(self) -> None:
 
     @property
     def binary_location(self) -> str:
-        """
-        Returns:
-            The location of the binary, otherwise an empty string.
-        """
+        """Returns the location of the binary, otherwise an empty string."""
         return self._binary_location
 
     @binary_location.setter
@@ -57,16 +54,12 @@ def binary_location(self, value: str) -> None:
 
     @property
     def debugger_address(self) -> Optional[str]:
-        """
-        Returns:
-            The address of the remote devtools instance.
-        """
+        """Returns the address of the remote devtools instance."""
         return self._debugger_address
 
     @debugger_address.setter
     def debugger_address(self, value: str) -> None:
-        """Allows you to set the address of the remote devtools instance that
-        the ChromeDriver instance will try to connect to during an active wait.
+        """Set the address of the remote devtools instance for active wait connection.
 
         Args:
             value: Address of remote devtools instance if any (hostname[:port]).
@@ -77,10 +70,7 @@ def debugger_address(self, value: str) -> None:
 
     @property
     def extensions(self) -> list[str]:
-        """
-        Returns:
-            A list of encoded extensions that will be loaded.
-        """
+        """Returns a list of encoded extensions that will be loaded."""
 
         def _decode(file_data: BinaryIO) -> str:
             # Should not use base64.encodestring() which inserts newlines every
@@ -96,8 +86,7 @@ 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.
+        """Add the path to an extension to be extracted to ChromeDriver.
 
         Args:
             extension: Path to the *.crx file.
@@ -112,8 +101,7 @@ 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.
+        """Add Base64-encoded string with extension data to be extracted to ChromeDriver.
 
         Args:
             extension: Base64 encoded string with extension data.
@@ -125,10 +113,7 @@ def add_encoded_extension(self, extension: str) -> None:
 
     @property
     def experimental_options(self) -> dict:
-        """
-        Returns:
-            A dictionary of experimental options for chromium.
-        """
+        """Returns a dictionary of experimental options for chromium."""
         return self._experimental_options
 
     def add_experimental_option(self, name: str, value: Union[str, int, dict, list[str]]) -> None:
@@ -142,11 +127,7 @@ def add_experimental_option(self, name: str, value: Union[str, int, dict, list[s
 
     @property
     def enable_webextensions(self) -> bool:
-        """
-        Returns:
-            Whether webextension support is enabled for Chromium-based browsers.
-            True if webextension support is enabled, False otherwise.
-        """
+        """Return whether webextension support is enabled for Chromium-based browsers."""
         return self._enable_webextensions
 
     @enable_webextensions.setter

py/selenium/webdriver/chromium/service.py

@@ -24,8 +24,7 @@
 
 
 class ChromiumService(service.Service):
-    """A Service class that is responsible for the starting and stopping the
-    WebDriver instance of the ChromiumDriver.
+    """Service class responsible for starting and stopping the ChromiumDriver WebDriver instance.
 
     Args:
         executable_path: Install path of the executable.
@@ -76,6 +75,7 @@ def command_line_args(self) -> list[str]:
 
     @property
     def service_args(self) -> Sequence[str]:
+        """Returns the sequence of service arguments."""
         return self._service_args
 
     @service_args.setter

py/selenium/webdriver/chromium/webdriver.py

@@ -26,9 +26,7 @@
 
 
 class ChromiumDriver(RemoteWebDriver):
-    """Controls the WebDriver instance of ChromiumDriver and allows you to
-    drive the browser.
-    """
+    """Control the WebDriver instance of ChromiumDriver and drive the browser."""
 
     def __init__(
         self,
@@ -38,8 +36,7 @@ def __init__(
         service: Optional[ChromiumService] = None,
         keep_alive: bool = True,
     ) -> None:
-        """Creates a new WebDriver instance of the ChromiumDriver. Starts the
-        service and then creates new WebDriver instance of ChromiumDriver.
+        """Create a new WebDriver instance, start the service, and create new ChromiumDriver instance.
 
         Args:
             browser_name: Browser name used when matching capabilities.
@@ -148,17 +145,11 @@ def execute_cdp_cmd(self, cmd: str, cmd_args: dict):
         return super().execute_cdp_cmd(cmd, cmd_args)
 
     def get_sinks(self) -> list:
-        """
-        Returns:
-            A list of sinks available for Cast.
-        """
+        """Get a list of sinks available for Cast."""
         return self.execute("getSinks")["value"]
 
     def get_issue_message(self):
-        """
-        Returns:
-            An error message when there is any issue in a Cast session.
-        """
+        """Returns an error message when there is any issue in a Cast session."""
         return self.execute("getIssueMessage")["value"]
 
     @property
@@ -186,8 +177,7 @@ def get_log(self, log_type):
         return self.execute(Command.GET_LOG, {"type": log_type})["value"]
 
     def set_sink_to_use(self, sink_name: str) -> dict:
-        """Sets a specific sink, using its name, as a Cast session receiver
-        target.
+        """Set a specific sink as a Cast session receiver target.
 
         Args:
             sink_name: Name of the sink to use as the target.