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

osn_selenium/abstract/webdriver/blink/__init__.py

@@ -0,0 +1,18 @@
+from abc import ABC
+from osn_selenium.abstract.webdriver.core import (
+	AbstractCoreWebDriver as AbstractBaseWebDriver
+)
+
+
+__all__ = ["AbstractBlinkWebDriver"]
+
+
+class AbstractBlinkWebDriver(AbstractBaseWebDriver, ABC):
+	"""
+	Abstract base class for Blink-based WebDrivers.
+
+	Combines the standard WebDriver interface with Blink-specific functionality,
+	specifically access to the Chrome DevTools Protocol (CDP).
+	"""
+	
+	pass

osn_selenium/abstract/webdriver/blink/base.py

@@ -0,0 +1,80 @@
+from abc import abstractmethod
+from selenium import webdriver
+from typing import Optional, Union
+from osn_selenium._typehints import PATH_TYPEHINT
+from osn_selenium.abstract.webdriver.core.base import (
+	AbstractCoreBaseMixin
+)
+
+
+__all__ = ["AbstractBlinkBaseMixin"]
+
+
+class AbstractBlinkBaseMixin(AbstractCoreBaseMixin):
+	"""
+	Abstract mixin defining the base interface for Blink-based WebDrivers (Chrome, Edge).
+
+	This mixin establishes the contract for managing the browser executable path,
+	debugging connection details, and the underlying Selenium driver instance.
+	"""
+	
+	@property
+	@abstractmethod
+	def browser_exe(self) -> Optional[PATH_TYPEHINT]:
+		"""
+		Returns the file path to the browser executable.
+
+		Returns:
+			Optional[PATH_TYPEHINT]: The path to the executable,
+			or None if not managed by this instance.
+		"""
+		
+		...
+	
+	@property
+	@abstractmethod
+	def debugging_ip(self) -> Optional[str]:
+		"""
+		Returns the IP address used for the remote debugging protocol.
+
+		Returns:
+			Optional[str]: The debugging IP address (e.g., "127.0.0.1"), or None if not set.
+		"""
+		
+		...
+	
+	@property
+	@abstractmethod
+	def debugging_port(self) -> Optional[int]:
+		"""
+		Returns the port number used for the remote debugging protocol.
+
+		Returns:
+			Optional[int]: The debugging port, or None if not set.
+		"""
+		
+		...
+	
+	@property
+	@abstractmethod
+	def driver(self) -> Optional[Union[webdriver.Chrome, webdriver.Edge]]:
+		"""
+		Returns the underlying Selenium WebDriver instance.
+
+		Returns:
+			Optional[Union[webdriver.Chrome, webdriver.Edge]]: The driver instance,
+			or None if not started.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def set_start_page_url(self, start_page_url: str) -> None:
+		"""
+		Sets the URL that the browser should navigate to upon startup.
+
+		Args:
+			start_page_url (str): The URL to set as the start page.
+		"""
+		
+		...

osn_selenium/abstract/webdriver/blink/casting.py

@@ -0,0 +1,82 @@
+from typing import Any, Dict, List
+from abc import ABC, abstractmethod
+
+
+__all__ = ["AbstractBlinkCastingMixin"]
+
+
+class AbstractBlinkCastingMixin(ABC):
+	"""
+	Abstract mixin defining the interface for casting/mirroring functionality
+	in Blink-based browsers.
+
+	Provides methods to discover sinks (receivers) and control tab or desktop mirroring sessions.
+	"""
+	
+	@abstractmethod
+	def get_sinks(self) -> List[Dict[str, Any]]:
+		"""
+		Retrieves a list of available casting sinks (receivers).
+
+		Returns:
+			List[Dict[str, Any]]: A list of dictionaries, where each dictionary represents
+			a discovered sink and its properties.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def set_sink_to_use(self, sink_name: str) -> Dict[str, Any]:
+		"""
+		Selects a specific sink to be used for future casting operations.
+
+		Args:
+			sink_name (str): The name of the sink to select.
+
+		Returns:
+			Dict[str, Any]: A dictionary containing the command response or status.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def start_desktop_mirroring(self, sink_name: str) -> Dict[str, Any]:
+		"""
+		Starts mirroring the entire desktop to the specified sink.
+
+		Args:
+			sink_name (str): The name of the sink to cast the desktop to.
+
+		Returns:
+			Dict[str, Any]: A dictionary containing the command response or status.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def start_tab_mirroring(self, sink_name: str) -> Dict[str, Any]:
+		"""
+		Starts mirroring the current browser tab to the specified sink.
+
+		Args:
+			sink_name (str): The name of the sink to cast the tab to.
+
+		Returns:
+			Dict[str, Any]: A dictionary containing the command response or status.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def stop_casting(self, sink_name: str) -> Dict[str, Any]:
+		"""
+		Stops the active casting session on the specified sink.
+
+		Args:
+			sink_name (str): The name of the sink (receiver) to stop casting to.
+
+		Returns:
+			Dict[str, Any]: A dictionary containing the command response or status.
+		"""
+		
+		...

osn_selenium/abstract/webdriver/blink/features.py

@@ -0,0 +1,51 @@
+from typing import Any, Dict
+from abc import ABC, abstractmethod
+
+
+__all__ = ["AbstractBlinkFeaturesMixin"]
+
+
+class AbstractBlinkFeaturesMixin(ABC):
+	"""
+	Abstract mixin defining the interface for specific Blink browser features.
+
+	Includes functionality for handling permissions, launching apps, and retrieving
+	browser issue messages.
+	"""
+	
+	@abstractmethod
+	def get_issue_message(self) -> Any:
+		"""
+		Retrieves the current issue message or status from the browser, if any.
+
+		Returns:
+			Any: The issue message object or string.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def launch_app(self, id: str) -> Dict[str, Any]:
+		"""
+		Launches an installed application within the browser by its ID.
+
+		Args:
+			id (str): The identifier of the application to launch.
+
+		Returns:
+			Dict[str, Any]: A dictionary containing the result of the launch operation.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def set_permissions(self, name: str, value: str) -> None:
+		"""
+		Sets a specific permission for the browser context.
+
+		Args:
+			name (str): The name of the permission (e.g., "camera", "microphone").
+			value (str): The value to set (e.g., "granted", "denied").
+		"""
+		
+		...

osn_selenium/abstract/webdriver/blink/lifecycle.py

@@ -0,0 +1,76 @@
+from typing import Optional
+from abc import abstractmethod
+from osn_selenium.models import WindowRect
+from osn_selenium._typehints import PATH_TYPEHINT
+from osn_selenium.flags.models.blink import BlinkFlags
+from osn_selenium.abstract.webdriver.core.lifecycle import (
+	AbstractCoreLifecycleMixin
+)
+
+
+__all__ = ["AbstractBlinkLifecycleMixin"]
+
+
+class AbstractBlinkLifecycleMixin(AbstractCoreLifecycleMixin):
+	"""
+	Abstract mixin defining the lifecycle management interface for Blink-based WebDrivers.
+
+	Handles creation, startup, shutdown, and restarting of the WebDriver instance
+	and the associated browser process.
+	"""
+	
+	@abstractmethod
+	async def close_webdriver(self) -> None:
+		"""
+		Closes the WebDriver connection and terminates the browser process.
+		"""
+		
+		...
+	
+	@abstractmethod
+	async def restart_webdriver(
+			self,
+			flags: Optional[BlinkFlags] = None,
+			browser_exe: Optional[PATH_TYPEHINT] = 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,
+	) -> None:
+		"""
+		Restarts the WebDriver and browser, applying new settings if provided.
+
+		Args:
+			flags (Optional[BlinkFlags]): Configuration flags for the new session.
+			browser_exe (Optional[PATH_TYPEHINT]): Path to the browser executable.
+			browser_name_in_system (Optional[str]): Name of the browser in the system.
+			use_browser_exe (Optional[bool]): Whether to manage the browser executable process.
+			start_page_url (Optional[str]): URL to open after restart.
+			window_rect (Optional[WindowRect]): Initial window dimensions.
+		"""
+		
+		...
+	
+	@abstractmethod
+	async def start_webdriver(
+			self,
+			flags: Optional[BlinkFlags] = None,
+			browser_exe: Optional[PATH_TYPEHINT] = 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,
+	) -> None:
+		"""
+		Starts the WebDriver and the browser instance.
+
+		Args:
+			flags (Optional[BlinkFlags]): Configuration flags for the browser.
+			browser_exe (Optional[PATH_TYPEHINT]): Path to the browser executable.
+			browser_name_in_system (Optional[str]): Name of the browser in the OS registry/system.
+			use_browser_exe (Optional[bool]): Whether to manage the browser executable process.
+			start_page_url (Optional[str]): URL to open immediately upon start.
+			window_rect (Optional[WindowRect]): Initial dimensions and position of the window.
+		"""
+		
+		...

osn_selenium/abstract/webdriver/blink/logging.py

@@ -0,0 +1,40 @@
+from typing import Any, List
+from abc import ABC, abstractmethod
+
+
+__all__ = ["AbstractBlinkLoggingMixin"]
+
+
+class AbstractBlinkLoggingMixin(ABC):
+	"""
+	Abstract mixin defining the interface for accessing browser logs.
+
+	Allows retrieving specific log types (e.g., browser, performance, client) supported
+	by the Blink-based browser.
+	"""
+	
+	@abstractmethod
+	def get_log(self, log_type: str) -> Any:
+		"""
+		Retrieves the logs for a specific log type.
+
+		Args:
+			log_type (str): The type of log to retrieve (must be one of the available log types).
+
+		Returns:
+			Any: The log entries, typically a list of dictionaries containing log messages.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def log_types(self) -> List[str]:
+		"""
+		Retrieves the list of available log types.
+
+		Returns:
+			List[str]: A list of strings representing the available log types
+			(e.g., ['browser', 'driver', 'client', 'performance']).
+		"""
+		
+		...

