Refactor docstrings for clarity and conciseness across multiple files

Author: iampopovich

py/generate.py

@@ -216,7 +216,7 @@ class CdpProperty:
     deprecated: bool
 
     @property
-    def py_name(self):
+    def py_name(self)->str:
         ''' Get this property's Python name. '''
         return snake_case(self.name)
 
@@ -590,7 +590,7 @@ class CdpCommand:
     domain: str
 
     @property
-    def py_name(self):
+    def py_name(self) -> str:
         ''' Get a Python name for this command. '''
         return snake_case(self.name)
 
@@ -794,7 +794,7 @@ class CdpDomain:
     events: List[CdpEvent]
 
     @property
-    def module(self):
+    def module(self) -> str:
         ''' The name of the Python module for this CDP domain. '''
         return snake_case(self.domain)
 

py/selenium/webdriver/chromium/options.py

@@ -38,10 +38,7 @@ def __init__(self) -> None:
 
     @property
     def binary_location(self) -> str:
-        """
-        Returns:
-            The location of the binary, otherwise an empty string.
-        """
+        """Returns the location of the binary, otherwise an empty string."""
         return self._binary_location
 
     @binary_location.setter
@@ -57,16 +54,12 @@ def binary_location(self, value: str) -> None:
 
     @property
     def debugger_address(self) -> Optional[str]:
-        """
-        Returns:
-            The address of the remote devtools instance.
-        """
+        """Returns the address of the remote devtools instance."""
         return self._debugger_address
 
     @debugger_address.setter
     def debugger_address(self, value: str) -> None:
-        """Allows you to set the address of the remote devtools instance that
-        the ChromeDriver instance will try to connect to during an active wait.
+        """Set the address of the remote devtools instance for active wait connection.
 
         Args:
             value: Address of remote devtools instance if any (hostname[:port]).
@@ -77,10 +70,7 @@ def debugger_address(self, value: str) -> None:
 
     @property
     def extensions(self) -> list[str]:
-        """
-        Returns:
-            A list of encoded extensions that will be loaded.
-        """
+        """Returns a list of encoded extensions that will be loaded."""
 
         def _decode(file_data: BinaryIO) -> str:
             # Should not use base64.encodestring() which inserts newlines every
@@ -96,8 +86,7 @@ def _decode(file_data: BinaryIO) -> str:
         return encoded_extensions + self._extensions
 
     def add_extension(self, extension: str) -> None:
-        """Adds the path to the extension to a list that will be used to
-        extract it to the ChromeDriver.
+        """Add the path to an extension to be extracted to ChromeDriver.
 
         Args:
             extension: Path to the *.crx file.
@@ -112,8 +101,7 @@ def add_extension(self, extension: str) -> None:
             raise ValueError("argument can not be null")
 
     def add_encoded_extension(self, extension: str) -> None:
-        """Adds Base64 encoded string with extension data to a list that will
-        be used to extract it to the ChromeDriver.
+        """Add Base64-encoded string with extension data to be extracted to ChromeDriver.
 
         Args:
             extension: Base64 encoded string with extension data.
@@ -125,10 +113,7 @@ def add_encoded_extension(self, extension: str) -> None:
 
     @property
     def experimental_options(self) -> dict:
-        """
-        Returns:
-            A dictionary of experimental options for chromium.
-        """
+        """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:
@@ -142,11 +127,7 @@ def add_experimental_option(self, name: str, value: Union[str, int, dict, list[s
 
     @property
     def enable_webextensions(self) -> bool:
-        """
-        Returns:
-            Whether webextension support is enabled for Chromium-based browsers.
-            True if webextension support is enabled, False otherwise.
-        """
+        """Return whether webextension support is enabled for Chromium-based browsers."""
         return self._enable_webextensions
 
     @enable_webextensions.setter

py/selenium/webdriver/chromium/webdriver.py

@@ -26,9 +26,7 @@
 
 
 class ChromiumDriver(RemoteWebDriver):
-    """Controls the WebDriver instance of ChromiumDriver and allows you to
-    drive the browser.
-    """
+    """Control the WebDriver instance of ChromiumDriver and drive the browser."""
 
     def __init__(
         self,
@@ -38,8 +36,7 @@ def __init__(
         service: Optional[ChromiumService] = None,
         keep_alive: bool = True,
     ) -> None:
-        """Creates a new WebDriver instance of the ChromiumDriver. Starts the
-        service and then creates new WebDriver instance of ChromiumDriver.
+        """Create a new WebDriver instance, start the service, and create new ChromiumDriver instance.
 
         Args:
             browser_name: Browser name used when matching capabilities.
@@ -148,17 +145,11 @@ def execute_cdp_cmd(self, cmd: str, cmd_args: dict):
         return super().execute_cdp_cmd(cmd, cmd_args)
 
     def get_sinks(self) -> list:
-        """
-        Returns:
-            A list of sinks available for Cast.
-        """
+        """Get a list of sinks available for Cast."""
         return self.execute("getSinks")["value"]
 
     def get_issue_message(self):
-        """
-        Returns:
-            An error message when there is any issue in a Cast session.
-        """
+        """Returns an error message when there is any issue in a Cast session."""
         return self.execute("getIssueMessage")["value"]
 
     @property
@@ -186,8 +177,7 @@ def get_log(self, log_type):
         return self.execute(Command.GET_LOG, {"type": log_type})["value"]
 
     def set_sink_to_use(self, sink_name: str) -> dict:
-        """Sets a specific sink, using its name, as a Cast session receiver
-        target.
+        """Set a specific sink as a Cast session receiver target.
 
         Args:
             sink_name: Name of the sink to use as the target.

py/selenium/webdriver/common/driver_finder.py

@@ -26,8 +26,7 @@
 
 
 class DriverFinder:
-    """A Driver finding class responsible for obtaining the correct driver and
-    associated browser.
+    """Find and obtain the correct driver and associated browser.
 
     Args:
         service: instance of the driver service class.

py/selenium/webdriver/common/log.py

@@ -34,8 +34,7 @@ def import_cdp():
 
 
 class Log:
-    """This class allows access to logging APIs that use the new WebDriver Bidi
-    protocol.
+    """Class for accessing logging APIs using the WebDriver Bidi protocol.
 
     This class is not to be used directly and should be used from the
     webdriver base classes.
@@ -95,8 +94,7 @@ async def mutation_events(self) -> AsyncGenerator[dict[str, Any], None]:
 
     @asynccontextmanager
     async def add_js_error_listener(self) -> AsyncGenerator[dict[str, Any], None]:
-        """Listen for JS errors and when the contextmanager exits check if
-        there were JS Errors.
+        """Listen for JS errors and check if they occurred when the context manager exits.
 
         Example:
                 async with driver.log.add_js_error_listener() as error:

py/selenium/webdriver/common/options.py

@@ -143,7 +143,8 @@ def __set__(self, obj, value):
 
 
 class _ProxyDescriptor:
-    """
+    """Descriptor for proxy property access.
+
     Returns:
         Proxy if set, otherwise None.
     """
