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

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

osn_selenium/abstract/webdriver/core/auth.py

@@ -0,0 +1,145 @@
+from abc import ABC, abstractmethod
+from typing import (
+	Any,
+	List,
+	Optional,
+	Union
+)
+from osn_selenium.abstract.instances.fedcm import AbstractFedCM
+from osn_selenium.abstract.instances.dialog import AbstractDialog
+from selenium.webdriver.common.virtual_authenticator import (
+	Credential,
+	VirtualAuthenticatorOptions
+)
+
+
+__all__ = ["AbstractCoreAuthMixin"]
+
+
+class AbstractCoreAuthMixin(ABC):
+	"""Mixin responsible for credentials, virtual authenticators, and FedCM."""
+	
+	@abstractmethod
+	def add_credential(self, credential: Credential) -> None:
+		"""
+		Adds a credential to the virtual authenticator.
+
+		Args:
+			credential (Credential): The credential to add.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def add_virtual_authenticator(self, options: VirtualAuthenticatorOptions) -> None:
+		"""
+		Adds a virtual authenticator for testing web authentication.
+
+		Args:
+			options (VirtualAuthenticatorOptions): Configuration for the virtual authenticator.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def fedcm(self) -> AbstractFedCM:
+		"""
+		Provides access to the FedCM (Federated Credential Management) interface.
+
+		Returns:
+			AbstractFedCM: An object for interacting with FedCM.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def fedcm_dialog(
+			self,
+			timeout: int = 5,
+			poll_frequency: float = 0.5,
+			ignored_exceptions: Optional[Any] = None,
+	) -> AbstractDialog:
+		"""
+		Waits for and returns a FedCM (Federated Credential Management) dialog.
+
+		Args:
+			timeout (int): The maximum time to wait for the dialog.
+			poll_frequency (float): The frequency to check for the dialog's presence.
+			ignored_exceptions (Optional[Any]): Exceptions to ignore during polling.
+
+		Returns:
+			AbstractDialog: The FedCM dialog object.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def get_credentials(self) -> List[Credential]:
+		"""
+		Gets all credentials from the virtual authenticator.
+
+		Returns:
+			List[Credential]: A list of Credential objects.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def remove_all_credentials(self) -> None:
+		"""
+		Removes all credentials from the virtual authenticator.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def remove_credential(self, credential_id: Union[str, bytearray]) -> None:
+		"""
+		Removes a credential from the virtual authenticator.
+
+		Args:
+			credential_id (Union[str, bytearray]): The ID of the credential to remove.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def remove_virtual_authenticator(self) -> None:
+		"""
+		Removes the currently active virtual authenticator.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def set_user_verified(self, verified: bool) -> None:
+		"""
+		Sets the user-verified status for a virtual authenticator.
+
+		Args:
+			verified (bool): The new verification status.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def supports_fedcm(self) -> bool:
+		"""
+		Checks if the browser supports Federated Credential Management (FedCM).
+
+		Returns:
+			bool: True if FedCM is supported, False otherwise.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def virtual_authenticator_id(self) -> Optional[str]:
+		"""
+		Returns the ID of the currently active virtual authenticator.
+
+		Returns:
+			Optional[str]: The ID of the virtual authenticator, or None if not set.
+		"""
+		
+		...

osn_selenium/abstract/webdriver/core/base.py

