refactor: standardize argument documentation format across multiple modules in webdriwer common

Author: iampopovich

py/selenium/webdriver/common/alert.py

@@ -47,8 +47,8 @@ class Alert:
     def __init__(self, driver) -> None:
         """Creates a new Alert.
 
-        :Args:
-         - driver: The WebDriver instance which performs user actions.
+        Args:
+            driver: The WebDriver instance which performs user actions.
         """
         self.driver = driver
 
@@ -64,17 +64,15 @@ def dismiss(self) -> None:
     def accept(self) -> None:
         """Accepts the alert available.
 
-        :Usage:
-            ::
-
-                Alert(driver).accept()  # Confirm a alert dialog.
+        Example:
+            Alert(driver).accept()  # Confirm a alert dialog.
         """
         self.driver.execute(Command.W3C_ACCEPT_ALERT)
 
     def send_keys(self, keysToSend: str) -> None:
         """Send Keys to the Alert.
 
-        :Args:
-         - keysToSend: The text to be sent to Alert.
+        Args:
+            keysToSend: The text to be sent to Alert.
         """
         self.driver.execute(Command.W3C_SET_ALERT_VALUE, {"value": keys_to_typing(keysToSend), "text": keysToSend})

py/selenium/webdriver/common/log.py

@@ -57,9 +57,7 @@ def __init__(self, driver, bidi_session) -> None:
     async def mutation_events(self) -> AsyncGenerator[dict[str, Any], None]:
         """Listen for mutation events and emit them as they are found.
 
-        :Usage:
-             ::
-
+        Example:
                async with driver.log.mutation_events() as event:
                     pages.load("dynamic.html")
                     driver.find_element(By.ID, "reveal").click()
@@ -101,9 +99,7 @@ async def add_js_error_listener(self) -> AsyncGenerator[dict[str, Any], None]:
         """Listen for JS errors and when the contextmanager exits check if
         there were JS Errors.
 
-        :Usage:
-             ::
-
+        Example:
                 async with driver.log.add_js_error_listener() as error:
                     driver.find_element(By.ID, "throwing-mouseover").click()
                 assert bool(error)
@@ -124,12 +120,10 @@ async def add_js_error_listener(self) -> AsyncGenerator[dict[str, Any], None]:
     async def add_listener(self, event_type) -> AsyncGenerator[dict[str, Any], None]:
         """Listen for certain events that are passed in.
 
-        :Args:
-         - event_type: The type of event that we want to look at.
-
-        :Usage:
-             ::
+        Args:
+            event_type: The type of event that we want to look at.
 
+        Example:
                 async with driver.log.add_listener(Console.log) as messages:
                     driver.execute_script("console.log('I like cheese')")
                 assert messages["message"] == "I love cheese"

py/selenium/webdriver/common/proxy.py

@@ -97,161 +97,41 @@ class Proxy:
 
     # create descriptor type objects
     auto_detect = _ProxyTypeDescriptor("autodetect", ProxyType.AUTODETECT)
-    """Gets and Sets `auto_detect`
-
-    Usage:
-    ------
-    - Get
-        - `self.auto_detect`
-    - Set
-        - `self.auto_detect` = `value`
-
-    Parameters:
-    -----------
-    `value`: `str`
-    """
+    """Proxy autodetection setting (boolean)."""
 
     # TODO: Remove ftpProxy in future version and remove deprecation warning
     ftp_proxy = _ProxyTypeDescriptor("ftpProxy", ProxyType.MANUAL)
-    """Gets and Sets `ftp_proxy`
-
-    Usage:
-    ------
-    - Get
-        - `self.ftp_proxy`
-    - Set
-        - `self.ftp_proxy` = `value`
-
-    Parameters:
-    -----------
-    `value`: `str`
-    """
+    """FTP proxy address (deprecated)."""
 
     http_proxy = _ProxyTypeDescriptor("httpProxy", ProxyType.MANUAL)
-    """Gets and Sets `http_proxy`
-
-    Usage:
-    ------
-    - Get
-        - `self.http_proxy`
-    - Set
-        - `self.http_proxy` = `value`
-
-    Parameters:
-    -----------
-    `value`: `str`
-    """
+    """HTTP proxy address."""
 
     no_proxy = _ProxyTypeDescriptor("noProxy", ProxyType.MANUAL)
-    """Gets and Sets `no_proxy`
-
-    Usage:
-    ------
-    - Get
-        - `self.no_proxy`
-    - Set
-        - `self.no_proxy` = `value`
-
-    Parameters:
-    -----------
-    `value`: `str`
-    """
+    """Addresses to bypass proxy."""
 
     proxy_autoconfig_url = _ProxyTypeDescriptor("proxyAutoconfigUrl", ProxyType.PAC)
-    """Gets and Sets `proxy_autoconfig_url`
-
-    Usage:
-    ------
-    - Get
-        - `self.proxy_autoconfig_url`
-    - Set
-        - `self.proxy_autoconfig_url` = `value`
-
-    Parameters:
-    -----------
-    `value`: `str`
-    """
+    """Proxy autoconfiguration URL."""
 
     ssl_proxy = _ProxyTypeDescriptor("sslProxy", ProxyType.MANUAL)
-    """Gets and Sets `ssl_proxy`
-
-    Usage:
-    ------
-    - Get
-        - `self.ssl_proxy`
-    - Set
-        - `self.ssl_proxy` = `value`
-
-    Parameters:
-    -----------
-    `value`: `str`
-    """
+    """SSL proxy address."""
 
     socks_proxy = _ProxyTypeDescriptor("socksProxy", ProxyType.MANUAL)
-    """Gets and Sets `socks_proxy`
-
-    Usage:
-    ------
-    - Get
-        - `self.sock_proxy`
-    - Set
-        - `self.socks_proxy` = `value`
-
-    Parameters:
-    -----------
-    `value`: `str`
-    """
+    """SOCKS proxy address."""
 
     socks_username = _ProxyTypeDescriptor("socksUsername", ProxyType.MANUAL)
-    """Gets and Sets `socks_password`
-
-    Usage:
-    ------
-    - Get
-        - `self.socks_password`
-    - Set
-        - `self.socks_password` = `value`
-
-    Parameters:
-    -----------
-    `value`: `str`
-    """
+    """SOCKS proxy username."""
 
     socks_password = _ProxyTypeDescriptor("socksPassword", ProxyType.MANUAL)
-    """Gets and Sets `socks_password`
-
-    Usage:
-    ------
-    - Get
-        - `self.socks_password`
-    - Set
-        - `self.socks_password` = `value`
-
-    Parameters:
-    -----------
-    `value`: `str`
-    """
+    """SOCKS proxy password."""
 
     socks_version = _ProxyTypeDescriptor("socksVersion", ProxyType.MANUAL)
-    """Gets and Sets `socks_version`
-
-    Usage:
-    ------
-    - Get
-        - `self.socks_version`
-    - Set
-        - `self.socks_version` = `value`
-
-    Parameters:
-    -----------
-    `value`: `str`
-    """
+    """SOCKS proxy version."""
 
     def __init__(self, raw=None):
         """Creates a new Proxy.
 