@@ -379,9 +380,7 @@ def default_capabilities(self):
         """Return minimal capabilities necessary as a dictionary."""
 
     def ignore_local_proxy_environment_variables(self) -> None:
-        """By calling this you will ignore HTTP_PROXY and HTTPS_PROXY from
-        being picked up and used.
-        """
+        """Ignore HTTP_PROXY and HTTPS_PROXY environment variables."""
         self._ignore_local_proxy = True
 
 
@@ -396,7 +395,8 @@ def __init__(self) -> None:
 
     @property
     def arguments(self):
-        """
+        """Get a list of arguments needed for the browser.
+
         Returns:
             A list of arguments needed for the browser.
         """
@@ -414,8 +414,9 @@ def add_argument(self, argument: str) -> None:
             raise ValueError("argument can not be null")
 
     def ignore_local_proxy_environment_variables(self) -> None:
-        """By calling this you will ignore HTTP_PROXY and HTTPS_PROXY from
-        being picked up and used.
+        """Ignore HTTP_PROXY and HTTPS_PROXY environment variables.
+
+        This method is deprecated; use a Proxy instance with ProxyType.DIRECT instead.
         """
         warnings.warn(
             "using ignore_local_proxy_environment_variables in Options has been deprecated, "

py/selenium/webdriver/common/print_page_options.py

@@ -335,7 +335,8 @@ def __init__(self) -> None:
         self._margin: _MarginOpts = {}
 
     def to_dict(self) -> _PrintOpts:
-        """
+        """Get a dictionary of the configured print options.
+
         Returns:
             A hash of print options configured.
         """

py/selenium/webdriver/common/proxy.py

@@ -80,9 +80,7 @@ def __set__(self, obj, value):
 
 
 class Proxy:
-    """Proxy contains information about proxy type and necessary proxy
-    settings.
-    """
+    """Proxy configuration containing proxy type and necessary proxy settings."""
 
     proxyType = ProxyType.UNSPECIFIED
     autodetect = False

py/selenium/webdriver/common/service.py

@@ -37,8 +37,9 @@
 
 
 class Service(ABC):
-    """The abstract base class for all service objects.  Services typically
-    launch a child program in a new process as an interim process to
+    """Abstract base class for all service objects that manage driver processes.
+
+    Services typically launch a child program in a new process as an interim process to
     communicate with a browser.
 
     Args:
@@ -123,15 +124,15 @@ def assert_process_still_running(self) -> None:
             raise WebDriverException(f"Service {self._path} unexpectedly exited. Status code was: {return_code}")
 
     def is_connectable(self) -> bool:
-        """Establishes a socket connection to determine if the service running
-        on the port is accessible.
+        """Establish a socket connection to determine if the service is accessible.
+
+        Returns:
+            True if the service is connectable on the configured port, False otherwise.
         """
         return utils.is_connectable(self.port)
 
     def send_remote_shutdown_command(self) -> None:
-        """Dispatch an HTTP request to the shutdown endpoint for the service in
-        an attempt to stop it.
-        """
+        """Dispatch an HTTP request to the shutdown endpoint to stop the service."""
         try:
             request.urlopen(f"{self.service_url}/shutdown")
         except URLError:

py/selenium/webdriver/common/utils.py

@@ -138,8 +138,7 @@ def is_url_connectable(
     host: Optional[str] = "127.0.0.1",
     scheme: Optional[str] = "http",
 ) -> bool:
-    """Sends a request to the HTTP server at the /status endpoint to see if it
-    responds successfully.
+    """Send a request to the HTTP server at the /status endpoint to verify connectivity.
 
     Args:
         port: port number