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

osn_selenium/abstract/instances/permissions.py

@@ -0,0 +1,52 @@
+from typing import Optional, Union
+from abc import ABC, abstractmethod
+from selenium.webdriver.common.bidi.permissions import (
+	PermissionDescriptor,
+	Permissions as legacyPermissions
+)
+
+
+__all__ = ["AbstractPermissions"]
+
+
+class AbstractPermissions(ABC):
+	"""
+	Abstract base class for managing browser permissions.
+
+	Defines the interface for setting permission states for various APIs.
+	"""
+	
+	@property
+	@abstractmethod
+	def legacy(self) -> legacyPermissions:
+		"""
+		Returns the underlying legacy Selenium Permissions instance.
+
+		This provides a way to access the original Selenium object for operations
+		not covered by this abstract interface.
+
+		Returns:
+			legacyPermissions: The legacy Selenium Permissions object.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def set_permission(
+			self,
+			descriptor: Union[str, PermissionDescriptor],
+			state: str,
+			origin: str,
+			user_context: Optional[str] = None,
+	) -> None:
+		"""
+		Sets the state of a permission.
+
+		Args:
+			descriptor (Union[str, PermissionDescriptor]): The permission descriptor.
+			state (str): The desired state of the permission (e.g., 'granted', 'denied').
+			origin (str): The origin for which to set the permission.
+			user_context (Optional[str]): The user context ID.
+		"""
+		
+		...

osn_selenium/abstract/instances/script.py

@@ -0,0 +1,109 @@
+from abc import ABC, abstractmethod
+from typing import (
+	Any,
+	Callable,
+	Mapping
+)
+from selenium.webdriver.common.bidi.script import (
+	Script as legacyScript
+)
+
+
+__all__ = ["AbstractScript"]
+
+
+class AbstractScript(ABC):
+	"""
+	Abstract base class for script execution and management.
+
+	Defines the interface for executing JavaScript, handling console messages,
+	and managing pinned scripts.
+	"""
+	
+	@abstractmethod
+	def add_console_message_handler(self, handler: Callable) -> None:
+		"""
+		Adds a handler for console messages.
+
+		Args:
+			handler (Callable): The callback function to handle console messages.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def add_javascript_error_handler(self, handler: Callable) -> None:
+		"""
+		Adds a handler for JavaScript errors.
+
+		Args:
+			handler (Callable): The callback function to handle errors.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def execute(self, script: str, *args: Any) -> Mapping:
+		"""
+		Executes a script.
+
+		Args:
+			script (str): The script to execute.
+			*args (Any): Arguments to pass to the script.
+
+		Returns:
+			Mapping: The result of the script execution.
+		"""
+		
+		...
+	
+	@property
+	@abstractmethod
+	def legacy(self) -> legacyScript:
+		"""
+		Returns the underlying legacy Selenium Script instance.
+
+		This provides a way to access the original Selenium object for operations
+		not covered by this abstract interface.
+
+		Returns:
+			legacyScript: The legacy Selenium Script object.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def pin(self, script: str) -> str:
+		"""
+		Pins a script for faster execution.
+
+		Args:
+			script (str): The JavaScript code to pin.
+
+		Returns:
+			str: The ID of the pinned script.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def remove_console_message_handler(self, id: str) -> None:
+		"""
+		Removes a console message handler.
+
+		Args:
+			id (str): The ID of the handler to remove.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def unpin(self, script_id: str) -> None:
+		"""
+		Unpins a previously pinned script.
+
+		Args:
+			script_id (str): The ID of the script to unpin.
+		"""
+		
+		...

osn_selenium/abstract/instances/shadow_root.py

