refactor[py]: Add type hints to options.py

- Added explicit type annotations to selenium.webdriver.common.options.py
- Improved code clarity and static type checking
- Ensured compatibility with modern type checkers like Pyright and Mypy

Author: duxtec

py/selenium/webdriver/common/options.py

@@ -19,9 +19,9 @@
 from abc import ABCMeta
 from abc import abstractmethod
 from enum import Enum
+from typing import Any
 from typing import Optional
 
-from selenium.common.exceptions import InvalidArgumentException
 from selenium.webdriver.common.proxy import Proxy
 
 
@@ -42,23 +42,28 @@ class PageLoadStrategy(str, Enum):
 
 
 class _BaseOptionsDescriptor:
-    def __init__(self, name):
+    def __init__(self, name: str):
         self.name = name
 
-    def __get__(self, obj, cls):
+    def __get__(self, obj: object, cls: type[object]):
+        if not isinstance(obj, BaseOptions):
+            raise ValueError("Invalid object: Expected an instance of BaseOptions.")
         if self.name == "enableBidi":
             # whether BiDi is or will be enabled
-            value = obj._caps.get("webSocketUrl")
+            value = obj.capabilities.get("webSocketUrl")
             return value is True or isinstance(value, str)
         if self.name == "webSocketUrl":
             # Return socket url or None if not created yet
-            value = obj._caps.get(self.name)
+            value = obj.capabilities.get(self.name)
             return None if not isinstance(value, str) else value
         if self.name in ("acceptInsecureCerts", "strictFileInteractability", "setWindowRect", "se:downloadsEnabled"):
-            return obj._caps.get(self.name, False)
-        return obj._caps.get(self.name)
+            return obj.capabilities.get(self.name, False)
+        return obj.capabilities.get(self.name)
+
+    def __set__(self, obj: object, value: Any):
+        if not isinstance(obj, BaseOptions):
+            raise ValueError("Invalid object: Expected an instance of BaseOptions.")
 
-    def __set__(self, obj, value):
         if self.name == "enableBidi":
             obj.set_capability("webSocketUrl", value)
         else:
@@ -72,17 +77,20 @@ class _PageLoadStrategyDescriptor:
     :param strategy: the strategy corresponding to a document readiness state
     """
 
-    def __init__(self, name):
+    def __init__(self, name: str):
         self.name = name
 
-    def __get__(self, obj, cls):
-        return obj._caps.get(self.name)
+    def __get__(self, obj: object, cls: type[object]):
+        if not isinstance(obj, BaseOptions):
+            raise ValueError("Invalid object: Expected an instance of BaseOptions.")
+        return obj.capabilities.get(self.name)
 
-    def __set__(self, obj, value):
-        if value in ("normal", "eager", "none"):
-            obj.set_capability(self.name, value)
-        else:
+    def __set__(self, obj: object, value: str):
+        if not isinstance(obj, BaseOptions):
+            raise ValueError("Invalid object: Expected an instance of BaseOptions.")
+        if value not in ("normal", "eager", "none"):
             raise ValueError("Strategy can only be one of the following: normal, eager, none")
+        obj.set_capability(self.name, value)
 
 
 class _UnHandledPromptBehaviorDescriptor:
@@ -95,20 +103,23 @@ class _UnHandledPromptBehaviorDescriptor:
     :returns: Values for implicit timeout, pageLoad timeout and script timeout if set (in milliseconds)
     """
 
-    def __init__(self, name):
+    def __init__(self, name: str):
         self.name = name
 
-    def __get__(self, obj, cls):
-        return obj._caps.get(self.name)
+    def __get__(self, obj: object, cls: type[object]):
+        if not isinstance(obj, BaseOptions):
+            raise ValueError("Invalid object: Expected an instance of BaseOptions.")
+        return obj.capabilities.get(self.name)
 
-    def __set__(self, obj, value):
-        if value in ("dismiss", "accept", "dismiss and notify", "accept and notify", "ignore"):
-            obj.set_capability(self.name, value)
-        else:
+    def __set__(self, obj: object, value: str):
+        if not isinstance(obj, BaseOptions):
+            raise ValueError("Invalid object: Expected an instance of BaseOptions.")
+        if value not in ("dismiss", "accept", "dismiss and notify", "accept and notify", "ignore"):
             raise ValueError(
                 "Behavior can only be one of the following: dismiss, accept, dismiss and notify, "
                 "accept and notify, ignore"
             )
+        obj.set_capability(self.name, value)
 
 
 class _TimeoutsDescriptor:
@@ -120,13 +131,17 @@ class _TimeoutsDescriptor:
     :returns: Values for implicit timeout, pageLoad timeout and script timeout if set (in milliseconds)
     """
 
-    def __init__(self, name):
+    def __init__(self, name: str):
         self.name = name
 
-    def __get__(self, obj, cls):
-        return obj._caps.get(self.name)
+    def __get__(self, obj: object, cls: type[object]):
+        if not isinstance(obj, BaseOptions):
+            raise ValueError("Invalid object: Expected an instance of BaseOptions.")
+        return obj.capabilities.get(self.name)
 
-    def __set__(self, obj, value):
+    def __set__(self, obj: object, value: dict[str, Any]):
+        if not isinstance(obj, BaseOptions):
+            raise ValueError("Invalid object: Expected an instance of BaseOptions.")
         if all(x in ("implicit", "pageLoad", "script") for x in value.keys()):
             obj.set_capability(self.name, value)
         else:
@@ -136,17 +151,19 @@ def __set__(self, obj, value):
 class _ProxyDescriptor:
     """:Returns: Proxy if set, otherwise None."""
 
-    def __init__(self, name):
+    def __init__(self, name: str):
         self.name = name
 
-    def __get__(self, obj, cls):
+    def __get__(self, obj: object, cls: type[object]):
+        if not isinstance(obj, BaseOptions):
+            raise ValueError("Invalid object: Expected an instance of BaseOptions.")
         return obj._proxy
 
-    def __set__(self, obj, value):
-        if not isinstance(value, Proxy):
-            raise InvalidArgumentException("Only Proxy objects can be passed in.")
+    def __set__(self, obj: object, value: Proxy):
+        if not isinstance(obj, BaseOptions):
+            raise ValueError("Invalid object: Expected an instance of BaseOptions.")
         obj._proxy = value
-        obj._caps[self.name] = value.to_capabilities()
+        obj.capabilities[self.name] = value.to_capabilities()
 
 
 class BaseOptions(metaclass=ABCMeta):
@@ -421,7 +438,7 @@ class BaseOptions(metaclass=ABCMeta):
     def __init__(self) -> None:
         super().__init__()
         self._caps = self.default_capabilities
-        self._proxy = None
+        self._proxy: Proxy | None = None
         self.set_capability("pageLoadStrategy", PageLoadStrategy.normal)
         self.mobile_options = None
         self._ignore_local_proxy = False
@@ -430,7 +447,7 @@ def __init__(self) -> None:
     def capabilities(self):
         return self._caps
 
-    def set_capability(self, name, value) -> None:
+    def set_capability(self, name: Any, value: Any) -> None:
         """Sets a capability."""
         self._caps[name] = value
 
@@ -454,12 +471,12 @@ def enable_mobile(
             self.mobile_options["androidDeviceSerial"] = device_serial
 
     @abstractmethod
-    def to_capabilities(self):
+    def to_capabilities(self) -> dict[Any, Any]:
         """Convert options into capabilities dictionary."""
 
     @property
     @abstractmethod
-    def default_capabilities(self):
+    def default_capabilities(self) -> dict[Any, Any]:
         """Return minimal capabilities necessary as a dictionary."""
 
     def ignore_local_proxy_environment_variables(self) -> None:
@@ -475,14 +492,14 @@ class ArgOptions(BaseOptions):
 
     def __init__(self) -> None:
         super().__init__()
-        self._arguments = []
+        self._arguments: list[Any] = []
 
     @property
     def arguments(self):
         """:Returns: A list of arguments needed for the browser."""
         return self._arguments
 
-    def add_argument(self, argument) -> None:
+    def add_argument(self, argument: Any) -> None:
         """Adds an argument to the list.
 
         :Args:
@@ -511,5 +528,5 @@ def to_capabilities(self):
         return self._caps
 
     @property
-    def default_capabilities(self):
+    def default_capabilities(self) -> dict[Any, Any]:
         return {}