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

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

osn_selenium/abstract/webdriver/core/components.py

@@ -0,0 +1,82 @@
+from abc import ABC, abstractmethod
+from osn_selenium.abstract.instances.dialog import AbstractDialog
+from osn_selenium.abstract.instances.mobile import AbstractMobile
+from osn_selenium.abstract.instances.browser import AbstractBrowser
+from osn_selenium.abstract.instances.permissions import AbstractPermissions
+from osn_selenium.abstract.instances.web_extension import AbstractWebExtension
+from osn_selenium.abstract.instances.browsing_context import (
+	AbstractBrowsingContext
+)
+
+
+__all__ = ["AbstractCoreComponentsMixin"]
+
+
+class AbstractCoreComponentsMixin(ABC):
+	"""Mixin responsible for accessing various sub-components of the browser."""
+	
+	@abstractmethod
+	def browser(self) -> AbstractBrowser:
+		"""
+		Provides access to browser-level actions.
+
+		Returns:
+			AbstractBrowser: An object for controlling browser-level features.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def browsing_context(self) -> AbstractBrowsingContext:
+		"""
+		Provides access to the browsing context interface (e.g., tabs, windows).
+
+		Returns:
+			AbstractBrowsingContext: An object for managing browsing contexts.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def dialog(self) -> AbstractDialog:
+		"""
+		Provides access to the dialog (alert, prompt, confirm) interface.
+
+		Returns:
+			AbstractDialog: An object for interacting with browser dialogs.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def mobile(self) -> AbstractMobile:
+		"""
+		Provides access to mobile-specific functionality.
+
+		Returns:
+			AbstractMobile: An object for mobile-specific interactions.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def permissions(self) -> AbstractPermissions:
+		"""
+		Provides access to the permissions management interface.
+
+		Returns:
+			AbstractPermissions: An object for managing browser permissions.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def webextension(self) -> AbstractWebExtension:
+		"""
+		Provides access to the web extension management interface.
+
+		Returns:
+			AbstractWebExtension: An object to manage browser extensions.
+		"""
+		
+		...

osn_selenium/abstract/webdriver/core/devtools.py

@@ -0,0 +1,69 @@
+from abc import ABC, abstractmethod
+from contextlib import asynccontextmanager
+from typing import (
+	Any,
+	AsyncGenerator,
+	Dict,
+	Tuple
+)
+from osn_selenium.abstract.instances.network import AbstractNetwork
+from selenium.webdriver.remote.bidi_connection import BidiConnection
+from selenium.webdriver.remote.websocket_connection import WebSocketConnection
+
+
+__all__ = ["AbstractCoreDevToolsMixin"]
+
+
+class AbstractCoreDevToolsMixin(ABC):
+	"""
+	Mixin responsible for CDP (Chrome DevTools Protocol), BiDi, and Network interactions.
+	"""
+	
+	@asynccontextmanager
+	@abstractmethod
+	async def bidi_connection(self) -> AsyncGenerator[BidiConnection, Any]:
+		"""
+		Returns a context manager for a BiDi (WebDriver Bi-Directional) connection.
+
+		Returns:
+			AsyncGenerator[BidiConnection, Any]: The BiDi connection context manager.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def execute_cdp_cmd(self, cmd: str, cmd_args: Dict[str, Any]) -> Dict[str, Any]:
+		"""
+		Executes a Chrome DevTools Protocol command.
+
+		Args:
+			cmd (str): The CDP command to execute.
+			cmd_args (Dict[str, Any]): The arguments for the command.
+
+		Returns:
+			Dict[str, Any]: The result of the command execution.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def network(self) -> AbstractNetwork:
+		"""
+		Provides access to the network interception and monitoring interface.
+
+		Returns:
+			AbstractNetwork: An object for interacting with network events.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def start_devtools(self) -> Tuple[Any, WebSocketConnection]:
+		"""
+		Starts a connection to the browser's developer tools.
+
+		Returns:
+			Tuple[Any, WebSocketConnection]: A tuple containing the DevTools session info and WebSocket connection.
+		"""
+		
+		...