-        :Args:
-         - raw: raw proxy data. If None, default class values are used.
+        Args:
+            raw: Raw proxy data. If None, default class values are used.
         """
         if raw:
             if "proxyType" in raw and raw["proxyType"]:
@@ -293,8 +173,8 @@ def proxy_type(self):
     def proxy_type(self, value) -> None:
         """Sets proxy type.
 
-        :Args:
-         - value: The proxy type.
+        Args:
+            value: The proxy type.
         """
         self._verify_proxy_type_compatibility(value)
         self.proxyType = value
@@ -326,12 +206,11 @@ def to_capabilities(self):
                 proxy_caps[proxy] = attr_value
         return proxy_caps
 
-    def to_bidi_dict(self):
+    def to_bidi_dict(self) -> dict:
         """Convert proxy settings to BiDi format.
 
         Returns:
-        -------
-            dict: Proxy configuration in BiDi format.
+            Proxy configuration in BiDi format.
         """
         proxy_type = self.proxyType["string"].lower()
         result = {"proxyType": proxy_type}

py/selenium/webdriver/common/selenium_manager.py

@@ -38,9 +38,11 @@ class SeleniumManager:
     def binary_paths(self, args: list) -> dict:
         """Determines the locations of the requested assets.
 
-        :Args:
-         - args: the commands to send to the selenium manager binary.
-        :Returns: dictionary of assets and their path
+        Args:
+            args: the commands to send to the selenium manager binary.
+
+        Returns:
+            Dictionary of assets and their path.
         """
 
         args = [str(self._get_binary())] + args
@@ -57,9 +59,11 @@ def binary_paths(self, args: list) -> dict:
     def _get_binary() -> Path:
         """Determines the path of the correct Selenium Manager binary.
 
-        :Returns: The Selenium Manager executable location
+        Returns:
+            The Selenium Manager executable location.
 
-        :Raises: WebDriverException if the platform is unsupported
+        Raises:
+            WebDriverException: If the platform is unsupported.
         """
 
         compiled_path = Path(__file__).parent.joinpath("selenium-manager")
@@ -105,9 +109,11 @@ def _get_binary() -> Path:
     def _run(args: list[str]) -> dict:
         """Executes the Selenium Manager Binary.
 
-        :Args:
-         - args: the components of the command being executed.
-        :Returns: The log string containing the driver location.
+        Args:
+            args: the components of the command being executed.
+
+        Returns:
+            The log string containing the driver location.
         """
         command = " ".join(args)
         logger.debug("Executing process: %s", command)