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

osn_selenium/abstract/instances/action_chains/keyboard.py

@@ -0,0 +1,79 @@
+from abc import ABC, abstractmethod
+from typing import (
+	Optional,
+	TYPE_CHECKING
+)
+from osn_selenium.instances._typehints import WEB_ELEMENT_TYPEHINT
+
+
+__all__ = ["AbstractKeyboardMixin"]
+
+if TYPE_CHECKING:
+	from osn_selenium.abstract.instances.action_chains import AbstractActionChains
+
+
+class AbstractKeyboardMixin(ABC):
+	"""
+	Mixin class providing abstract methods for keyboard interactions.
+	"""
+	
+	@abstractmethod
+	def key_down(self, value: str, element: Optional[WEB_ELEMENT_TYPEHINT]) -> "AbstractActionChains":
+		"""
+		Performs a key press without releasing it.
+
+		Args:
+			value (str): The key to press (e.g., Keys.CONTROL).
+			element (Optional[WEB_ELEMENT_TYPEHINT]): The element to focus before pressing the key.
+				If None, the key is pressed without focusing on an element.
+
+		Returns:
+			AbstractActionChains: The instance of ActionChains for method chaining.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def key_up(self, value: str, element: Optional[WEB_ELEMENT_TYPEHINT]) -> "AbstractActionChains":
+		"""
+		Performs a key release.
+
+		Args:
+			value (str): The key to release (e.g., Keys.CONTROL).
+			element (Optional[WEB_ELEMENT_TYPEHINT]): The element to focus before releasing the key.
+				If None, the key is released without focusing on an element.
+
+		Returns:
+			AbstractActionChains: The instance of ActionChains for method chaining.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def send_keys(self, *keys_to_send: str) -> "AbstractActionChains":
+		"""
+		Sends keys to the current focused element.
+
+		Args:
+			keys_to_send (str): The keys to send.
+
+		Returns:
+			AbstractActionChains: The instance of ActionChains for method chaining.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def send_keys_to_element(self, element: WEB_ELEMENT_TYPEHINT, *keys_to_send: str) -> "AbstractActionChains":
+		"""
+		Sends keys to a specific element.
+
+		Args:
+			element (WEB_ELEMENT_TYPEHINT): The element to send keys to.
+			keys_to_send (str): The keys to send.
+
+		Returns:
+			AbstractActionChains: The instance of ActionChains for method chaining.
+		"""
+		
+		...

osn_selenium/abstract/instances/action_chains/move.py

@@ -0,0 +1,60 @@
+from typing import TYPE_CHECKING
+from abc import ABC, abstractmethod
+from osn_selenium.instances._typehints import WEB_ELEMENT_TYPEHINT
+
+
+__all__ = ["AbstractMoveMixin"]
+
+if TYPE_CHECKING:
+	from osn_selenium.abstract.instances.action_chains import AbstractActionChains
+
+
+class AbstractMoveMixin(ABC):
+	"""
+	Mixin class providing abstract methods for mouse movement interactions.
+	"""
+	
+	@abstractmethod
+	def move_by_offset(self, xoffset: int, yoffset: int) -> "AbstractActionChains":
+		"""
+		Moves the mouse to an offset from the current position.
+
+		Args:
+			xoffset (int): The horizontal offset to move by.
+			yoffset (int): The vertical offset to move by.
+
+		Returns:
+			AbstractActionChains: The instance of ActionChains for method chaining.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def move_to_element(self, to_element: WEB_ELEMENT_TYPEHINT) -> "AbstractActionChains":
+		"""
+		Moves the mouse to the middle of the specified element.
+
+		Args:
+			to_element (WEB_ELEMENT_TYPEHINT): The element to move to.
+
+		Returns:
+			AbstractActionChains: The instance of ActionChains for method chaining.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def move_to_element_with_offset(self, to_element: WEB_ELEMENT_TYPEHINT, xoffset: int, yoffset: int) -> "AbstractActionChains":
+		"""
+		Moves the mouse to an offset from the center of an element.
+
+		Args:
+			to_element (WEB_ELEMENT_TYPEHINT): The element to move to.
+			xoffset (int): The horizontal offset from the element's center.
+			yoffset (int): The vertical offset from the element's center.
+
+		Returns:
+			AbstractActionChains: The instance of ActionChains for method chaining.
+		"""
+		
+		...

osn_selenium/abstract/instances/action_chains/scroll.py

@@ -0,0 +1,61 @@
+from typing import TYPE_CHECKING
+from abc import ABC, abstractmethod
+from osn_selenium.instances._typehints import WEB_ELEMENT_TYPEHINT
+from selenium.webdriver.common.actions.wheel_input import ScrollOrigin
+
+
+__all__ = ["AbstractScrollMixin"]
+
+if TYPE_CHECKING:
+	from osn_selenium.abstract.instances.action_chains import AbstractActionChains
+
+
+class AbstractScrollMixin(ABC):
+	"""
+	Mixin class providing abstract methods for wheel/scroll interactions.
+	"""
+	
+	@abstractmethod
+	def scroll_by_amount(self, delta_x: int, delta_y: int) -> "AbstractActionChains":
+		"""
+		Scrolls by a given amount from the current position.
+
+		Args:
+			delta_x (int): The horizontal scroll amount.
+			delta_y (int): The vertical scroll amount.
+
+		Returns:
+			AbstractActionChains: The instance of ActionChains for method chaining.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def scroll_from_origin(self, scroll_origin: ScrollOrigin, delta_x: int, delta_y: int) -> "AbstractActionChains":
+		"""
+		Scrolls from a specific origin Point by a given offset.
+
+		Args:
+			scroll_origin (ScrollOrigin): The origin Point to start scrolling from.
+			delta_x (int): The horizontal scroll amount.
+			delta_y (int): The vertical scroll amount.
+
+		Returns:
+			AbstractActionChains: The instance of ActionChains for method chaining.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def scroll_to_element(self, element: WEB_ELEMENT_TYPEHINT) -> "AbstractActionChains":
+		"""
+		Scrolls the view to bring the element into view.
+
+		Args:
+			element (WEB_ELEMENT_TYPEHINT): The element to scroll to.
+
+		Returns:
+			AbstractActionChains: The instance of ActionChains for method chaining.
+		"""
+		
+		...

osn_selenium/abstract/instances/action_chains/utils.py

@@ -0,0 +1,44 @@
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Union
+
+
+__all__ = ["AbstractUtilsMixin"]
+
+if TYPE_CHECKING:
+	from osn_selenium.abstract.instances.action_chains import AbstractActionChains
+
+
+class AbstractUtilsMixin(ABC):
+	"""
+	Mixin class providing utility methods for action chains.
+	"""
+	
+	@abstractmethod
+	def pause(self, seconds: Union[float, int]) -> "AbstractActionChains":
+		"""
+		Pauses the execution for a specified duration.
+
+		Args:
+			seconds (Union[float, int]): The duration to pause in seconds.
+
+		Returns:
+			AbstractActionChains: The instance of ActionChains for method chaining.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def perform(self) -> None:
+		"""
+		Performs all stored actions.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def reset_actions(self) -> None:
+		"""
+		Clears all actions that are already stored locally and on the remote end.
+		"""
+		
+		...

osn_selenium/abstract/instances/alert.py

@@ -0,0 +1,67 @@
+from abc import ABC, abstractmethod
+from selenium.webdriver.common.alert import Alert as legacyAlert
+
+
+__all__ = ["AbstractAlert"]
+
+
+class AbstractAlert(ABC):
+	"""
+	Abstract base class for an alert dialog.
+
+	Defines the interface for interacting with JavaScript alerts,
+	prompts, and confirmation dialogs.
+	"""
+	
+	@abstractmethod
+	def accept(self) -> None:
+		"""
+		Accepts the alert.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def dismiss(self) -> None:
+		"""
+		Dismisses the alert.
+		"""
+		
+		...
+	
+	@property
+	@abstractmethod
+	def legacy(self) -> legacyAlert:
+		"""
+		Returns the underlying legacy Selenium Alert instance.
+
+		This provides a way to access the original Selenium object for operations
+		not covered by this abstract interface.
+
+		Returns:
+			legacyAlert: The legacy Selenium Alert object.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def send_keys(self, keysToSend: str) -> None:
+		"""
+		Sends keys to the alert's prompt.
+
+		Args:
+			keysToSend (str): The text to send to the prompt.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def text(self) -> str:
+		"""
+		The text of the alert.
+
+		Returns:
+			str: The text displayed in the alert.
+		"""
+		
+		...