@@ -0,0 +1,298 @@
+from selenium import webdriver
+from abc import ABC, abstractmethod
+from typing import (
+	Any,
+	Dict,
+	Optional,
+	Union
+)
+from selenium.webdriver.common.bidi.session import Session
+from osn_selenium._typehints import (
+	ARCHITECTURES_TYPEHINT
+)
+from selenium.webdriver.remote.errorhandler import ErrorHandler
+from osn_selenium.abstract.executors.cdp import AbstractCDPExecutor
+from selenium.webdriver.remote.locator_converter import LocatorConverter
+from selenium.webdriver.remote.remote_connection import RemoteConnection
+from osn_selenium.abstract.executors.javascript import AbstractJSExecutor
+from selenium.webdriver.remote.webdriver import (
+	WebDriver as legacyWebDriver
+)
+
+
+__all__ = ["AbstractCoreBaseMixin"]
+
+
+class AbstractCoreBaseMixin(ABC):
+	"""
+	Abstract base mixin providing core WebDriver functionality and session management.
+	"""
+	
+	@abstractmethod
+	def _ensure_driver(self) -> Optional[legacyWebDriver]:
+		"""
+		Internal method to ensure the WebDriver instance is running before an operation.
+
+		Returns:
+			Optional[legacyWebDriver]: The driver instance if verified, otherwise None.
+
+		Raises:
+			RuntimeError: If the driver is not started.
+		"""
+		
+		...
+	
+	@property
+	@abstractmethod
+	def architecture(self) -> ARCHITECTURES_TYPEHINT:
+		"""
+		Returns the architecture of the driver.
+
+		Returns:
+			ARCHITECTURE_TYPEHINT: The architecture name.
+		"""
+		
+		...
+	
+	@property
+	@abstractmethod
+	def capabilities(self) -> Dict[str, Any]:
+		"""
+		Returns the capabilities of the current session as reported by the driver.
+
+		Returns:
+			Dict[str, Any]: A dictionary of session capabilities.
+		"""
+		
+		...
+	
+	@property
+	@abstractmethod
+	def caps(self) -> Dict[str, Any]:
+		"""
+		The direct representation of session capabilities.
+
+		Returns:
+			Dict[str, Any]: Current session capabilities.
+		"""
+		
+		...
+	
+	@caps.setter
+	@abstractmethod
+	def caps(self, value: Dict[str, Any]) -> None:
+		"""
+		Sets the session capabilities.
+
+		Args:
+			value (Dict[str, Any]): Dictionary of capabilities.
+		"""
+		
+		...
+	
+	@property
+	@abstractmethod
+	def cdp(self) -> AbstractCDPExecutor:
+		"""
+		Returns the CDP (Chrome DevTools Protocol) executor.
+
+		Returns:
+			AbstractCDPExecutor: The CDP executor instance used for sending
+			commands directly to the browser via the DevTools protocol.
+		"""
+		
+		...
+	
+	@property
+	@abstractmethod
+	def command_executor(self) -> RemoteConnection:
+		"""
+		Gets the remote connection manager used for executing commands.
+
+		Returns:
+			RemoteConnection: The remote connection instance.
+		"""
+		
+		...
+	
+	@command_executor.setter
+	@abstractmethod
+	def command_executor(self, value: RemoteConnection) -> None:
+		"""
+		Sets the remote connection manager used for executing commands.
+
+		Args:
+			value (RemoteConnection): The remote connection instance.
+		"""
+		
+		...
+	
+	@property
+	@abstractmethod
+	def driver(self) -> Optional[Union[webdriver.Chrome, webdriver.Edge, webdriver.Firefox]]:
+		"""
+		Returns the underlying Selenium WebDriver instance.
+
+		Returns:
+			Optional[Union[webdriver.Chrome, webdriver.Edge, webdriver.Firefox]]: The driver instance, or None if not started.
+		"""
+		
+		...
+	
+	@property
+	@abstractmethod
+	def error_handler(self) -> ErrorHandler:
+		"""
+		The error handler associated with the current session.
+
+		Returns:
+			ErrorHandler: The error handler instance.
+		"""
+		
+		...
+	
+	@error_handler.setter
+	@abstractmethod
+	def error_handler(self, value: ErrorHandler) -> None:
+		"""
+		Sets the error handler for the session.
+
+		Args:
+			value (ErrorHandler): The new error handler instance.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def execute(self, driver_command: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+		"""
+		Sends a command to be executed by the remote driver.
+
+		Args:
+			driver_command (str): The name of the command to execute.
+			params (Optional[Dict[str, Any]]): A dictionary of parameters for the command.
+
+		Returns:
+			Dict[str, Any]: The response from the driver.
+		"""
+		
+		...
+	
+	@property
+	@abstractmethod
+	def is_active(self) -> bool:
+		"""
+		Checks if the WebDriver instance is currently running.
+
+		Returns:
+			bool: True if the driver is active, False otherwise.
+		"""
+		
+		...
+	
+	@property
+	@abstractmethod
+	def javascript(self) -> AbstractJSExecutor:
+		"""
+		Returns the JavaScript executor for this WebDriver instance.
+
+		Returns:
+			AbstractJSExecutor: The JavaScript executor instance.
+		"""
+		
+		...
+	
+	@property
+	@abstractmethod
+	def locator_converter(self) -> LocatorConverter:
+		"""
+		The converter used for translating locators into WebDriver protocols.
+
+		Returns:
+			LocatorConverter: The locator converter instance.
+		"""
+		
+		...
+	
+	@locator_converter.setter
+	@abstractmethod
+	def locator_converter(self, value: LocatorConverter) -> None:
+		"""
+		Sets the locator converter instance.
+
+		Args:
+			value (LocatorConverter): The new locator converter.
+		"""
+		
+		...
+	
+	@property
+	@abstractmethod
+	def name(self) -> str:
+		"""
+		Returns the name of the underlying browser (e.g., 'chrome', 'firefox').
+
+		Returns:
+			str: The name of the browser.
+		"""
+		
+		...
+	
+	@property
+	@abstractmethod
+	def pinned_scripts(self) -> Dict[str, Any]:
+		"""
+		A dictionary of scripts pinned to the current session.
+
+		Returns:
+			Dict[str, Any]: Pinned scripts and their handles.
+		"""
+		
+		...
+	
+	@pinned_scripts.setter
+	@abstractmethod
+	def pinned_scripts(self, value: Dict[str, Any]) -> None:
+		"""
+		Sets the pinned scripts for the session.
+
+		Args:
+			value (Dict[str, Any]): Dictionary of scripts to pin.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def session(self) -> Session:
+		"""
+		Internal method to access the current BiDi session object.
+
+		Returns:
+			Session: The session object.
+		"""
+		
+		...
+	
+	@property
+	@abstractmethod
+	def session_id(self) -> Optional[str]:
+		"""
+		The unique session ID assigned by the browser driver.
+
+		Returns:
+			Optional[str]: The session identifier.
+		"""
+		
+		...
+	
+	@session_id.setter
+	@abstractmethod
+	def session_id(self, value: Optional[str]) -> None:
+		"""
+		Sets the unique session ID.
+
+		Args:
+			value (Optional[str]): The new session identifier.
+		"""
+		
+		...

