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

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.
+		"""
+		
+		...

osn_selenium/abstract/webdriver/chrome/settings.py

@@ -0,0 +1,110 @@
+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.settings import (
+	AbstractBlinkSettingsMixin
+)
+
+
+__all__ = ["AbstractChromeSettingsMixin"]
+
+
+class AbstractChromeSettingsMixin(AbstractBlinkSettingsMixin):
+	"""
+	Abstract mixin for managing Chrome browser settings.
+
+	Provides methods to update or reset configuration parameters such as flags,
+	executable paths, and window dimensions for the Chrome WebDriver.
+	"""
+	
+	@abstractmethod
+	def reset_settings(
+			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: str = "",
+			window_rect: Optional[WindowRect] = None,
+	):
+		"""
+		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[ChromeFlags]): 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[PATH_TYPEHINT]): 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").
+				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.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def update_settings(
+			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,
+	):
+		"""
+		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[ChromeFlags]): 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[PATH_TYPEHINT]): 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").
+				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.
+		"""
+		
+		...

osn_selenium/abstract/webdriver/core/__init__.py

@@ -0,0 +1,16 @@
+from abc import ABC
+
+
+__all__ = ["AbstractCoreWebDriver"]
+
+
+class AbstractCoreWebDriver(ABC):
+	"""
+	Abstract base class for a WebDriver.
+
+	This class defines the interface that all WebDriver implementations must adhere to.
+	It includes methods for browser navigation, element interaction, script execution,
+	and managing various browser features.
+	"""
+	
+	pass

osn_selenium/abstract/webdriver/core/actions.py

@@ -0,0 +1,58 @@
+from abc import ABC, abstractmethod
+from typing import (
+	Iterable,
+	List,
+	Optional
+)
+from osn_selenium._typehints import DEVICES_TYPEHINT
+from osn_selenium.abstract.instances.action_chains import AbstractActionChains
+from osn_selenium.abstract.instances.web_driver_wait import (
+	AbstractWebDriverWait
+)
+
+
+__all__ = ["AbstractCoreActionsMixin"]
+
+
+class AbstractCoreActionsMixin(ABC):
+	"""Mixin responsible for user actions chains."""
+	
+	@abstractmethod
+	def action_chains(
+			self,
+			duration: int = 250,
+			devices: Optional[List[DEVICES_TYPEHINT]] = None
+	) -> AbstractActionChains:
+		"""
+		Creates a new ActionChains instance for building complex user interactions.
+
+		Args:
+			duration (int): The default duration for pointer actions in milliseconds.
+			devices (Optional[List[DEVICES_TYPEHINT]]): A list of input devices to use.
+
+		Returns:
+			AbstractActionChains: A new ActionChains instance.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def web_driver_wait(
+			self,
+			timeout: float,
+			poll_frequency: float = 0.5,
+			ignored_exceptions: Optional[Iterable[BaseException]] = None,
+	) -> AbstractWebDriverWait:
+		"""
+		Creates a new WebDriverWait instance.
+
+		Args:
+			timeout (float): How long to wait for the condition to be true.
+			poll_frequency (float): How often to check the condition. Defaults to 0.5.
+			ignored_exceptions (Optional[Iterable[BaseException]]): Exceptions to ignore while waiting.
+
+		Returns:
+			AbstractWebDriverWait: A new WebDriverWait instance.
+		"""
+		
+		...