diff --git a/py/selenium/webdriver/common/bidi/cdp.py b/py/selenium/webdriver/common/bidi/cdp.py index 6ab3d3b012299..175724143599d 100644 --- a/py/selenium/webdriver/common/bidi/cdp.py +++ b/py/selenium/webdriver/common/bidi/cdp.py @@ -166,8 +166,8 @@ class CdpConnectionClosed(WsConnectionClosed): def __init__(self, reason): """Constructor. - :param reason: - :type reason: wsproto.frame_protocol.CloseReason + Args: + reason: wsproto.frame_protocol.CloseReason """ self.reason = reason @@ -205,8 +205,11 @@ def __init__(self, ws, session_id, target_id): async def execute(self, cmd: Generator[dict, T, Any]) -> T: """Execute a command on the server and wait for the result. - :param cmd: any CDP command - :returns: a CDP result + Args: + cmd: any CDP command + + Returns: + a CDP result """ cmd_id = next(self.id_iter) cmd_event = trio.Event() @@ -261,18 +264,20 @@ async def wait_for(self, event_type: type[T], buffer_size=10) -> AsyncGenerator[ def _handle_data(self, data): """Handle incoming WebSocket data. - :param dict data: a JSON dictionary + Args: + data: a JSON dictionary """ if "id" in data: self._handle_cmd_response(data) else: self._handle_event(data) - def _handle_cmd_response(self, data): + def _handle_cmd_response(self, data: dict): """Handle a response to a command. This will set an event flag that will return control to the task that called the command. - :param dict data: response as a JSON dictionary + Args: + data: response as a JSON dictionary """ cmd_id = data["id"] try: @@ -295,10 +300,11 @@ def _handle_cmd_response(self, data): self.inflight_result[cmd_id] = return_ event.set() - def _handle_event(self, data): + def _handle_event(self, data: dict): """Handle an event. - :param dict data: event as a JSON dictionary + Args: + data: event as a JSON dictionary """ global devtools event = devtools.util.parse_json_event(data) @@ -325,9 +331,10 @@ class CdpSession(CdpBase): def __init__(self, ws, session_id, target_id): """Constructor. - :param trio_websocket.WebSocketConnection ws: - :param devtools.target.SessionID session_id: - :param devtools.target.TargetID target_id: + Args: + ws: trio_websocket.WebSocketConnection + session_id: devtools.target.SessionID + target_id: devtools.target.TargetID """ super().__init__(ws, session_id, target_id) @@ -394,7 +401,8 @@ class corresponds to the "root" session, i.e. the implicitly created def __init__(self, ws): """Constructor. - :param trio_websocket.WebSocketConnection ws: + Args: + ws: trio_websocket.WebSocketConnection """ super().__init__(ws, session_id=None, target_id=None) self.sessions = {} diff --git a/py/selenium/webdriver/common/bidi/script.py b/py/selenium/webdriver/common/bidi/script.py index cbf18b4f072e1..e397e0d7dfca2 100644 --- a/py/selenium/webdriver/common/bidi/script.py +++ b/py/selenium/webdriver/common/bidi/script.py @@ -60,12 +60,10 @@ class RealmInfo: def from_json(cls, json: dict[str, Any]) -> "RealmInfo": """Creates a RealmInfo instance from a dictionary. - Parameters: - ----------- + Args: json: A dictionary containing the realm information. Returns: - ------- RealmInfo: A new instance of RealmInfo. """ if "realm" not in json: @@ -95,12 +93,10 @@ class Source: def from_json(cls, json: dict[str, Any]) -> "Source": """Creates a Source instance from a dictionary. - Parameters: - ----------- + Args: json: A dictionary containing the source information. Returns: - ------- Source: A new instance of Source. """ if "realm" not in json: @@ -125,12 +121,10 @@ class EvaluateResult: def from_json(cls, json: dict[str, Any]) -> "EvaluateResult": """Creates an EvaluateResult instance from a dictionary. - Parameters: - ----------- + Args: json: A dictionary containing the evaluation result. Returns: - ------- EvaluateResult: A new instance of EvaluateResult. """ if "realm" not in json: @@ -160,12 +154,10 @@ def __init__(self, channel: str, data: dict, source: Source): def from_json(cls, json: dict[str, Any]) -> "ScriptMessage": """Creates a ScriptMessage instance from a dictionary. - Parameters: - ----------- + Args: json: A dictionary containing the script message. Returns: - ------- ScriptMessage: A new instance of ScriptMessage. """ if "channel" not in json: @@ -194,12 +186,10 @@ def __init__(self, realm_info: RealmInfo): def from_json(cls, json: dict[str, Any]) -> "RealmCreated": """Creates a RealmCreated instance from a dictionary. - Parameters: - ----------- + Args: json: A dictionary containing the realm created event. Returns: - ------- RealmCreated: A new instance of RealmCreated. """ return cls(realm_info=RealmInfo.from_json(json)) @@ -217,12 +207,10 @@ def __init__(self, realm: str): def from_json(cls, json: dict[str, Any]) -> "RealmDestroyed": """Creates a RealmDestroyed instance from a dictionary. - Parameters: - ----------- + Args: json: A dictionary containing the realm destroyed event. Returns: - ------- RealmDestroyed: A new instance of RealmDestroyed. """ if "realm" not in json: @@ -266,12 +254,10 @@ def remove_console_message_handler(self, id): def pin(self, script: str) -> str: """Pins a script to the current browsing context. - Parameters: - ----------- + Args: script: The script to pin. Returns: - ------- str: The ID of the pinned script. """ return self._add_preload_script(script) @@ -279,8 +265,7 @@ def pin(self, script: str) -> str: def unpin(self, script_id: str) -> None: """Unpins a script from the current browsing context. - Parameters: - ----------- + Args: script_id: The ID of the pinned script to unpin. """ self._remove_preload_script(script_id) @@ -288,17 +273,14 @@ def unpin(self, script_id: str) -> None: def execute(self, script: str, *args) -> dict: """Executes a script in the current browsing context. - Parameters: - ----------- + Args: script: The script function to execute. *args: Arguments to pass to the script function. Returns: - ------- dict: The result value from the script execution. Raises: - ------ WebDriverException: If the script execution fails. """ @@ -390,8 +372,7 @@ def _add_preload_script( ) -> str: """Adds a preload script. - Parameters: - ----------- + Args: function_declaration: The function declaration to preload. arguments: The arguments to pass to the function. contexts: The browsing context IDs to apply the script to. @@ -399,11 +380,9 @@ def _add_preload_script( sandbox: The sandbox name to apply the script to. Returns: - ------- str: The preload script ID. Raises: - ------ ValueError: If both contexts and user_contexts are provided. """ if contexts is not None and user_contexts is not None: @@ -426,8 +405,7 @@ def _add_preload_script( def _remove_preload_script(self, script_id: str) -> None: """Removes a preload script. - Parameters: - ----------- + Args: script_id: The preload script ID to remove. """ params = {"script": script_id} @@ -436,8 +414,7 @@ def _remove_preload_script(self, script_id: str) -> None: def _disown(self, handles: list[str], target: dict) -> None: """Disowns the given handles. - Parameters: - ----------- + Args: handles: The handles to disown. target: The target realm or context. """ @@ -460,8 +437,7 @@ def _call_function( ) -> EvaluateResult: """Calls a provided function with given arguments in a given realm. - Parameters: - ----------- + Args: function_declaration: The function declaration to call. await_promise: Whether to await promise resolution. target: The target realm or context. @@ -472,7 +448,6 @@ def _call_function( user_activation: Whether to trigger user activation. Returns: - ------- EvaluateResult: The result of the function call. """ params = { @@ -505,8 +480,7 @@ def _evaluate( ) -> EvaluateResult: """Evaluates a provided script in a given realm. - Parameters: - ----------- + Args: expression: The script expression to evaluate. target: The target realm or context. await_promise: Whether to await promise resolution. @@ -515,7 +489,6 @@ def _evaluate( user_activation: Whether to trigger user activation. Returns: - ------- EvaluateResult: The result of the script evaluation. """ params = { @@ -540,13 +513,11 @@ def _get_realms( ) -> list[RealmInfo]: """Returns a list of all realms, optionally filtered. - Parameters: - ----------- + Args: context: The browsing context ID to filter by. type: The realm type to filter by. Returns: - ------- List[RealmInfo]: A list of realm information. """ params = {} diff --git a/py/selenium/webdriver/common/driver_finder.py b/py/selenium/webdriver/common/driver_finder.py index 2c8aeb365706c..14d2421c3258a 100644 --- a/py/selenium/webdriver/common/driver_finder.py +++ b/py/selenium/webdriver/common/driver_finder.py @@ -29,8 +29,9 @@ class DriverFinder: """A Driver finding class responsible for obtaining the correct driver and associated browser. - :param service: instance of the driver service class. - :param options: instance of the browser options class. + Args: + service: instance of the driver service class. + options: instance of the browser options class. """ def __init__(self, service: Service, options: BaseOptions) -> None: diff --git a/py/selenium/webdriver/common/options.py b/py/selenium/webdriver/common/options.py index fc76c6fd832fc..98247c3047222 100644 --- a/py/selenium/webdriver/common/options.py +++ b/py/selenium/webdriver/common/options.py @@ -68,7 +68,8 @@ class _PageLoadStrategyDescriptor: """Determines the point at which a navigation command is returned: https://w3c.github.io/webdriver/#dfn-table-of-page-load-strategies. - :param strategy: the strategy corresponding to a document readiness state + Args: + strategy: the strategy corresponding to a document readiness state """ def __init__(self, name): @@ -89,9 +90,11 @@ class _UnHandledPromptBehaviorDescriptor: command sent is not handling the alert: https://w3c.github.io/webdriver/#dfn-table-of-page-load-strategies: - :param behavior: behavior to use when an alert is encountered + Args: + behavior: behavior to use when an alert is encountered - :returns: Values for implicit timeout, pageLoad timeout and script timeout if set (in milliseconds) + Returns: + Values for implicit timeout, pageLoad timeout and script timeout if set (in milliseconds) """ def __init__(self, name): @@ -114,9 +117,11 @@ class _TimeoutsDescriptor: """How long the driver should wait for actions to complete before: returning an error https://w3c.github.io/webdriver/#timeouts: - :param timeouts: values in milliseconds for implicit wait, page load and script timeout + Args: + timeouts: values in milliseconds for implicit wait, page load and script timeout - :returns: Values for implicit timeout, pageLoad timeout and script timeout if set (in milliseconds) + Returns: + Values for implicit timeout, pageLoad timeout and script timeout if set (in milliseconds) """ def __init__(self, name): @@ -133,7 +138,10 @@ def __set__(self, obj, value): class _ProxyDescriptor: - """:Returns: Proxy if set, otherwise None.""" + """ + Returns: + Proxy if set, otherwise None. + """ def __init__(self, name): self.name = name @@ -441,8 +449,10 @@ def enable_mobile( ) -> None: """Enables mobile browser use for browsers that support it. - :Args: - android_activity: The name of the android package to start + Args: + android_package: The name of the android package to start + android_activity: The name of the android activity + device_serial: The device serial number """ if not android_package: raise AttributeError("android_package must be passed in") @@ -478,14 +488,17 @@ def __init__(self) -> None: @property def arguments(self): - """:Returns: A list of arguments needed for the browser.""" + """ + Returns: + A list of arguments needed for the browser. + """ return self._arguments def add_argument(self, argument: str) -> None: """Adds an argument to the list. - :Args: - - Sets the arguments + Args: + argument: Sets the arguments """ if argument: self._arguments.append(argument) diff --git a/py/selenium/webdriver/common/service.py b/py/selenium/webdriver/common/service.py index d8e7ac018df87..87773177dbaeb 100644 --- a/py/selenium/webdriver/common/service.py +++ b/py/selenium/webdriver/common/service.py @@ -41,11 +41,12 @@ class Service(ABC): launch a child program in a new process as an interim process to communicate with a browser. - :param executable: install path of the executable. - :param port: Port for the service to run on, defaults to 0 where the operating system will decide. - :param log_output: (Optional) int representation of STDOUT/DEVNULL, any IO instance or String path to file. - :param env: (Optional) Mapping of environment variables for the new process, defaults to `os.environ`. - :param driver_path_env_key: (Optional) Environment variable to use to get the path to the driver executable. + Args: + executable: install path of the executable. + port: 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. """ def __init__( @@ -96,9 +97,9 @@ def path(self, value: str) -> None: def start(self) -> None: """Starts the Service. - :Exceptions: - - WebDriverException : Raised either when it can't start the service - or when it can't connect to the service + Raises: + WebDriverException: Raised either when it can't start the service + or when it can't connect to the service """ if self._path is None: raise WebDriverException("Service path cannot be None.") @@ -201,7 +202,8 @@ def __del__(self) -> None: def _start_process(self, path: str) -> None: """Creates a subprocess by executing the command provided. - :param cmd: full command to execute + Args: + path: full command to execute """ cmd = [path] cmd.extend(self.command_line_args()) diff --git a/py/selenium/webdriver/firefox/firefox_profile.py b/py/selenium/webdriver/firefox/firefox_profile.py index 41bb9a4ba91f5..bc783cd48c827 100644 --- a/py/selenium/webdriver/firefox/firefox_profile.py +++ b/py/selenium/webdriver/firefox/firefox_profile.py @@ -46,12 +46,12 @@ class FirefoxProfile: def __init__(self, profile_directory=None): """Initialises a new instance of a Firefox Profile. - :args: - - profile_directory: Directory of profile that you want to use. If a - directory is passed in it will be cloned and the cloned directory - will be used by the driver when instantiated. - This defaults to None and will create a new - directory when object is created. + Args: + profile_directory: Directory of profile that you want to use. If a + directory is passed in it will be cloned and the cloned directory + will be used by the driver when instantiated. + This defaults to None and will create a new + directory when object is created. """ self._desired_preferences = {} if profile_directory: @@ -179,8 +179,9 @@ def _install_extension(self, addon, unpack=True): """Installs addon from a filepath, url or directory of addons in the profile. - - path: url, absolute path to .xpi, or directory of addons - - unpack: whether to unpack unless specified otherwise in the install.rdf + Args: + addon: url, absolute path to .xpi, or directory of addons + unpack: whether to unpack unless specified otherwise in the install.rdf """ tmpdir = None xpifile = None @@ -225,9 +226,11 @@ def _install_extension(self, addon, unpack=True): def _addon_details(self, addon_path): """Returns a dictionary of details about the addon. - :param addon_path: path to the add-on directory or XPI + Args: + addon_path: path to the add-on directory or XPI - Returns:: + Returns: + A dictionary containing: { "id": "rainbow@colors.org", # id of the addon diff --git a/py/selenium/webdriver/firefox/service.py b/py/selenium/webdriver/firefox/service.py index ce5eb96e60d60..00848c5378d5d 100644 --- a/py/selenium/webdriver/firefox/service.py +++ b/py/selenium/webdriver/firefox/service.py @@ -26,12 +26,13 @@ class Service(service.Service): """A Service class that is responsible for the starting and stopping of `geckodriver`. - :param executable_path: install path of the geckodriver executable, defaults to `geckodriver`. - :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_output: (Optional) int representation of STDOUT/DEVNULL, any IO instance or String path to file. - :param env: (Optional) Mapping of environment variables for the new process, defaults to `os.environ`. - :param driver_path_env_key: (Optional) Environment variable to use to get the path to the driver executable. + 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. + 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__( diff --git a/py/selenium/webdriver/remote/remote_connection.py b/py/selenium/webdriver/remote/remote_connection.py index 7905209fe17a7..56d36c567656a 100644 --- a/py/selenium/webdriver/remote/remote_connection.py +++ b/py/selenium/webdriver/remote/remote_connection.py @@ -169,10 +169,11 @@ def client_config(self): @classmethod def get_timeout(cls): - """:Returns: + """Returns timeout value in seconds for all http requests made to the Remote Connection. - Timeout value in seconds for all http requests made to the - Remote Connection + Returns: + Timeout value in seconds for all http requests made to the + Remote Connection """ warnings.warn( "get_timeout() in RemoteConnection is deprecated, get timeout from client_config instead", @@ -185,8 +186,8 @@ def get_timeout(cls): def set_timeout(cls, timeout): """Override the default timeout. - :Args: - - timeout - timeout value for http requests in seconds + Args: + timeout: timeout value for http requests in seconds """ warnings.warn( "set_timeout() in RemoteConnection is deprecated, set timeout in client_config instead", @@ -207,11 +208,12 @@ def reset_timeout(cls): @classmethod def get_certificate_bundle_path(cls): - """:Returns: + """Returns paths of the .pem encoded certificate to verify connection to command executor. - Paths of the .pem encoded certificate to verify connection to - command executor. Defaults to certifi.where() or - REQUESTS_CA_BUNDLE env variable if set. + Returns: + Paths of the .pem encoded certificate to verify connection to + command executor. Defaults to certifi.where() or + REQUESTS_CA_BUNDLE env variable if set. """ warnings.warn( "get_certificate_bundle_path() in RemoteConnection is deprecated, get ca_certs from client_config instead", @@ -226,8 +228,8 @@ def set_certificate_bundle_path(cls, path): command executor. Can also be set to None to disable certificate validation. - :Args: - - path - path of a .pem encoded certificate chain. + Args: + path: path of a .pem encoded certificate chain. """ warnings.warn( "set_certificate_bundle_path() in RemoteConnection is deprecated, set ca_certs in client_config instead", @@ -240,9 +242,9 @@ def set_certificate_bundle_path(cls, path): def get_remote_connection_headers(cls, parsed_url, keep_alive=False): """Get headers for remote request. - :Args: - - parsed_url - The parsed url - - keep_alive (Boolean) - Is this a keep-alive connection (default: False) + Args: + parsed_url: The parsed url + keep_alive: Is this a keep-alive connection (default: False) """ headers = { @@ -385,10 +387,10 @@ def execute(self, command, params): Any path substitutions required for the URL mapped to the command should be included in the command parameters. - :Args: - - command - A string specifying the command to execute. - - params - A dictionary of named parameters to send with the command as - its JSON payload. + Args: + command: A string specifying the command to execute. + params: A dictionary of named parameters to send with the command as + its JSON payload. """ command_info = self._commands.get(command) or self.extra_commands.get(command) assert command_info is not None, f"Unrecognised command {command}" @@ -404,16 +406,16 @@ def execute(self, command, params): LOGGER.debug("%s %s %s", command_info[0], url, str(trimmed)) return self._request(command_info[0], url, body=data) - def _request(self, method, url, body=None): + def _request(self, method, url, body=None) -> dict: """Send an HTTP request to the remote server. - :Args: - - method - A string for the HTTP method to send the request with. - - url - A string for the URL to send the request to. - - body - A string for request body. Ignored unless method is POST or PUT. + Args: + method: A string for the HTTP method to send the request with. + url: A string for the URL to send the request to. + body: A string for request body. Ignored unless method is POST or PUT. - :Returns: - A dictionary with the server's parsed JSON response. + Returns: + A dictionary with the server's parsed JSON response. """ parsed_url = parse.urlparse(url) headers = self.get_remote_connection_headers(parsed_url, self._client_config.keep_alive) @@ -471,12 +473,15 @@ def close(self): if hasattr(self, "_conn"): self._conn.clear() - def _trim_large_entries(self, input_dict, max_length=100): + def _trim_large_entries(self, input_dict, max_length=100) -> dict: """Truncate string values in a dictionary if they exceed max_length. - :param dict: Dictionary with potentially large values - :param max_length: Maximum allowed length of string values - :return: Dictionary with truncated string values + Args: + input_dict: Dictionary with potentially large values + max_length: Maximum allowed length of string values + + Returns: + Dictionary with truncated string values """ output_dictionary = {} for key, value in input_dict.items(): diff --git a/py/selenium/webdriver/safari/service.py b/py/selenium/webdriver/safari/service.py index eeb6a57948cf3..3e8062616a780 100644 --- a/py/selenium/webdriver/safari/service.py +++ b/py/selenium/webdriver/safari/service.py @@ -25,13 +25,14 @@ class Service(service.Service): """A Service class that is responsible for the starting and stopping of `safaridriver` This is only supported on MAC OSX. - :param executable_path: install path of the safaridriver executable, defaults to `/usr/bin/safaridriver`. - :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 env: (Optional) Mapping of environment variables for the new process, defaults to `os.environ`. - :param enable_logging: (Optional) Enable logging of the service. Logs can be located at - `~/Library/Logs/com.apple.WebDriver/` - :param driver_path_env_key: (Optional) Environment variable to use to get the path to the driver executable. + Args: + executable_path: install path of the safaridriver executable, defaults to `/usr/bin/safaridriver`. + 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. + env: (Optional) Mapping of environment variables for the new process, defaults to `os.environ`. + enable_logging: (Optional) Enable logging of the service. Logs can be located at + `~/Library/Logs/com.apple.WebDriver/` + driver_path_env_key: (Optional) Environment variable to use to get the path to the driver executable. """ def __init__(