[py] Fix type annotations, make docstrings consistent, centralize dev dependencies (#16821)

Author: cgoldberg

.github/workflows/ci-python.yml

@@ -54,7 +54,7 @@ jobs:
         run: |
           tox -c py/tox.ini || true
         env:
-          TOXENV: mypy
+          TOXENV: typecheck
 
   unit-tests:
     name: Unit Tests

py/pyproject.toml

@@ -42,6 +42,22 @@ changelog = "https://github.com/SeleniumHQ/selenium/blob/trunk/py/CHANGES"
 documentation = "https://www.selenium.dev/documentation/webdriver"
 issues = "https://github.com/SeleniumHQ/selenium/issues"
 
+[dependency-groups]
+lint = [
+    "ruff==0.14.10",
+]
+typecheck = [
+    "mypy==1.19.1",
+    "types-urllib3==1.26.25.14",
+    "types-certifi==2021.10.8.3",
+    "trio-typing==0.10.0",
+    "trio-websocket>=0.12.2,<1.0",
+]
+validate = [
+    "validate-pyproject==0.24.1",
+    "packaging==25.0",
+]
+
 [tool.setuptools]
 zip-safe = false
 
@@ -126,11 +142,6 @@ warn_return_any = false
 # Shows a warning when encountering any code inferred to be unreachable after performing type analysis.
 warn_unreachable = false
 
-# mypy module specific options
-[[tool.mypy.trio_websocket]]
-# suppress error messages about imports that cannot be resolved.
-ignore_missing_imports = true
-
 [tool.ruff]
 extend-exclude = [
     "selenium/webdriver/common/devtools/",

py/requirements.txt

@@ -1,12 +1,16 @@
 attrs==25.4.0
 backports.tarfile==1.2.0
+cachetools==6.2.4
+chardet==5.2.0
 certifi==2025.11.12
 cffi==2.0.0
 charset-normalizer==3.4.4
 colorama==0.4.6
 cryptography==46.0.3
+distlib==0.4.0
 docutils==0.21.2
 exceptiongroup==1.3.1
+filelock==3.20.1
 filetype==1.2.0
 h11==0.16.0
 id==1.5.0
@@ -25,8 +29,10 @@ more-itertools==10.8.0
 nh3==0.3.2
 outcome==1.3.0.post0
 packaging==25.0
+platformdirs==4.5.1
 pluggy==1.6.0
 pycparser==2.23
+pyproject-api==1.10.0
 Pygments==2.19.2
 PySocks==1.7.1
 pytest==9.0.2
@@ -43,11 +49,13 @@ SecretStorage==3.5.0
 sniffio==1.3.1
 sortedcontainers==2.4.0
 tomli==2.3.0
+tox==4.32.0
 trio==0.32.0
 trio-websocket==0.12.2
 twine==6.2.0
 typing_extensions==4.15.0
 urllib3[socks]==2.6.2
+virtualenv==20.35.4
 websocket-client==1.9.0
 wsproto==1.3.2
 zipp==3.23.0

py/requirements_lock.txt

@@ -17,6 +17,12 @@ backports-tarfile==1.2.0 \
     # via
     #   -r py/requirements.txt
     #   jaraco-context
+cachetools==6.2.4 \
+    --hash=sha256:69a7a52634fed8b8bf6e24a050fb60bff1c9bd8f6d24572b99c32d4e71e62a51 \
+    --hash=sha256:82c5c05585e70b6ba2d3ae09ea60b79548872185d2f24ae1f2709d37299fd607
+    # via
+    #   -r py/requirements.txt
+    #   tox
 certifi==2025.11.12 \
     --hash=sha256:97de8790030bbd5c2d96b7ec782fc2f7820ef8dba6db909ccf95449f2d062d4b \
     --hash=sha256:d8ab5478f2ecd78af242878415affce761ca6bc54a22a27e026d7c25357c3316
@@ -111,6 +117,12 @@ cffi==2.0.0 \
     # via
     #   -r py/requirements.txt
     #   cryptography
+chardet==5.2.0 \
+    --hash=sha256:1b3b6ff479a8c414bc3fa2c0852995695c4a026dcd6d0633b2dd092ca39c1cf7 \
+    --hash=sha256:e1cf59446890a00105fe7b7912492ea04b6e6f06d4b742b2c788469e34c82970
+    # via
+    #   -r py/requirements.txt
+    #   tox
 charset-normalizer==3.4.4 \
     --hash=sha256:027f6de494925c0ab2a55eab46ae5129951638a49a34d87f4c3eda90f696b4ad \
     --hash=sha256:077fbb858e903c73f6c9db43374fd213b0b6a778106bc7032446a8e8b5b38b93 \
@@ -231,7 +243,9 @@ charset-normalizer==3.4.4 \
 colorama==0.4.6 \
     --hash=sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44 \
     --hash=sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6
-    # via -r py/requirements.txt
+    # via
+    #   -r py/requirements.txt
+    #   tox
 cryptography==46.0.3 \
     --hash=sha256:00a5e7e87938e5ff9ff5447ab086a5706a957137e6e433841e9d24f38a065217 \
     --hash=sha256:01ca9ff2885f3acc98c29f1860552e37f6d7c7d013d7334ff2a9de43a449315d \
@@ -290,6 +304,12 @@ cryptography==46.0.3 \
     # via
     #   -r py/requirements.txt
     #   secretstorage
+distlib==0.4.0 \
+    --hash=sha256:9659f7d87e46584a30b5780e43ac7a2143098441670ff0a49d5f9034c54a6c16 \
+    --hash=sha256:feec40075be03a04501a973d81f633735b4b69f98b05450592310c0f401a4e0d
+    # via
+    #   -r py/requirements.txt
+    #   virtualenv
 docutils==0.21.2 \
     --hash=sha256:3a6b18732edf182daa3cd12775bbb338cf5691468f91eeeb109deff6ebfa986f \
     --hash=sha256:dafca5b9e384f0e419294eb4d2ff9fa826435bf15f15b7bd45723e8ad76811b2
@@ -304,6 +324,13 @@ exceptiongroup==1.3.1 \
     #   pytest
     #   trio
     #   trio-websocket
+filelock==3.20.1 \
+    --hash=sha256:15d9e9a67306188a44baa72f569d2bfd803076269365fdea0934385da4dc361a \
+    --hash=sha256:b8360948b351b80f420878d8516519a2204b07aefcdcfd24912a5d33127f188c
+    # via
+    #   -r py/requirements.txt
+    #   tox
+    #   virtualenv
 filetype==1.2.0 \
     --hash=sha256:66b56cd6474bf41d8c54660347d37afcc3f7d1970648de365c102ef77548aadb \
     --hash=sha256:7ce71b6880181241cf7ac8697a2f1eb6a8bd9b429f7ad6d27b8db9ba5f1c2d25
@@ -436,14 +463,24 @@ packaging==25.0 \
     --hash=sha256:d443872c98d677bf60f6a1f2f8c1cb748e8fe762d2bf9d3148b5599295b0fc4f
     # via
     #   -r py/requirements.txt
+    #   pyproject-api
     #   pytest
+    #   tox
     #   twine
+platformdirs==4.5.1 \
+    --hash=sha256:61d5cdcc6065745cdd94f0f878977f8de9437be93de97c1c12f853c9c0cdcbda \
+    --hash=sha256:d03afa3963c806a9bed9d5125c8f4cb2fdaf74a55ab60e5d59b3fde758104d31
+    # via
+    #   -r py/requirements.txt
+    #   tox
+    #   virtualenv
 pluggy==1.6.0 \
     --hash=sha256:7dcc130b76258d33b90f61b658791dede3486c3e6bfb003ee5c9bfb396dd22f3 \
     --hash=sha256:e920276dd6813095e9377c0bc5566d94c932c33b27a3e3945d8389c374dd4746
     # via
     #   -r py/requirements.txt
     #   pytest
+    #   tox
 pycparser==2.23 \
     --hash=sha256:78816d4f24add8f10a06d6f05b4d424ad9e96cfebf68a4ddc99c65c0720d00c2 \
     --hash=sha256:e5c6e8d3fbad53479cab09ac03729e0a9faf2bee3db8208a550daf5af81a5934
@@ -458,6 +495,12 @@ pygments==2.19.2 \
     #   pytest
     #   readme-renderer
     #   rich
+pyproject-api==1.10.0 \
+    --hash=sha256:40c6f2d82eebdc4afee61c773ed208c04c19db4c4a60d97f8d7be3ebc0bbb330 \
+    --hash=sha256:8757c41a79c0f4ab71b99abed52b97ecf66bd20b04fa59da43b5840bac105a09
+    # via
+    #   -r py/requirements.txt
+    #   tox
 pysocks==1.7.1 \
     --hash=sha256:08e69f092cc6dbe92a0fdd16eeb9b9ffbc13cadfe5ca4c7bd92ffb078b293299 \
     --hash=sha256:2725bd0a9925919b9b51739eea5f9e2bae91e83288108a9ad338b2e3a4435ee5 \
@@ -584,7 +627,13 @@ tomli==2.3.0 \
     --hash=sha256:ff72b71b5d10d22ecb084d345fc26f42b5143c5533db5e2eaba7d2d335358876
     # via
     #   -r py/requirements.txt
+    #   pyproject-api
     #   pytest
+    #   tox
+tox==4.32.0 \
+    --hash=sha256:1ad476b5f4d3679455b89a992849ffc3367560bbc7e9495ee8a3963542e7c8ff \
+    --hash=sha256:451e81dc02ba8d1ed20efd52ee409641ae4b5d5830e008af10fe8823ef1bd551
+    # via -r py/requirements.txt
 trio==0.32.0 \
     --hash=sha256:150f29ec923bcd51231e1d4c71c7006e65247d68759dd1c19af4ea815a25806b \
     --hash=sha256:4ab65984ef8370b79a76659ec87aa3a30c5c7c83ff250b4de88c29a8ab6123c5
@@ -607,13 +656,21 @@ typing-extensions==4.15.0 \
     #   -r py/requirements.txt
     #   cryptography
     #   exceptiongroup
+    #   tox
+    #   virtualenv
 urllib3[socks]==2.6.2 \
     --hash=sha256:016f9c98bb7e98085cb2b4b17b87d2c702975664e4f060c6532e64d1c1a5e797 \
     --hash=sha256:ec21cddfe7724fc7cb4ba4bea7aa8e2ef36f607a4bab81aa6ce42a13dc3f03dd
     # via
     #   -r py/requirements.txt
     #   requests
     #   twine
+virtualenv==20.35.4 \
+    --hash=sha256:643d3914d73d3eeb0c552cbb12d7e82adf0e504dbf86a3182f8771a153a1971c \
+    --hash=sha256:c21c9cede36c9753eeade68ba7d523529f228a403463376cf821eaae2b650f1b
+    # via
+    #   -r py/requirements.txt
+    #   tox
 websocket-client==1.9.0 \
     --hash=sha256:9e813624b6eb619999a97dc7958469217c3176312b3a16a4bd1bc7e08a46ec98 \
     --hash=sha256:af248a825037ef591efbf6ed20cc5faa03d3b47b9e5a2230a529eeee1c1fc3ef

py/selenium/webdriver/chrome/service.py

@@ -46,7 +46,7 @@ def __init__(
         env: Mapping[str, str] | None = None,
         **kwargs,
     ) -> None:
-        self._service_args = service_args or []
+        self._service_args = list(service_args or [])
 
         super().__init__(
             executable_path=executable_path,

py/selenium/webdriver/chromium/service.py

@@ -16,7 +16,6 @@
 # under the License.
 
 from collections.abc import Mapping, Sequence
-from io import IOBase
 from typing import IO, Any
 
 from selenium.webdriver.common import service
@@ -26,17 +25,12 @@ class ChromiumService(service.Service):
     """Service class responsible for starting and stopping the ChromiumDriver WebDriver instance.
 
     Args:
-        executable_path: Install path of the executable.
-        port: Port for the service to run on, defaults to 0 where the operating
-            system will decide.
-        service_args: (Optional) Sequence of args to be passed to the subprocess
-            when launching the executable.
-        log_output: (Optional) int representation of STDOUT/DEVNULL, any IO
-            instance or String path to file.
-        env: (Optional) Mapping of environment variables for the new process,
-            defaults to `os.environ`.
-        driver_path_env_key: (Optional) Environment variable to use to get the
-            path to the driver executable.
+        executable_path: (Optional) Install path of the executable.
+        port: (Optional) Port for the service to run on, defaults to 0 where the operating system will decide.
+        service_args: (Optional) Sequence of args to be passed to the subprocess when launching the executable.
+        log_output: (Optional) int representation of STDOUT/DEVNULL, any IO instance or String path to file.
+        env: (Optional) Mapping of environment variables for the new process, defaults to `os.environ`.
+        driver_path_env_key: (Optional) Environment variable to use to get the path to the driver executable.
     """
 
     def __init__(
@@ -54,9 +48,7 @@ def __init__(
 
         if isinstance(log_output, str):
             self._service_args.append(f"--log-path={log_output}")
-            self.log_output: IOBase | None = None
-        elif isinstance(log_output, IOBase):
-            self.log_output = log_output
+            self.log_output = None
         else:
             self.log_output = log_output
 

py/selenium/webdriver/common/bidi/browsing_context.py

@@ -984,8 +984,8 @@ def reload(
     def set_viewport(
         self,
         context: str | None = None,
-        viewport: dict | None | UNDEFINED = UNDEFINED,
-        device_pixel_ratio: float | None | UNDEFINED = UNDEFINED,
+        viewport: dict | None | Sentinel = UNDEFINED,
+        device_pixel_ratio: float | None | Sentinel = UNDEFINED,
         user_contexts: list[str] | None = None,
     ) -> None:
         """Modifies specific viewport characteristics on the given top-level traversable.

py/selenium/webdriver/common/service.py

@@ -25,7 +25,7 @@
 from io import IOBase
 from subprocess import PIPE
 from time import sleep
-from typing import IO, Any, cast
+from typing import IO, Any
 from urllib import request
 from urllib.error import URLError
 
@@ -42,8 +42,8 @@ class Service(ABC):
     communicate with a browser.
 
     Args:
-        executable: install path of the executable.
-        port: Port for the service to run on, defaults to 0 where the operating system will decide.
+        executable_path: (Optional) Install path of the executable.
+        port: (Optional) Port for the service to run on, defaults to 0 where the operating system will decide.
         log_output: (Optional) int representation of STDOUT/DEVNULL, any IO instance or String path to file.
         env: (Optional) Mapping of environment variables for the new process, defaults to `os.environ`.
         driver_path_env_key: (Optional) Environment variable to use to get the path to the driver executable.
@@ -58,15 +58,15 @@ def __init__(
         driver_path_env_key: str | None = None,
         **kwargs,
     ) -> None:
-        self.log_output: int | IOBase | None
+        self.log_output: int | IO[Any] | None
         if isinstance(log_output, str):
-            self.log_output = cast(IOBase, open(log_output, "a+", encoding="utf-8"))
+            self.log_output = open(log_output, "a+", encoding="utf-8")
         elif log_output == subprocess.STDOUT:
             self.log_output = None
         elif log_output is None or log_output == subprocess.DEVNULL:
             self.log_output = subprocess.DEVNULL
         else:
-            self.log_output = cast(int | IOBase, log_output)
+            self.log_output = log_output
 
         self.port = port or utils.free_port()
         # Default value for every python subprocess: subprocess.Popen(..., creationflags=0)
@@ -220,8 +220,8 @@ def _start_process(self, path: str) -> None:
                 cmd,
                 env=self.env,
                 close_fds=close_file_descriptors,
-                stdout=cast(int | IO[Any] | None, self.log_output),
-                stderr=cast(int | IO[Any] | None, self.log_output),
+                stdout=self.log_output,
+                stderr=self.log_output,
                 stdin=PIPE,
                 creationflags=self.creation_flags,
                 startupinfo=start_info,

py/selenium/webdriver/firefox/service.py

@@ -22,11 +22,11 @@
 
 
 class Service(service.Service):
-    """Service class responsible for starting and stopping geckodriver.
+    """Service class responsible for starting and stopping of `geckodriver`.
 
     Args:
-        executable_path: install path of the geckodriver executable, defaults to `geckodriver`.
-        port: Port for the service to run on, defaults to 0 where the operating system will decide.
+        executable_path: (Optional) Install path of the executable.
+        port: (Optional) Port for the service to run on, defaults to 0 where the operating system will decide.
         service_args: (Optional) Sequence of args to be passed to the subprocess when launching the executable.
         log_output: (Optional) int representation of STDOUT/DEVNULL, any IO instance or String path to file.
         env: (Optional) Mapping of environment variables for the new process, defaults to `os.environ`.

py/selenium/webdriver/ie/service.py

@@ -22,7 +22,19 @@
 
 
 class Service(service.Service):
-    """Object that manages the starting and stopping of the IEDriver."""
+    """Service class responsible for starting and stopping of `IEDriver`.
+
+    Args:
+        executable_path: (Optional) Install path of the executable.
+        port: (Optional) Port for the service to run on, defaults to 0 where the operating system will decide.
+        host: (Optional) IP address the service port is bound
+        service_args: (Optional) Sequence of args to be passed to the subprocess when launching the executable.
+        log_level: (Optional) Level of logging of service, may be "FATAL", "ERROR", "WARN", "INFO", "DEBUG",
+            "TRACE". Default is "FATAL".
+        log_output: (Optional) int representation of STDOUT/DEVNULL, any IO instance or String path to file.
+        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.
+    """
 
     def __init__(
         self,
@@ -35,20 +47,6 @@ def __init__(
         driver_path_env_key: str | None = None,
         **kwargs,
     ) -> None:
-        """Creates a new instance of the Service.
-
-        Args:
-            executable_path: Path to the IEDriver
-            port: Port the service is running on
-            host: (Optional) IP address the service port is bound
-            service_args: (Optional) Sequence of args to be passed to the subprocess when launching the executable.
-            log_level: (Optional) Level of logging of service, may be "FATAL", "ERROR", "WARN", "INFO", "DEBUG",
-                "TRACE". Default is "FATAL".
-            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"