osn-selenium 0.0.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

osn_selenium/webdrivers/Blink/protocols.py

@@ -1,330 +0,0 @@
-import pathlib
-from selenium import webdriver
-from osn_selenium.types import WindowRect
-from osn_selenium.webdrivers.types import _any_flags_mapping
-from typing import (
-	Optional,
-	Protocol,
-	TYPE_CHECKING,
-	Union,
-	runtime_checkable
-)
-from osn_selenium.webdrivers.BaseDriver.protocols import (
-	TrioWebDriverWrapperProtocol
-)
-
-
-if TYPE_CHECKING:
-	from osn_selenium.webdrivers.Blink.webdriver import BlinkWebDriver
-	from osn_selenium.webdrivers.Blink.flags import BlinkFlagsManager, BlinkFlags
-
-
-@runtime_checkable
-class TrioBlinkWebDriverWrapperProtocol(TrioWebDriverWrapperProtocol, Protocol):
-	"""
-	Wraps BlinkWebDriver methods for asynchronous execution using Trio.
-
-	This class acts as a proxy to a `BrowserWebDriver` instance. It intercepts
-	method calls and executes them in a separate thread using `trio.to_thread.run_sync`,
-	allowing synchronous WebDriver operations to be called from asynchronous Trio code
-	without blocking the event loop. Properties and non-callable attributes are accessed directly.
-
-	Attributes:
-		_webdriver (BrowserWebDriver): The underlying synchronous BrowserWebDriver instance.
-		_excluding_functions (list[str]): A list of attribute names on the wrapped object
-											  that should *not* be accessible through this wrapper,
-											  typically because they are irrelevant or dangerous
-											  in an async context handled by the wrapper.
-	"""
-	
-	_webdriver: "BlinkWebDriver"
-	_webdriver_flags_manager: "BlinkFlagsManager"
-	_driver: Optional[Union[webdriver.Chrome, webdriver.Edge]]
-	
-	async def _check_browser_exe_active(self) -> bool:
-		"""
-		Checks if the WebDriver is active by verifying if the debugging port is in use.
-
-		Determines if a WebDriver instance is currently running and active by checking if the configured
-		debugging port is in use by any process. This is a way to verify if a browser session is active
-		without directly querying the WebDriver itself.
-
-		Returns:
-			bool: True if the WebDriver is active (debugging port is in use), False otherwise.
-		"""
-		
-		...
-	
-	async def _find_debugging_port(self, debugging_port: Optional[int]) -> int:
-		"""
-		Finds an appropriate debugging port, either reusing a previous session's port or finding a free port.
-
-		Attempts to locate a suitable debugging port for the browser. It first tries to reuse a debugging port
-		from a previous browser session if a profile directory is specified and a previous session is found.
-		If no previous session is found or if no profile directory is specified, it attempts to use the provided
-		`debugging_port` if available, or finds a minimum free port if no port is provided or the provided port is in use.
-
-		Args:
-			debugging_port (Optional[int]): Requested debugging port number. If provided, the method attempts to use this port. Defaults to None.
-
-		Returns:
-			int: The debugging port number to use. This is either a reused port from a previous session, the provided port if available, or a newly found free port.
-		"""
-		
-		...
-	
-	async def _set_debugging_port(self, debugging_port: Optional[int], debugging_address: Optional[str]):
-		"""
-		Sets the debugging port and address.
-
-		Configures the browser to start with a specific debugging port. This port is used for external tools,
-		like debuggers or browser automation frameworks, to connect to and control the browser instance.
-		Setting a fixed debugging port can be useful for consistent remote debugging or automation setups.
-
-		Args:
-			debugging_port (Optional[int]): Debugging port number. If None or 0, the browser chooses a port automatically.
-			debugging_address (Optional[str]): The IP address for the debugger to listen on. Defaults to '127.0.0.1'.
-		"""
-		
-		...
-	
-	@property
-	def browser_exe(self) -> Optional[Union[str, pathlib.Path]]:
-		"""
-		Gets the path to the browser executable.
-
-		Returns:
-			Optional[Union[str, pathlib.Path]]: The path to the browser executable.
-		"""
-		
-		...
-	
-	async def close_webdriver(self):
-		"""
-		Closes the WebDriver instance and terminates the associated browser subprocess.
-
-		Quits the current WebDriver session, closes all browser windows, and then forcefully terminates
-		the browser process. This ensures a clean shutdown of the browser and WebDriver environment.
-		"""
-		
-		...
-	
-	@property
-	def debugging_ip(self) -> Optional[str]:
-		"""
-		Gets the IP address part of the debugger address.
-
-		Returns:
-			Optional[str]: The IP address of the debugger, or None if not set.
-		"""
-		
-		...
-	
-	@property
-	def debugging_port(self) -> Optional[int]:
-		"""
-		Gets the currently set debugging port.
-
-		Retrieves the debugging port number that the browser instance is configured to use.
-
-		Returns:
-			Optional[int]: The debugging port number, or None if not set.
-		"""
-		
-		...
-	
-	@property
-	def driver(self) -> Optional[Union[webdriver.Chrome, webdriver.Edge]]:
-		"""
-		Gets the underlying Selenium WebDriver instance associated with this object.
-
-		This property provides direct access to the WebDriver object (e.g., Chrome, Edge)
-		that is being controlled, allowing for direct Selenium operations if needed.
-
-		Returns:
-			Optional[Union[webdriver.Chrome, webdriver.Edge]]:
-				The active WebDriver instance, or None if no driver is currently set or active.
-		"""
-		
-		...
-	
-	def reset_settings(
-			self,
-			flags: Optional[Union["BlinkFlags", _any_flags_mapping]] = None,
-			browser_exe: Optional[Union[str, pathlib.Path]] = None,
-			browser_name_in_system: Optional[str] = None,
-			use_browser_exe: Optional[bool] = None,
-			start_page_url: str = "",
-			window_rect: Optional[WindowRect] = None,
-			trio_tokens_limit: Union[int, float] = 40,
-	):
-		"""
-		Resets various configurable browser settings to their specified or default values.
-
-		This method allows for reconfiguring the WebDriver's operational parameters,
-		such as browser flags, executable path, start URL, window dimensions, and
-		concurrency limits. It is crucial that the browser session is *not* active
-		when this method is called; otherwise, a warning will be issued, and no changes
-		will be applied.
-
-		Args:
-			flags (Optional[Union[BlinkFlags, Mapping[str, Any]]]): New browser flags to apply.
-				If provided, existing flags are cleared and replaced with these.
-				If `None`, all custom flags are cleared, and the browser will start with default flags.
-			browser_exe (Optional[Union[str, pathlib.Path]]): The explicit path to the browser executable.
-				If provided, this path will be used. If `None`, the executable path managed by the
-				flags manager will be cleared, and then potentially re-detected based on
-				`use_browser_exe` and `browser_name_in_system`.
-			browser_name_in_system (Optional[str]): The common name of the browser (e.g., "Chrome", "Edge").
-				Used in conjunction with `use_browser_exe` to automatically detect the browser executable path.
-				This parameter only takes effect if `use_browser_exe` is explicitly `True` or `False`.
-				If `None`, no automatic detection based on name will occur through this method call.
-			use_browser_exe (Optional[bool]): Controls the automatic detection of the browser executable.
-				If `True` (and `browser_name_in_system` is provided), the browser executable path
-				will be automatically detected if `browser_exe` is `None`.
-				If `False` (and `browser_name_in_system` is provided), any existing `browser_exe`
-				path in the flags manager will be cleared.
-				If `None`, the current `use_browser_exe` state is maintained for the `_detect_browser_exe` logic.
-			start_page_url (str): The URL that the browser will attempt to navigate to
-				immediately after starting. Defaults to an empty string.
-			window_rect (Optional[WindowRect]): The initial window size and position settings.
-				If `None`, it defaults to a new `WindowRect()` instance, effectively resetting
-				to the browser's default window behavior.
-			trio_tokens_limit (Union[int, float]): The maximum number of concurrent synchronous
-				WebDriver operations allowed by the Trio capacity limiter. Defaults to 40.
-		"""
-		
-		...
-	
-	def restart_webdriver(
-			self,
-			flags: Optional[Union["BlinkFlags", _any_flags_mapping]] = None,
-			browser_exe: Optional[Union[str, pathlib.Path]] = None,
-			browser_name_in_system: Optional[str] = None,
-			use_browser_exe: Optional[bool] = None,
-			start_page_url: Optional[str] = None,
-			window_rect: Optional[WindowRect] = None,
-			trio_tokens_limit: Optional[Union[int, float]] = None,
-	):
-		"""
-		Restarts the WebDriver and browser session gracefully.
-
-		Performs a clean restart by first closing the existing WebDriver session and browser
-		(using `close_webdriver`), and then initiating a new session (using `start_webdriver`)
-		with potentially updated settings. If settings arguments are provided, they override
-		the existing settings for the new session; otherwise, the current settings are used.
-
-		Args:
-			flags (Optional[Union[BlinkFlags, Mapping[str, Any]]]): Override flags for the new session.
-				If provided, these flags will be applied. If `None`, current settings are used.
-			browser_exe (Optional[Union[str, pathlib.Path]]): Override browser executable for the new session.
-				If provided, this path will be used. If `None`, current settings are used.
-			browser_name_in_system (Optional[str]): Override browser name for auto-detection for the new session.
-				Only takes effect if `use_browser_exe` is also provided. If `None`, current settings are used.
-			use_browser_exe (Optional[bool]): Override auto-detection behavior for the new session.
-				If provided, this boolean determines if the browser executable is auto-detected.
-				If `None`, current settings are used.
-			start_page_url (Optional[str]): Override start page URL for the new session.
-				If provided, this URL will be used. If `None`, current setting is used.
-			window_rect (Optional[WindowRect]): Override window rectangle for the new session.
-				If provided, these dimensions will be used. If `None`, current settings are used.
-			trio_tokens_limit (Optional[Union[int, float]]): Override Trio token limit for the new session.
-				If provided, this limit will be used. If `None`, current setting is used.
-		"""
-		
-		...
-	
-	async def set_start_page_url(self, start_page_url: str):
-		"""
-		Sets the URL that the browser will open upon starting.
-
-		Args:
-			start_page_url (str): The URL to set as the start page.
-		"""
-		
-		...
-	
-	def start_webdriver(
-			self,
-			flags: Optional[Union["BlinkFlags", _any_flags_mapping]] = None,
-			browser_exe: Optional[Union[str, pathlib.Path]] = None,
-			browser_name_in_system: Optional[str] = None,
-			use_browser_exe: Optional[bool] = None,
-			start_page_url: Optional[str] = None,
-			window_rect: Optional[WindowRect] = None,
-			trio_tokens_limit: Optional[Union[int, float]] = None,
-	):
-		"""
-		Starts the WebDriver service and the browser session.
-
-		Initializes and starts the WebDriver instance and the associated browser process.
-		It first updates settings based on provided parameters (if the driver is not already running),
-		checks if a browser process needs to be started, starts it if necessary using Popen,
-		waits for it to become active, and then creates the WebDriver client instance (`self.driver`).
-
-		Args:
-			flags (Optional[Union[BlinkFlags, Mapping[str, Any]]]): Override flags for this start.
-				If provided, these flags will be applied. If `None`, current settings are used.
-			browser_exe (Optional[Union[str, pathlib.Path]]): Override browser executable path for this start.
-				If provided, this path will be used. If `None`, current settings are used.
-			browser_name_in_system (Optional[str]): Override browser name for auto-detection for this start.
-				Only takes effect if `use_browser_exe` is also provided. If `None`, current settings are used.
-			use_browser_exe (Optional[bool]): Override auto-detection behavior for this start.
-				If provided, this boolean determines if the browser executable is auto-detected.
-				If `None`, current settings are used.
-			start_page_url (Optional[str]): Override start page URL for this start.
-				If provided, this URL will be used. If `None`, current setting is used.
-			window_rect (Optional[WindowRect]): Override window rectangle for this start.
-				If provided, these dimensions will be used. If `None`, current settings are used.
-			trio_tokens_limit (Optional[Union[int, float]]): Override Trio token limit for this start.
-				If provided, this limit will be used. If `None`, current setting is used.
-		"""
-		
-		...
-	
-	def update_settings(
-			self,
-			flags: Optional[Union["BlinkFlags", _any_flags_mapping]] = None,
-			browser_exe: Optional[Union[str, pathlib.Path]] = None,
-			browser_name_in_system: Optional[str] = None,
-			use_browser_exe: Optional[bool] = None,
-			start_page_url: Optional[str] = None,
-			window_rect: Optional[WindowRect] = None,
-			trio_tokens_limit: Optional[Union[int, float]] = None,
-	):
-		"""
-		Updates various browser settings selectively without resetting others.
-
-		This method allows for dynamic updating of browser settings. Only the settings
-		for which a non-None value is provided will be updated. Settings passed as `None`
-		will retain their current values. This method can be called whether the browser
-		is active or not, but some changes might only take effect after the browser is
-		restarted.
-
-		Args:
-			flags (Optional[Union[BlinkFlags, Mapping[str, Any]]]): New browser flags to update.
-				If provided, these flags will be merged with or overwrite existing flags
-				within the flags manager. If `None`, existing flags remain unchanged.
-			browser_exe (Optional[Union[str, pathlib.Path]]): The new path to the browser executable.
-				If provided, this path will be set in the flags manager. If `None`, the
-				current browser executable path remains unchanged.
-			browser_name_in_system (Optional[str]): The common name of the browser (e.g., "Chrome", "Edge").
-				Used in conjunction with `use_browser_exe` to automatically detect the browser executable path.
-				This parameter only takes effect if `use_browser_exe` is explicitly provided.
-				If `None`, no automatic detection based on name will occur through this method call.
-			use_browser_exe (Optional[bool]): Controls the automatic detection of the browser executable.
-				If `True` (and `browser_name_in_system` is provided), the browser executable path
-				will be automatically detected if `browser_exe` is `None`.
-				If `False` (and `browser_name_in_system` is provided), any existing `browser_exe`
-				path in the flags manager will be cleared.
-				If `None`, the current `use_browser_exe` state is maintained for the `_detect_browser_exe` logic.
-			start_page_url (Optional[str]): The new URL that the browser will attempt to navigate to
-				immediately after starting. If `None`, the current start page URL remains unchanged.
-			window_rect (Optional[WindowRect]): The new window size and position settings.
-				If `None`, the current window rectangle settings remain unchanged.
-			trio_tokens_limit (Optional[Union[int, float]]): The new maximum number of concurrent
-				asynchronous operations allowed by the Trio capacity limiter. If `None`, the
-				current limit remains unchanged.
-		"""
-		
-		...