osn_selenium/abstract/webdriver/core/capture.py

@@ -0,0 +1,84 @@
+from typing import Any, Optional
+from abc import ABC, abstractmethod
+
+
+__all__ = ["AbstractCoreCaptureMixin"]
+
+
+class AbstractCoreCaptureMixin(ABC):
+	"""Mixin responsible for screenshots, page source, and printing."""
+	
+	@abstractmethod
+	def get_screenshot_as_base64(self) -> str:
+		"""
+		Gets a screenshot of the current window as a base64-encoded string.
+
+		Returns:
+			str: The base64-encoded screenshot image.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def get_screenshot_as_file(self, filename: str) -> bool:
+		"""
+		Saves a screenshot to a file. This is an alias for save_screenshot.
+
+		Args:
+			filename (str): The full path of the file to save to.
+
+		Returns:
+			bool: True if successful, False otherwise.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def get_screenshot_as_png(self) -> bytes:
+		"""
+		Gets a screenshot of the current window as binary data.
+
+		Returns:
+			bytes: The screenshot image in PNG format.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def page_source(self) -> str:
+		"""
+		Gets the source of the current page.
+
+		Returns:
+			str: The source code of the current page.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def print_page(self, print_options: Optional[Any] = None) -> str:
+		"""
+		Prints the current page to a PDF.
+
+		Args:
+			print_options (Optional[Any]): Options for printing the page.
+
+		Returns:
+			str: A base64-encoded string of the PDF.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def save_screenshot(self, filename: str) -> bool:
+		"""
+		Saves a screenshot of the current window to a file.
+
+		Args:
+			filename (str): The full path of the file to save the screenshot to.
+
+		Returns:
+			bool: True if successful, False otherwise.
+		"""
+		
+		...