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

osn_selenium/abstract/instances/action_chains/hm_scroll.py

@@ -0,0 +1,75 @@
+from abc import ABC, abstractmethod
+from typing import (
+	Optional,
+	TYPE_CHECKING
+)
+from osn_selenium.instances._typehints import WEB_ELEMENT_TYPEHINT
+from selenium.webdriver.common.actions.wheel_input import ScrollOrigin
+
+
+__all__ = ["AbstractHMScrollMixin"]
+
+if TYPE_CHECKING:
+	from osn_selenium.abstract.instances.action_chains import AbstractActionChains
+
+
+class AbstractHMScrollMixin(ABC):
+	"""
+	Mixin class providing abstract methods for human-like scrolling interactions.
+	"""
+	
+	@abstractmethod
+	def hm_scroll_by_amount(self, delta_x: int, delta_y: int) -> "AbstractActionChains":
+		"""
+		Simulates smooth, human-like scrolling by a specific amount.
+
+		Args:
+			delta_x (int): The horizontal distance to scroll.
+			delta_y (int): The vertical distance to scroll.
+
+		Returns:
+			AbstractActionChains: The instance for method chaining.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def hm_scroll_from_origin(self, delta_x: int, delta_y: int, origin: Optional[ScrollOrigin] = None) -> "AbstractActionChains":
+		"""
+		Simulates smooth, human-like scrolling from a specific origin.
+
+		Args:
+			delta_x (int): The horizontal distance to scroll.
+			delta_y (int): The vertical distance to scroll.
+			origin (Optional[ScrollOrigin]): The origin Point for scrolling. If None, it's determined automatically.
+
+		Returns:
+			AbstractActionChains: The instance for method chaining.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def hm_scroll_to_element(
+			self,
+			element: WEB_ELEMENT_TYPEHINT,
+			additional_lower_y_offset: int = 0,
+			additional_upper_y_offset: int = 0,
+			additional_right_x_offset: int = 0,
+			additional_left_x_offset: int = 0
+	) -> "AbstractActionChains":
+		"""
+		Scrolls smoothly to bring an element into view, avoiding viewport edges.
+
+		Args:
+			element (WEB_ELEMENT_TYPEHINT): The target element to scroll to.
+			additional_lower_y_offset (int): Additional offset from the bottom edge of the viewport.
+			additional_upper_y_offset (int): Additional offset from the top edge of the viewport.
+			additional_right_x_offset (int): Additional offset from the right edge of the viewport.
+			additional_left_x_offset (int): Additional offset from the left edge of the viewport.
+
+		Returns:
+			AbstractActionChains: The instance for method chaining.
+		"""
+		
+		...

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