osn_selenium/abstract/webdriver/blink/network.py

@@ -0,0 +1,45 @@
+from typing import Any, Dict
+from abc import ABC, abstractmethod
+
+
+__all__ = ["AbstractBlinkNetworkMixin"]
+
+
+class AbstractBlinkNetworkMixin(ABC):
+	"""
+	Abstract mixin defining the interface for network emulation and condition management.
+
+	Provides methods to simulate network conditions such as latency, throughput, and
+	offline status in a Blink-based browser.
+	"""
+	
+	@abstractmethod
+	def delete_network_conditions(self) -> None:
+		"""
+		Resets the network conditions to the default state (no emulation/throttling).
+		"""
+		
+		...
+	
+	@abstractmethod
+	def get_network_conditions(self) -> Dict[str, Any]:
+		"""
+		Retrieves the currently active network emulation conditions.
+
+		Returns:
+			Dict[str, Any]: A dictionary containing the current network settings.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def set_network_conditions(self, **network_conditions: Dict[str, Any]) -> None:
+		"""
+		Sets the network emulation conditions.
+
+		Args:
+			**network_conditions (Dict[str, Any]): Key-value pairs defining the network conditions
+				(e.g., offline status, latency, download_throughput, upload_throughput).
+		"""
+		
+		...

osn_selenium/abstract/webdriver/blink/settings.py

@@ -0,0 +1,68 @@
+from typing import Optional
+from abc import abstractmethod
+from osn_selenium.models import WindowRect
+from osn_selenium._typehints import PATH_TYPEHINT
+from osn_selenium.flags.models.blink import BlinkFlags
+from osn_selenium.abstract.webdriver.core.settings import (
+	AbstractCoreSettingsMixin
+)
+
+
+__all__ = ["AbstractBlinkSettingsMixin"]
+
+
+class AbstractBlinkSettingsMixin(AbstractCoreSettingsMixin):
+	"""
+	Abstract mixin defining the interface for managing browser settings and configuration.
+
+	Provides methods to update or reset the browser's runtime configuration, including
+	flags, executable paths, and window geometry.
+	"""
+	
+	@abstractmethod
+	def reset_settings(
+			self,
+			flags: Optional[BlinkFlags] = None,
+			browser_exe: Optional[PATH_TYPEHINT] = None,
+			browser_name_in_system: Optional[str] = None,
+			use_browser_exe: Optional[bool] = None,
+			start_page_url: str = "",
+			window_rect: Optional[WindowRect] = None,
+	) -> None:
+		"""
+		Resets the browser settings to their default or specified values.
+
+		Args:
+			flags (Optional[BlinkFlags]): Flags to set (overwriting previous configuration).
+			browser_exe (Optional[PATH_TYPEHINT]): Path to the browser executable.
+			browser_name_in_system (Optional[str]): System name for the browser.
+			use_browser_exe (Optional[bool]): Flag to enable/disable executable management.
+			start_page_url (str): The start page URL (defaults to empty string).
+			window_rect (Optional[WindowRect]): Window dimensions.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def update_settings(
+			self,
+			flags: Optional[BlinkFlags] = None,
+			browser_exe: Optional[PATH_TYPEHINT] = 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,
+	) -> None:
+		"""
+		Updates the browser settings without performing a full reset.
+
+		Args:
+			flags (Optional[BlinkFlags]): New flags to merge or apply.
+			browser_exe (Optional[PATH_TYPEHINT]): New path to the browser executable.
+			browser_name_in_system (Optional[str]): New system name for the browser.
+			use_browser_exe (Optional[bool]): Flag to enable/disable executable management.
+			start_page_url (Optional[str]): New start page URL.
+			window_rect (Optional[WindowRect]): New window dimensions.
+		"""
+		
+		...

