Merge branch 'trunk' into timezone

Author: Delta456

py/pyproject.toml

@@ -146,7 +146,6 @@ target-version = "py39"
 [tool.ruff.lint]
 extend-select = ["D", "E4", "E7", "E9", "F", "I", "E501", "RUF022", "TID252"]
 fixable = ["ALL"]
-# remove these as we cleanup docstrings
 extend-ignore = [
     "D100", # Missing docstring in public module
     "D101", # Missing docstring in public class
@@ -157,8 +156,6 @@ extend-ignore = [
     "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
-    "D415", # First line should end with a period, question mark, or exclamation point
-    "D417", # Missing argument descriptions in the docstring for `__init__`
 ]
 
 [tool.ruff.format]

py/selenium/webdriver/chromium/webdriver.py

@@ -105,7 +105,7 @@ def set_network_conditions(self, **network_conditions) -> None:
                 upload_throughput=500 * 1024,
             )  # maximal throughput
 
-            Note: 'throughput' can be used to set both (for download and upload).
+            Note: `throughput` can be used to set both (for download and upload).
         """
         self.execute("setNetworkConditions", {"network_conditions": network_conditions})
 
@@ -126,17 +126,19 @@ def set_permissions(self, name: str, value: str) -> None:
         self.execute("setPermissions", {"descriptor": {"name": name}, "state": value})
 
     def execute_cdp_cmd(self, cmd: str, cmd_args: dict):
-        """Execute Chrome Devtools Protocol command and get returned result The
-        command and command args should follow chrome devtools protocol
-        domains/commands, refer to link
-        https://chromedevtools.github.io/devtools-protocol/
+        """Execute Chrome Devtools Protocol command and get returned result.
+
+        The command and command args should follow chrome devtools protocol domains/commands
+
+        See:
+          - https://chromedevtools.github.io/devtools-protocol/
 
         Args:
             cmd: A str, command name
             cmd_args: A dict, command args. empty dict {} if there is no command args
 
         Example:
-            driver.execute_cdp_cmd('Network.getResponseBody', {'requestId': requestId})
+            `driver.execute_cdp_cmd('Network.getResponseBody', {'requestId': requestId})`
 
         Returns:
             A dict, empty dict {} if there is no result to return.

py/selenium/webdriver/common/action_chains.py

@@ -72,6 +72,8 @@ def __init__(self, driver: WebDriver, duration: int = 250, devices: list[AnyDevi
         Args:
             driver: The WebDriver instance which performs user actions.
             duration: override the default 250 msecs of DEFAULT_MOVE_DURATION in PointerInput
+            devices: Optional list of input devices (PointerInput, KeyInput, WheelInput) to use.
+                If not provided, default devices will be created.
         """
         self._driver = driver
         mouse = None

py/selenium/webdriver/common/actions/pointer_actions.py

@@ -25,10 +25,13 @@
 
 class PointerActions(Interaction):
     def __init__(self, source: Optional[PointerInput] = None, duration: int = 250):
-        """
+        """Initialize a new PointerActions instance.
+
         Args:
-        - source: PointerInput instance
-        - duration: override the default 250 msecs of DEFAULT_MOVE_DURATION in source
+            source: Optional PointerInput instance. If not provided, a default
+                mouse PointerInput will be created.
+            duration: Override the default 250 msecs of DEFAULT_MOVE_DURATION
+                in the source.
         """
         if source is None:
             source = PointerInput(interaction.POINTER_MOUSE, "mouse")

py/selenium/webdriver/common/options.py

@@ -65,8 +65,10 @@ def __set__(self, obj, value):
 
 
 class _PageLoadStrategyDescriptor:
-    """Determines the point at which a navigation command is returned:
-    https://w3c.github.io/webdriver/#dfn-table-of-page-load-strategies.
+    """Determines the point at which a navigation command is returned.
+
+    See:
+      - https://w3c.github.io/webdriver/#dfn-table-of-page-load-strategies.
 
     Args:
         strategy: the strategy corresponding to a document readiness state
@@ -86,9 +88,10 @@ def __set__(self, obj, value):
 
 
 class _UnHandledPromptBehaviorDescriptor:
-    """How the driver should respond when an alert is present and the:
-    command sent is not handling the alert:
-    https://w3c.github.io/webdriver/#dfn-table-of-page-load-strategies:
+    """How the driver should respond when an alert is present and the command sent is not handling the alert.
+
+    See:
+      - https://w3c.github.io/webdriver/#dfn-table-of-page-load-strategies:
 
     Args:
         behavior: behavior to use when an alert is encountered
@@ -114,8 +117,10 @@ def __set__(self, obj, value):
 
 
 class _TimeoutsDescriptor:
-    """How long the driver should wait for actions to complete before:
-    returning an error https://w3c.github.io/webdriver/#timeouts:
+    """How long the driver should wait for actions to complete before returning an error.
+
+    See:
+      - https://w3c.github.io/webdriver/#timeouts
 
     Args:
         timeouts: values in milliseconds for implicit wait, page load and script timeout

py/selenium/webdriver/ie/service.py

@@ -48,6 +48,7 @@ def __init__(
             log_output: (Optional) int representation of STDOUT/DEVNULL, any IO instance or String path to file.
                 Default is "stdout".
             driver_path_env_key: (Optional) Environment variable to use to get the path to the driver executable.
+            **kwargs: Additional keyword arguments to pass to the parent Service class.
         """
         self._service_args = list(service_args or [])
         driver_path_env_key = driver_path_env_key or "SE_IEDRIVER"

py/selenium/webdriver/remote/shadowroot.py

@@ -59,6 +59,7 @@ def find_element(self, by: str = By.ID, value: str = None):
                 - By.LINK_TEXT: Locate a link element by its exact text.
                 - By.PARTIAL_LINK_TEXT: Locate a link element by partial text match.
                 - RelativeBy: Locate elements relative to a specified root element.
+            value: The locator value to use with the specified `by` strategy.
 
         Returns:
             The first matching `WebElement` found on the page.
@@ -94,6 +95,7 @@ def find_elements(self, by: str = By.ID, value: str = None) -> list:
                 - By.LINK_TEXT: Locate a link element by its exact text.
                 - By.PARTIAL_LINK_TEXT: Locate a link element by partial text match.
                 - RelativeBy: Locate elements relative to a specified root element.
+            value: The locator value to use with the specified `by` strategy.
 
         Returns:
             List of `WebElements` matching locator strategy found on the page.