[py] Upgrade type hints (SeleniumHQ#15784)

- Upgrade type hints to Python 3.9+ syntax throughout codebase
- Replace legacy List, Dict, Tuple, etc. with built-in generics (e.g., list, dict, tuple)
- Move type hints to use collections.abc where appropriate

Author: cgoldberg

py/selenium/common/exceptions.py

@@ -16,7 +16,8 @@
 # under the License.
 """Exceptions that may happen in all the webdriver code."""
 
-from typing import Optional, Sequence
+from collections.abc import Sequence
+from typing import Optional
 
 SUPPORT_MSG = "For documentation on this error, please visit:"
 ERROR_URL = "https://www.selenium.dev/documentation/webdriver/troubleshooting/errors"

py/selenium/types.py

@@ -16,10 +16,11 @@
 # under the License.
 """Selenium type definitions."""
 
-from typing import IO, Any, Iterable, Type, Union
+from collections.abc import Iterable
+from typing import IO, Any, Union
 
 AnyKey = Union[str, int, float]
-WaitExcTypes = Iterable[Type[Exception]]
+WaitExcTypes = Iterable[type[Exception]]
 
 # Service Types
 SubprocessStdAlias = Union[int, str, IO[Any]]

py/selenium/webdriver/chrome/service.py

@@ -16,7 +16,8 @@
 # under the License.
 
 
-from typing import List, Mapping, Optional
+from collections.abc import Mapping
+from typing import Optional
 
 from selenium.types import SubprocessStdAlias
 from selenium.webdriver.chromium import service
@@ -37,7 +38,7 @@ def __init__(
         self,
         executable_path: Optional[str] = None,
         port: int = 0,
-        service_args: Optional[List[str]] = None,
+        service_args: Optional[list[str]] = None,
         log_output: Optional[SubprocessStdAlias] = None,
         env: Optional[Mapping[str, str]] = None,
         **kwargs,

py/selenium/webdriver/chromium/options.py

@@ -17,7 +17,7 @@
 
 import base64
 import os
-from typing import BinaryIO, Dict, List, Optional, Union
+from typing import BinaryIO, Optional, Union
 
 from selenium.webdriver.common.desired_capabilities import DesiredCapabilities
 from selenium.webdriver.common.options import ArgOptions
@@ -29,9 +29,9 @@ class ChromiumOptions(ArgOptions):
     def __init__(self) -> None:
         super().__init__()
         self._binary_location: str = ""
-        self._extension_files: List[str] = []
-        self._extensions: List[str] = []
-        self._experimental_options: Dict[str, Union[str, int, dict, List[str]]] = {}
+        self._extension_files: list[str] = []
+        self._extensions: list[str] = []
+        self._experimental_options: dict[str, Union[str, int, dict, list[str]]] = {}
         self._debugger_address: Optional[str] = None
 
     @property
@@ -68,7 +68,7 @@ def debugger_address(self, value: str) -> None:
         self._debugger_address = value
 
     @property
-    def extensions(self) -> List[str]:
+    def extensions(self) -> list[str]:
         """:Returns: A list of encoded extensions that will be loaded."""
 
         def _decode(file_data: BinaryIO) -> str:
@@ -117,7 +117,7 @@ def experimental_options(self) -> dict:
         """: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:
+    def add_experimental_option(self, name: str, value: Union[str, int, dict, list[str]]) -> None:
         """Adds an experimental option which is passed to chromium.
 
         :Args:

py/selenium/webdriver/chromium/service.py

@@ -14,8 +14,9 @@
 # KIND, either express or implied.  See the License for the
 # specific language governing permissions and limitations
 # under the License.
+from collections.abc import Mapping
 from io import IOBase
-from typing import List, Mapping, Optional
+from typing import Optional
 
 from selenium.types import SubprocessStdAlias
 from selenium.webdriver.common import service
@@ -37,7 +38,7 @@ def __init__(
         self,
         executable_path: Optional[str] = None,
         port: int = 0,
-        service_args: Optional[List[str]] = None,
+        service_args: Optional[list[str]] = None,
         log_output: Optional[SubprocessStdAlias] = None,
         env: Optional[Mapping[str, str]] = None,
         driver_path_env_key: Optional[str] = None,
@@ -63,5 +64,5 @@ def __init__(
             **kwargs,
         )
 
-    def command_line_args(self) -> List[str]:
+    def command_line_args(self) -> list[str]:
         return [f"--port={self.port}"] + self.service_args

py/selenium/webdriver/common/actions/action_builder.py

@@ -15,7 +15,7 @@
 # specific language governing permissions and limitations
 # under the License.
 
-from typing import List, Optional, Union
+from typing import Optional, Union
 
 from selenium.webdriver.remote.command import Command
 
@@ -61,11 +61,11 @@ def get_device_with(self, name: str) -> Optional[Union["WheelInput", "PointerInp
         return next(filter(lambda x: x == name, self.devices), None)
 
     @property
-    def pointer_inputs(self) -> List[PointerInput]:
+    def pointer_inputs(self) -> list[PointerInput]:
         return [device for device in self.devices if device.type == interaction.POINTER]
 
     @property
-    def key_inputs(self) -> List[KeyInput]:
+    def key_inputs(self) -> list[KeyInput]:
         return [device for device in self.devices if device.type == interaction.KEY]
 
     @property

py/selenium/webdriver/common/actions/input_device.py

@@ -16,15 +16,15 @@
 # under the License.
 
 import uuid
-from typing import Any, List, Optional
+from typing import Any, Optional
 
 
 class InputDevice:
     """Describes the input device being used for the action."""
 
     def __init__(self, name: Optional[str] = None):
         self.name = name or uuid.uuid4()
-        self.actions: List[Any] = []
+        self.actions: list[Any] = []
 
     def add_action(self, action: Any) -> None:
         """"""

py/selenium/webdriver/common/actions/interaction.py

@@ -14,7 +14,7 @@
 # KIND, either express or implied.  See the License for the
 # specific language governing permissions and limitations
 # under the License.
-from typing import Dict, Union
+from typing import Union
 
 KEY = "key"
 POINTER = "pointer"
@@ -41,5 +41,5 @@ def __init__(self, source, duration: float = 0) -> None:
         super().__init__(source)
         self.duration = duration
 
-    def encode(self) -> Dict[str, Union[str, int]]:
+    def encode(self) -> dict[str, Union[str, int]]:
         return {"type": self.PAUSE, "duration": int(self.duration * 1000)}

py/selenium/webdriver/common/actions/pointer_input.py

@@ -15,7 +15,7 @@
 # specific language governing permissions and limitations
 # under the License.
 
-from typing import Any, Dict, Optional, Union
+from typing import Any, Optional, Union
 
 from selenium.common.exceptions import InvalidArgumentException
 from selenium.webdriver.remote.webelement import WebElement
@@ -66,7 +66,7 @@ def create_pause(self, pause_duration: Union[int, float] = 0) -> None:
     def encode(self):
         return {"type": self.type, "parameters": {"pointerType": self.kind}, "id": self.name, "actions": self.actions}
 
-    def _convert_keys(self, actions: Dict[str, Any]):
+    def _convert_keys(self, actions: dict[str, Any]):
         out = {}
         for k, v in actions.items():
             if v is None:

py/selenium/webdriver/common/bidi/browser.py

@@ -15,7 +15,6 @@
 # specific language governing permissions and limitations
 # under the License.
 
-from typing import Dict, List
 
 from selenium.webdriver.common.bidi.common import command_builder
 
@@ -114,7 +113,7 @@ def is_active(self) -> bool:
         return self.active
 
     @classmethod
-    def from_dict(cls, data: Dict) -> "ClientWindowInfo":
+    def from_dict(cls, data: dict) -> "ClientWindowInfo":
         """Creates a ClientWindowInfo instance from a dictionary.
 
         Parameters:
@@ -154,7 +153,7 @@ def create_user_context(self) -> str:
         result = self.conn.execute(command_builder("browser.createUserContext", {}))
         return result["userContext"]
 
-    def get_user_contexts(self) -> List[str]:
+    def get_user_contexts(self) -> list[str]:
         """Gets all user contexts.
 
         Returns:
@@ -181,7 +180,7 @@ def remove_user_context(self, user_context_id: str) -> None:
         params = {"userContext": user_context_id}
         self.conn.execute(command_builder("browser.removeUserContext", params))
 
-    def get_client_windows(self) -> List[ClientWindowInfo]:
+    def get_client_windows(self) -> list[ClientWindowInfo]:
         """Gets all client windows.
 
         Returns:

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

@@ -15,7 +15,7 @@
 # specific language governing permissions and limitations
 # under the License.
 
-from typing import Dict, List, Optional, Union
+from typing import Optional, Union
 
 from selenium.webdriver.common.bidi.common import command_builder
 
@@ -55,7 +55,7 @@ def __init__(
         self.url = url
 
     @classmethod
-    def from_json(cls, json: Dict) -> "NavigationInfo":
+    def from_json(cls, json: dict) -> "NavigationInfo":
         """Creates a NavigationInfo instance from a dictionary.
 
         Parameters:
@@ -81,7 +81,7 @@ def __init__(
         self,
         context: str,
         url: str,
-        children: Optional[List["BrowsingContextInfo"]],
+        children: Optional[list["BrowsingContextInfo"]],
         parent: Optional[str] = None,
         user_context: Optional[str] = None,
         original_opener: Optional[str] = None,
@@ -96,7 +96,7 @@ def __init__(
         self.client_window = client_window
 
     @classmethod
-    def from_json(cls, json: Dict) -> "BrowsingContextInfo":
+    def from_json(cls, json: dict) -> "BrowsingContextInfo":
         """Creates a BrowsingContextInfo instance from a dictionary.
 
         Parameters:
@@ -137,7 +137,7 @@ def __init__(
         self.suggested_filename = suggested_filename
 
     @classmethod
-    def from_json(cls, json: Dict) -> "DownloadWillBeginParams":
+    def from_json(cls, json: dict) -> "DownloadWillBeginParams":
         """Creates a DownloadWillBeginParams instance from a dictionary.
 
         Parameters:
@@ -175,7 +175,7 @@ def __init__(
         self.default_value = default_value
 
     @classmethod
-    def from_json(cls, json: Dict) -> "UserPromptOpenedParams":
+    def from_json(cls, json: dict) -> "UserPromptOpenedParams":
         """Creates a UserPromptOpenedParams instance from a dictionary.
 
         Parameters:
@@ -211,7 +211,7 @@ def __init__(
         self.user_text = user_text
 
     @classmethod
-    def from_json(cls, json: Dict) -> "UserPromptClosedParams":
+    def from_json(cls, json: dict) -> "UserPromptClosedParams":
         """Creates a UserPromptClosedParams instance from a dictionary.
 
         Parameters:
@@ -242,7 +242,7 @@ def __init__(
         self.url = url
 
     @classmethod
-    def from_json(cls, json: Dict) -> "HistoryUpdatedParams":
+    def from_json(cls, json: dict) -> "HistoryUpdatedParams":
         """Creates a HistoryUpdatedParams instance from a dictionary.
 
         Parameters:
@@ -267,7 +267,7 @@ def __init__(self, event_class: str, **kwargs):
         self.params = kwargs
 
     @classmethod
-    def from_json(cls, json: Dict) -> "BrowsingContextEvent":
+    def from_json(cls, json: dict) -> "BrowsingContextEvent":
         """Creates a BrowsingContextEvent instance from a dictionary.
 
         Parameters:
@@ -323,8 +323,8 @@ def capture_screenshot(
         self,
         context: str,
         origin: str = "viewport",
-        format: Optional[Dict] = None,
-        clip: Optional[Dict] = None,
+        format: Optional[dict] = None,
+        clip: Optional[dict] = None,
     ) -> str:
         """Captures an image of the given navigable, and returns it as a Base64-encoded string.
 
@@ -398,7 +398,7 @@ def get_tree(
         self,
         max_depth: Optional[int] = None,
         root: Optional[str] = None,
-    ) -> List[BrowsingContextInfo]:
+    ) -> list[BrowsingContextInfo]:
         """Returns a tree of all descendent navigables including the given parent itself, or all top-level contexts
         when no parent is provided.
 
@@ -445,11 +445,11 @@ def handle_user_prompt(
     def locate_nodes(
         self,
         context: str,
-        locator: Dict,
+        locator: dict,
         max_node_count: Optional[int] = None,
-        serialization_options: Optional[Dict] = None,
-        start_nodes: Optional[List[Dict]] = None,
-    ) -> List[Dict]:
+        serialization_options: Optional[dict] = None,
+        start_nodes: Optional[list[dict]] = None,
+    ) -> list[dict]:
         """Returns a list of all nodes matching the specified locator.
 
         Parameters:
@@ -480,7 +480,7 @@ def navigate(
         context: str,
         url: str,
         wait: Optional[str] = None,
-    ) -> Dict:
+    ) -> dict:
         """Navigates a navigable to the given URL.
 
         Parameters:
@@ -504,10 +504,10 @@ def print(
         self,
         context: str,
         background: bool = False,
-        margin: Optional[Dict] = None,
+        margin: Optional[dict] = None,
         orientation: str = "portrait",
-        page: Optional[Dict] = None,
-        page_ranges: Optional[List[Union[int, str]]] = None,
+        page: Optional[dict] = None,
+        page_ranges: Optional[list[Union[int, str]]] = None,
         scale: float = 1.0,
         shrink_to_fit: bool = True,
     ) -> str:
@@ -551,7 +551,7 @@ def reload(
         context: str,
         ignore_cache: Optional[bool] = None,
         wait: Optional[str] = None,
-    ) -> Dict:
+    ) -> dict:
         """Reloads a navigable.
 
         Parameters:
@@ -576,9 +576,9 @@ def reload(
     def set_viewport(
         self,
         context: Optional[str] = None,
-        viewport: Optional[Dict] = None,
+        viewport: Optional[dict] = None,
         device_pixel_ratio: Optional[float] = None,
-        user_contexts: Optional[List[str]] = None,
+        user_contexts: Optional[list[str]] = None,
     ) -> None:
         """Modifies specific viewport characteristics on the given top-level traversable.
 
@@ -605,7 +605,7 @@ def set_viewport(
 
         self.conn.execute(command_builder("browsingContext.setViewport", params))
 
-    def traverse_history(self, context: str, delta: int) -> Dict:
+    def traverse_history(self, context: str, delta: int) -> dict:
         """Traverses the history of a given navigable by a delta.
 
         Parameters:
@@ -665,7 +665,7 @@ def _callback(event_data):
 
         return callback_id
 
-    def add_event_handler(self, event: str, callback: callable, contexts: Optional[List[str]] = None) -> int:
+    def add_event_handler(self, event: str, callback: callable, contexts: Optional[list[str]] = None) -> int:
         """Add an event handler to the browsing context.
 
         Parameters: