[py]: docs and types for EdgeService. deprecate verbose=True

Author: symonk

py/conftest.py

@@ -241,3 +241,9 @@ def webserver():
     webserver.start()
     yield webserver
     webserver.stop()
+
+
+@pytest.fixture
+def edge_service():
+    from selenium.webdriver.edge.service import Service as EdgeService
+    return EdgeService

py/selenium/webdriver/chromium/service.py

@@ -26,7 +26,7 @@ class ChromiumService(service.Service):
     :param executable_path: install path of the executable.
     :param port: Port for the service to run on, defaults to 0 where the operating system will decide.
     :param service_args: (Optional) Sequence of args to be passed to the subprocess when launching the executable.
-    :param log_path: (Optional) String to be passed to the executable as `--log-path`
+    :param log_path: (Optional) String to be passed to the executable as `--log-path`.
     :param env: (Optional) Mapping of environment variables for the new process, defaults to `os.environ`.
     :param start_error_message: (Optional) Error message that forms part of the error when problems occur
     launching the subprocess.

py/selenium/webdriver/edge/service.py

@@ -14,48 +14,51 @@
 # KIND, either express or implied.  See the License for the
 # specific language governing permissions and limitations
 # under the License.
-
-from typing import List
+import typing
+import warnings
 
 from selenium.webdriver.chromium import service
 
 DEFAULT_EXECUTABLE_PATH = "msedgedriver"
 
 
 class Service(service.ChromiumService):
+    """A Service class that is responsible for the starting and stopping
+    of `msedgedriver`.
+
+    :param executable_path: install path of the msedgedriver executable, defaults to `msedgedriver`.
+    :param port: Port for the service to run on, defaults to 0 where the operating system will decide.
+    :param verbose: (Deprecated) Whether to make the webdriver more verbose (passes the --verbose option to the binary).
+        Defaults to False.
+    :param log_path: (Optional) String to be passed to the executable as `--log-path`.
+    :param service_args: (Optional) Sequence of args to be passed to the subprocess when launching the executable.
+    :param env: (Optional) Mapping of environment variables for the new process, defaults to `os.environ`.
+    """
+
     def __init__(
         self,
         executable_path: str = DEFAULT_EXECUTABLE_PATH,
         port: int = 0,
         verbose: bool = False,
-        log_path: str = None,
-        service_args: List[str] = None,
-        env=None,
+        log_path: typing.Optional[str] = None,
+        service_args: typing.Optional[typing.Sequence[str]] = None,
+        env: typing.Optional[typing.Mapping[str, str]] = None,
     ):
-        """
-        Creates a new instance of the EdgeDriver service.
-        EdgeDriver provides an interface for Microsoft WebDriver to use
-        with Microsoft Edge.
-
-        :Args:
-         - executable_path : Path to the Microsoft WebDriver binary.
-         - port : Run the remote service on a specified port. Defaults to 0, which binds to a random open port
-           of the system's choosing.
-         - verbose : Whether to make the webdriver more verbose (passes the --verbose option to the binary).
-           Defaults to False.
-         - log_path : Optional path for the webdriver binary to log to. Defaults to None which disables logging.
-         - service_args : List of args to pass to the WebDriver service.
-        """
         self.service_args = service_args or []
 
         if verbose:
+            warnings.warn(
+                "verbose=True is deprecated. Use `service_args=['--verbose', ...]` instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
             self.service_args.append("--verbose")
 
         super().__init__(
-            executable_path,
-            port,
-            service_args,
-            log_path,
-            env,
-            "Please download from https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/",
+            executable_path=executable_path,
+            port=port,
+            service_args=service_args,
+            log_path=log_path,
+            env=env,
+            start_error_message="Please download from https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/",
         )

py/test/unit/selenium/webdriver/edge/edge_service_tests.py

@@ -0,0 +1,6 @@
+import pytest
+
+
+def test_edge_service_verbose_flag_is_deprecated(edge_service) -> None:
+    with pytest.warns(match="verbose=True is deprecated", expected_warning=DeprecationWarning):
+        edge_service(verbose=True)