osn_selenium/abstract/instances/browser.py

@@ -0,0 +1,76 @@
+from typing import Sequence
+from abc import ABC, abstractmethod
+from selenium.webdriver.common.bidi.browser import (
+	Browser as legacyBrowser,
+	ClientWindowInfo
+)
+
+
+__all__ = ["AbstractBrowser"]
+
+
+class AbstractBrowser(ABC):
+	"""
+	Abstract base class for browser-level interactions.
+
+	Defines the interface for managing user contexts and client windows.
+	"""
+	
+	@abstractmethod
+	def create_user_context(self) -> str:
+		"""
+		Creates a new user context.
+
+		Returns:
+			str: The ID of the newly created user context.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def get_client_windows(self) -> Sequence[ClientWindowInfo]:
+		"""
+		Gets information about all client windows.
+
+		Returns:
+			Sequence[ClientWindowInfo]: A sequence of ClientWindowInfo objects.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def get_user_contexts(self) -> Sequence[str]:
+		"""
+		Gets a list of all user context IDs.
+
+		Returns:
+			Sequence[str]: A sequence of user context IDs.
+		"""
+		
+		...
+	
+	@property
+	@abstractmethod
+	def legacy(self) -> legacyBrowser:
+		"""
+		Returns the underlying legacy Selenium Browser instance.
+
+		This provides a way to access the original Selenium object for operations
+		not covered by this abstract interface.
+
+		Returns:
+			legacyBrowser: The legacy Selenium Browser object.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def remove_user_context(self, user_context_id: str) -> None:
+		"""
+		Removes a user context.
+
+		Args:
+			user_context_id (str): The ID of the user context to remove.
+		"""
+		
+		...

osn_selenium/abstract/instances/browsing_context.py

@@ -0,0 +1,310 @@
+from abc import ABC, abstractmethod
+from typing import (
+	Callable,
+	Mapping,
+	Optional,
+	Sequence,
+	Union
+)
+from selenium.webdriver.common.bidi.browsing_context import (
+	BrowsingContext as legacyBrowsingContext,
+	BrowsingContextInfo
+)
+
+
+__all__ = ["AbstractBrowsingContext"]
+
+
+class AbstractBrowsingContext(ABC):
+	"""
+	Abstract base class for managing browsing contexts.
+
+	Defines the interface for creating, closing, navigating, and interacting
+	with browsing contexts (e.g., tabs, windows).
+	"""
+	
+	@abstractmethod
+	def activate(self, context: str) -> None:
+		"""
+		Activates (brings to the front) a browsing context.
+
+		Args:
+			context (str): The ID of the browsing context to activate.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def add_event_handler(
+			self,
+			event: str,
+			callback: Callable,
+			contexts: Optional[Sequence[str]] = None,
+	) -> int:
+		"""
+		Adds an event handler for browsing context events.
+
+		Args:
+			event (str): The name of the event to listen for.
+			callback (Callable): The function to call when the event occurs.
+			contexts (Optional[Sequence[str]]): A list of context IDs to listen on.
+
+		Returns:
+			int: The ID of the newly added event handler.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def capture_screenshot(
+			self,
+			context: str,
+			origin: str = 'viewport',
+			format: Optional[Mapping] = None,
+			clip: Optional[Mapping] = None,
+	) -> str:
+		"""
+		Captures a screenshot of a browsing context.
+
+		Args:
+			context (str): The ID of the browsing context to capture.
+			origin (str): The origin of the screenshot ('viewport' or 'document').
+			format (Optional[Mapping]): Image format options.
+			clip (Optional[Mapping]): A clip rectangle to capture a specific area.
+
+		Returns:
+			str: A base64-encoded string of the screenshot image data.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def clear_event_handlers(self) -> None:
+		"""
+		Clears all registered event handlers for browsing contexts.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def close(self, context: str, prompt_unload: bool = False) -> None:
+		"""
+		Closes a browsing context.
+
+		Args:
+			context (str): The ID of the browsing context to close.
+			prompt_unload (bool): Whether to handle any beforeunload prompts.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def create(
+			self,
+			type: str,
+			reference_context: Optional[str] = None,
+			background: bool = False,
+			user_context: Optional[str] = None,
+	) -> str:
+		"""
+		Creates a new browsing context.
+
+		Args:
+			type (str): The type of context to create ('tab' or 'window').
+			reference_context (Optional[str]): A reference context for positioning.
+			background (bool): Whether to create the context in the background.
+			user_context (Optional[str]): The user context to create it in.
+
+		Returns:
+			str: The ID of the newly created browsing context.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def get_tree(self, max_depth: Optional[int] = None, root: Optional[str] = None) -> Sequence[BrowsingContextInfo]:
+		"""
+		Retrieves the tree of browsing contexts.
+
+		Args:
+			max_depth (Optional[int]): The maximum depth of the tree to retrieve.
+			root (Optional[str]): The root context ID to start from.
+
+		Returns:
+			Sequence[BrowsingContextInfo]: A sequence of browsing context information objects.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def handle_user_prompt(
+			self,
+			context: str,
+			accept: Optional[bool] = None,
+			user_text: Optional[str] = None,
+	) -> None:
+		"""
+		Handles a user prompt (e.g., alert, confirm, prompt).
+
+		Args:
+			context (str): The ID of the browsing context with the prompt.
+			accept (Optional[bool]): Whether to accept or dismiss the prompt.
+			user_text (Optional[str]): Text to enter into a prompt.
+		"""
+		
+		...
+	
+	@property
+	@abstractmethod
+	def legacy(self) -> legacyBrowsingContext:
+		"""
+		Returns the underlying legacy Selenium BrowsingContext instance.
+
+		This provides a way to access the original Selenium object for operations
+		not covered by this abstract interface.
+
+		Returns:
+			legacyBrowsingContext: The legacy Selenium BrowsingContext object.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def locate_nodes(
+			self,
+			context: str,
+			locator: Mapping,
+			max_node_count: Optional[int] = None,
+			serialization_options: Optional[Mapping] = None,
+			start_nodes: Optional[Sequence[Mapping]] = None,
+	) -> Sequence[Mapping]:
+		"""
+		Locates nodes within a browsing context.
+
+		Args:
+			context (str): The ID of the browsing context.
+			locator (Mapping): The locator strategy and value.
+			max_node_count (Optional[int]): The maximum number of nodes to return.
+			serialization_options (Optional[Mapping]): Options for serializing the nodes.
+			start_nodes (Optional[Sequence[Mapping]]): Nodes to start the search from.
+
+		Returns:
+			Sequence[Mapping]: A sequence of found nodes.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def navigate(self, context: str, url: str, wait: Optional[str] = None) -> Mapping:
+		"""
+		Navigates a browsing context to a new URL.
+
+		Args:
+			context (str): The ID of the browsing context.
+			url (str): The URL to navigate to.
+			wait (Optional[str]): The page load strategy ('none', 'eager', 'interactive', 'complete').
+
+		Returns:
+			Mapping: A dictionary with navigation information.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def print(
+			self,
+			context: str,
+			background: bool = False,
+			margin: Optional[Mapping] = None,
+			orientation: str = 'portrait',
+			page: Optional[Mapping] = None,
+			page_ranges: Optional[Sequence[Union[int, str]]] = None,
+			scale: float = 1.0,
+			shrink_to_fit: bool = True,
+	) -> str:
+		"""
+		Prints the page to a PDF.
+
+		Args:
+			context (str): The ID of the browsing context.
+			background (bool): Whether to print background graphics.
+			margin (Optional[Mapping]): Margins for the page.
+			orientation (str): Page orientation ('portrait' or 'landscape').
+			page (Optional[Mapping]): Page size settings.
+			page_ranges (Optional[Sequence[Union[int, str]]]): Page ranges to print.
+			scale (float): The scale of the webpage rendering.
+			shrink_to_fit (bool): Whether to shrink the content to fit the page size.
+
+		Returns:
+			str: A base64-encoded string of the PDF data.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def reload(
+			self,
+			context: str,
+			ignore_cache: Optional[bool] = None,
+			wait: Optional[str] = None,
+	) -> Mapping:
+		"""
+		Reloads the current page in a browsing context.
+
+		Args:
+			context (str): The ID of the browsing context.
+			ignore_cache (Optional[bool]): If True, bypasses the cache.
+			wait (Optional[str]): The page load strategy ('none', 'eager', 'interactive', 'complete').
+
+		Returns:
+			Mapping: A dictionary with navigation information.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def remove_event_handler(self, event: str, callback_id: int) -> None:
+		"""
+		Removes an event handler.
+
+		Args:
+			event (str): The name of the event.
+			callback_id (int): The ID of the handler to remove.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def set_viewport(
+			self,
+			context: Optional[str] = None,
+			viewport: Optional[Mapping] = None,
+			device_pixel_ratio: Optional[float] = None,
+			user_contexts: Optional[Sequence[str]] = None,
+	) -> None:
+		"""
+		Sets the viewport for a browsing context.
+
+		Args:
+			context (Optional[str]): The ID of the browsing context.
+			viewport (Optional[Mapping]): A dictionary with 'width' and 'height'.
+			device_pixel_ratio (Optional[float]): The device pixel ratio.
+			user_contexts (Optional[Sequence[str]]): A sequence of user context IDs to apply this to.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def traverse_history(self, context: str, delta: int) -> Mapping:
+		"""
+		Traverses the browsing history by a given delta.
+
+		Args:
+			context (str): The ID of the browsing context.
+			delta (int): The number of steps to go forward (positive) or backward (negative).
+
+		Returns:
+			Mapping: A dictionary with navigation information.
+		"""
+		
+		...