osn_selenium/abstract/webdriver/chrome/__init__.py

@@ -0,0 +1,18 @@
+from abc import ABC
+from osn_selenium.abstract.webdriver.blink import (
+	AbstractBlinkWebDriver
+)
+
+
+__all__ = ["AbstractChromeWebDriver"]
+
+
+class AbstractChromeWebDriver(AbstractBlinkWebDriver, ABC):
+	"""
+	Abstract composite class representing a full Chrome WebDriver.
+
+	Combines lifecycle, settings, and base functionality for Chrome-based browsers.
+	Serves as the main entry point for abstract Chrome implementations.
+	"""
+	
+	pass

osn_selenium/abstract/webdriver/chrome/base.py

@@ -0,0 +1,36 @@
+from typing import Optional
+from abc import abstractmethod
+from selenium.webdriver.chrome.webdriver import (
+	WebDriver as legacyWebDriver
+)
+from osn_selenium.abstract.webdriver.blink.base import (
+	AbstractBlinkBaseMixin
+)
+
+
+__all__ = ["AbstractChromeBaseMixin"]
+
+
+class AbstractChromeBaseMixin(AbstractBlinkBaseMixin):
+	"""
+	Abstract mixin defining the base interface for Chrome-based WebDrivers.
+
+	This class serves as a foundational component for Chrome WebDriver implementations,
+	providing access to the underlying Selenium WebDriver instance.
+	"""
+	
+	@property
+	@abstractmethod
+	def driver(self) -> Optional[legacyWebDriver]:
+		"""
+		Gets the underlying Selenium WebDriver instance associated with this object.
+
+		This property provides direct access to the WebDriver object (e.g., Chrome)
+		that is being controlled, allowing for direct Selenium operations if needed.
+
+		Returns:
+			Optional[legacyWebDriver]:
+				The active WebDriver instance, or None if no driver is currently set or active.
+		"""
+		
+		...