@@ -0,0 +1,81 @@
+from abc import ABC, abstractmethod
+from selenium.webdriver.common.by import By
+from typing import (
+	Optional,
+	Sequence,
+	TYPE_CHECKING
+)
+from selenium.webdriver.remote.shadowroot import (
+	ShadowRoot as legacyShadowRoot
+)
+
+
+__all__ = ["AbstractShadowRoot"]
+
+if TYPE_CHECKING:
+	from osn_selenium.abstract.instances.web_element import AbstractWebElement
+
+
+class AbstractShadowRoot(ABC):
+	"""
+	Abstract base class for a shadow root.
+
+	Defines the interface for finding elements within a shadow DOM.
+	"""
+	
+	@abstractmethod
+	def find_element(self, by: By = By.ID, value: Optional[str] = None) -> "AbstractWebElement":
+		"""
+		Find an element within the shadow root's context.
+
+		Args:
+			by (By): The strategy to use for finding the element.
+			value (Optional[str]): The value of the locator.
+
+		Returns:
+			"AbstractWebElement": The found WebElement.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def find_elements(self, by: By = By.ID, value: Optional[str] = None) -> Sequence["AbstractWebElement"]:
+		"""
+		Find all elements within the shadow root's context.
+
+		Args:
+			by (By): The strategy to use for finding elements.
+			value (Optional[str]): The value of the locator.
+
+		Returns:
+			Sequence["AbstractWebElement"]: A sequence of found WebElements.
+		"""
+		
+		...
+	
+	@property
+	@abstractmethod
+	def id(self) -> str:
+		"""
+		The ID of the shadow root.
+
+		Returns:
+			str: The unique identifier for the shadow root.
+		"""
+		
+		...
+	
+	@property
+	@abstractmethod
+	def legacy(self) -> legacyShadowRoot:
+		"""
+		Returns the underlying legacy Selenium ShadowRoot instance.
+
+		This provides a way to access the original Selenium object for operations
+		not covered by this abstract interface.
+
+		Returns:
+			legacyShadowRoot: The legacy Selenium ShadowRoot object.
+		"""
+		
+		...

osn_selenium/abstract/instances/storage.py

@@ -0,0 +1,98 @@
+from typing import Optional, Union
+from abc import ABC, abstractmethod
+from selenium.webdriver.common.bidi.storage import (
+	BrowsingContextPartitionDescriptor,
+	CookieFilter,
+	DeleteCookiesResult,
+	GetCookiesResult,
+	PartialCookie,
+	SetCookieResult,
+	Storage as legacyStorage,
+	StorageKeyPartitionDescriptor
+)
+
+
+__all__ = ["AbstractStorage"]
+
+
+class AbstractStorage(ABC):
+	"""
+	Abstract base class for interacting with browser storage.
+
+	Defines the interface for managing cookies within different browsing contexts.
+	"""
+	
+	@abstractmethod
+	def delete_cookies(
+			self,
+			filter: Optional[CookieFilter] = None,
+			partition: Optional[Union[BrowsingContextPartitionDescriptor, StorageKeyPartitionDescriptor]] = None,
+	) -> DeleteCookiesResult:
+		"""
+		Deletes cookies.
+
+		Args:
+			filter (Optional[CookieFilter]): A filter to select which cookies to delete.
+			partition (Optional[Union[BrowsingContextPartitionDescriptor, StorageKeyPartitionDescriptor]]):
+				The storage partition to delete cookies from.
+
+		Returns:
+			DeleteCookiesResult: The result of the delete cookies operation.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def get_cookies(
+			self,
+			filter: Optional[CookieFilter] = None,
+			partition: Optional[Union[BrowsingContextPartitionDescriptor, StorageKeyPartitionDescriptor]] = None,
+	) -> GetCookiesResult:
+		"""
+		Gets cookies from the browser.
+
+		Args:
+			filter (Optional[CookieFilter]): A filter to apply to the cookies.
+			partition (Optional[Union[BrowsingContextPartitionDescriptor, StorageKeyPartitionDescriptor]]):
+				The storage partition to retrieve cookies from.
+
+		Returns:
+			GetCookiesResult: The result containing the retrieved cookies.
+		"""
+		
+		...
+	
+	@property
+	@abstractmethod
+	def legacy(self) -> legacyStorage:
+		"""
+		Returns the underlying legacy Selenium Storage instance.
+
+		This provides a way to access the original Selenium object for operations
+		not covered by this abstract interface.
+
+		Returns:
+			legacyStorage: The legacy Selenium Storage object.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def set_cookie(
+			self,
+			cookie: PartialCookie,
+			partition: Optional[Union[BrowsingContextPartitionDescriptor, StorageKeyPartitionDescriptor]] = None,
+	) -> SetCookieResult:
+		"""
+		Sets a cookie.
+
+		Args:
+			cookie (PartialCookie): The cookie to set.
+			partition (Optional[Union[BrowsingContextPartitionDescriptor, StorageKeyPartitionDescriptor]]):
+				The storage partition to set the cookie in.
+
+		Returns:
+			SetCookieResult: The result of the set cookie operation.
+		"""
+		
+		...

osn_selenium/abstract/instances/switch_to.py

@@ -0,0 +1,104 @@
+from typing import Optional, Union
+from abc import ABC, abstractmethod
+from selenium.webdriver.common.alert import Alert
+from osn_selenium.abstract.instances.web_element import AbstractWebElement
+from selenium.webdriver.remote.switch_to import (
+	SwitchTo as legacySwitchTo
+)
+
+
+__all__ = ["AbstractSwitchTo"]
+
+
+class AbstractSwitchTo(ABC):
+	"""
+	Abstract base class for context switching.
+
+	Defines the interface for switching between frames, windows, and alerts.
+	"""
+	
+	@abstractmethod
+	def active_element(self) -> AbstractWebElement:
+		"""
+		Returns the element with focus, or the body if no element has focus.
+
+		Returns:
+			AbstractWebElement: The currently active WebElement.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def alert(self) -> Alert:
+		"""
+		Switches to the currently active alert.
+
+		Returns:
+			Alert: The Alert object for the active alert.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def default_content(self) -> None:
+		"""
+		Switches focus to the default content of a page.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def frame(self, frame_reference: Union[str, int, AbstractWebElement]) -> None:
+		"""
+		Switches focus to the specified frame.
+
+		Args:
+			frame_reference (Union[str, int, AbstractWebElement]): The name, index, or WebElement of the frame.
+		"""
+		
+		...
+	
+	@property
+	@abstractmethod
+	def legacy(self) -> legacySwitchTo:
+		"""
+		Returns the underlying legacy Selenium SwitchTo instance.
+
+		This provides a way to access the original Selenium object for operations
+		not covered by this abstract interface.
+
+		Returns:
+			legacySwitchTo: The legacy Selenium SwitchTo object.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def new_window(self, type_hint: Optional[str] = None) -> None:
+		"""
+		Creates a new window and switches to it.
+
+		Args:
+			type_hint (Optional[str]): Specifies the type of new window, e.g., 'tab' or 'window'.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def parent_frame(self) -> None:
+		"""
+		Switches focus to the parent frame.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def window(self, window_name: str) -> None:
+		"""
+		Switches focus to the specified window.
+
+		Args:
+			window_name (str): The name or window handle of the window to switch to.
+		"""
+		
+		...

osn_selenium/abstract/instances/web_driver_wait.py

@@ -0,0 +1,57 @@
+from typing import Any, Callable
+from abc import ABC, abstractmethod
+from selenium.webdriver.support.wait import (
+	WebDriverWait as legacyWebDriverWait
+)
+
+
+__all__ = ["AbstractWebDriverWait"]
+
+
+class AbstractWebDriverWait(ABC):
+	"""
+	Abstract base class for WebDriver wait implementations.
+
+	Provides the interface for waiting until a condition is met or a timeout occurs.
+	"""
+	
+	@abstractmethod
+	def legacy(self) -> legacyWebDriverWait:
+		"""
+		Returns the underlying Selenium WebDriverWait instance.
+
+		Returns:
+			legacyWebDriverWait: The original Selenium wait object.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def until(self, method: Callable[[Any], Any], message: str = "") -> Any:
+		"""
+		Waits until the method returns a non-false value.
+
+		Args:
+			method (Callable[[Any], Any]): The condition to evaluate.
+			message (str): Optional message for TimeoutException.
+
+		Returns:
+			Any: The return value of the method.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def until_not(self, method: Callable[[Any], Any], message: str = "") -> Any:
+		"""
+		Waits until the method returns a false value.
+
+		Args:
+			method (Callable[[Any], Any]): The condition to evaluate.
+			message (str): Optional message for TimeoutException.
+
+		Returns:
+			Any: The return value of the method.
+		"""
+		
+		...