osn_selenium/abstract/webdriver/chrome/lifecycle.py

@@ -0,0 +1,92 @@
+from typing import Optional
+from abc import abstractmethod
+from osn_selenium.models import WindowRect
+from osn_selenium._typehints import PATH_TYPEHINT
+from osn_selenium.flags.models.chrome import ChromeFlags
+from osn_selenium.abstract.webdriver.blink.lifecycle import (
+	AbstractBlinkLifecycleMixin
+)
+
+
+__all__ = ["AbstractChromeLifecycleMixin"]
+
+
+class AbstractChromeLifecycleMixin(AbstractBlinkLifecycleMixin):
+	"""
+	Abstract mixin managing the lifecycle of a Chrome WebDriver session.
+
+	Defines the contract for creating, starting, and restarting the Chrome browser
+	and its associated WebDriver service.
+	"""
+	
+	@abstractmethod
+	def restart_webdriver(
+			self,
+			flags: Optional[ChromeFlags] = None,
+			browser_exe: Optional[PATH_TYPEHINT] = 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,
+	):
+		"""
+		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[ChromeFlags]): Override flags for the new session.
+				If provided, these flags will be applied. If `None`, current settings are used.
+			browser_exe (Optional[PATH_TYPEHINT]): 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.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def start_webdriver(
+			self,
+			flags: Optional[ChromeFlags] = None,
+			browser_exe: Optional[PATH_TYPEHINT] = 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,
+	):
+		"""
+		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[ChromeFlags]): Override flags for this start.
+				If provided, these flags will be applied. If `None`, current settings are used.
+			browser_exe (Optional[PATH_TYPEHINT]): 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.
+		"""
+		
+		...