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

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

osn_selenium/abstract/instances/web_element.py

@@ -0,0 +1,395 @@
+from abc import ABC, abstractmethod
+from selenium.webdriver.common.by import By
+from osn_selenium.abstract.instances.shadow_root import AbstractShadowRoot
+from typing import (
+	Any,
+	Iterable,
+	Mapping,
+	Optional,
+	Self,
+	Sequence
+)
+from selenium.webdriver.remote.webelement import (
+	WebElement as legacyWebElement
+)
+from osn_selenium.abstract.instances.web_driver_wait import (
+	AbstractWebDriverWait
+)
+
+
+__all__ = ["AbstractWebElement"]
+
+
+class AbstractWebElement(ABC):
+	"""
+	Abstract base class for a web element.
+
+	Defines the interface for interacting with an element on a web page,
+	such as clicking, sending keys, and retrieving attributes.
+	"""
+	
+	@abstractmethod
+	def __eq__(self, element: Self) -> bool:
+		"""
+		Checks if two elements are equal.
+
+		Args:
+			element (Self): The element to compare with.
+
+		Returns:
+			bool: True if the elements are the same, False otherwise.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def __hash__(self) -> int:
+		"""
+		Returns the hash of the element's ID.
+
+		Returns:
+			int: The hash value.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def __ne__(self, element: Self) -> bool:
+		"""
+		Checks if two elements are not equal.
+
+		Args:
+			element (Self): The element to compare with.
+
+		Returns:
+			bool: True if the elements are not the same, False otherwise.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def __repr__(self) -> str:
+		"""
+		Returns a string representation of the WebElement.
+
+		Returns:
+			str: The string representation.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def accessible_name(self) -> str:
+		"""
+		The accessible name of the element.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def aria_role(self) -> str:
+		"""
+		The ARIA role of the element.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def clear(self) -> None:
+		"""
+		Clears the text if it's a text entry element.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def click(self) -> None:
+		"""
+		Clicks the element.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def find_element(self, by: str = By.ID, value: Optional[str] = None) -> Self:
+		"""
+		Finds a child element within this element's context.
+
+		Args:
+			by (str): 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: str = By.ID, value: Optional[str] = None) -> Sequence[Self]:
+		"""
+		Finds all child elements within this element's context.
+
+		Args:
+			by (str): The strategy to use for finding elements.
+			value (Optional[str]): The value of the locator.
+
+		Returns:
+			Sequence[Self]: A sequence of found WebElements.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def get_attribute(self, name: str) -> Optional[str]:
+		"""
+		Gets the given attribute or property of the element.
+
+		Args:
+			name (str): The name of the attribute/property.
+
+		Returns:
+			Optional[str]: The value of the attribute/property, or None if it does not exist.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def get_dom_attribute(self, name: str) -> Optional[str]:
+		"""
+		Gets the given attribute of the element from the DOM.
+
+		Args:
+			name (str): The name of the attribute.
+
+		Returns:
+			Optional[str]: The value of the attribute, or None if it does not exist.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def get_property(self, name: str) -> Any:
+		"""
+		Gets the given property of the element.
+
+		Args:
+			name (str): The name of the property.
+
+		Returns:
+			Any: The value of the property.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def id(self) -> str:
+		"""
+		The internal ID used by the WebDriver.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def is_displayed(self) -> bool:
+		"""
+		Whether the element is visible to a user.
+
+		Returns:
+			bool: True if the element is displayed, False otherwise.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def is_enabled(self) -> bool:
+		"""
+		Whether the element is enabled.
+
+		Returns:
+			bool: True if the element is enabled, False otherwise.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def is_selected(self) -> bool:
+		"""
+		Whether the element is selected.
+
+		Returns:
+			bool: True if the element is selected, False otherwise.
+		"""
+		
+		...
+	
+	@property
+	@abstractmethod
+	def legacy(self) -> legacyWebElement:
+		"""
+		Returns the underlying legacy Selenium WebElement instance.
+
+		This provides a way to access the original Selenium object for operations
+		not covered by this abstract interface.
+
+		Returns:
+			legacyWebElement: The legacy Selenium WebElement object.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def location(self) -> Mapping[str, int]:
+		"""
+		The location of the element in the renderable canvas.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def location_once_scrolled_into_view(self) -> Mapping[str, int]:
+		"""
+		The location of the element after scrolling it into view.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def parent(self) -> Self:
+		"""
+		The parent of this element (the WebDriver instance).
+		"""
+		
+		...
+	
+	@abstractmethod
+	def rect(self) -> Mapping[str, int]:
+		"""
+		A dictionary with the size and location of the element.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def screenshot(self, filename: str) -> bool:
+		"""
+		Saves a screenshot of the element to a file.
+
+		Args:
+			filename (str): The full path of the file.
+
+		Returns:
+			bool: True if successful, False otherwise.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def screenshot_as_base64(self) -> str:
+		"""
+		A base64-encoded PNG image of the element.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def screenshot_as_png(self) -> bytes:
+		"""
+		A PNG image of the element, as binary data.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def send_keys(self, *value: str) -> None:
+		"""
+		Simulates typing into the element.
+
+		Args:
+			*value (str): A sequence of strings to send.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def session_id(self) -> str:
+		"""
+		The session ID of the WebDriver controlling this element.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def shadow_root(self) -> AbstractShadowRoot:
+		"""
+		The shadow root of this element.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def size(self) -> Mapping[str, int]:
+		"""
+		The size of the element.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def submit(self) -> None:
+		"""
+		Submits a form.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def tag_name(self) -> str:
+		"""
+		The tag name of this element.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def text(self) -> str:
+		"""
+		The text of the element.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def value_of_css_property(self, property_name: str) -> str:
+		"""
+		The value of a CSS property.
+
+		Args:
+			property_name (str): The name of the CSS property.
+
+		Returns:
+			str: The value of the property.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def web_driver_wait(
+			self,
+			timeout: float,
+			poll_frequency: float = 0.5,
+			ignored_exceptions: Optional[Iterable[BaseException]] = None,
+	) -> AbstractWebDriverWait:
+		"""
+		Creates a wait instance for this element.
+
+		Args:
+			timeout (float): Total time to wait in seconds.
+			poll_frequency (float): Sleep interval between polls. Defaults to 0.5.
+			ignored_exceptions (Optional[Iterable[BaseException]]): Exceptions to ignore during polling.
+
+		Returns:
+			AbstractWebDriverWait: The wait instance.
+		"""
+		
+		...

osn_selenium/abstract/instances/web_extension.py

@@ -0,0 +1,70 @@
+from abc import ABC, abstractmethod
+from typing import (
+	Any,
+	Mapping,
+	Optional,
+	Union
+)
+from selenium.webdriver.common.bidi.webextension import (
+	WebExtension as legacyWebExtension
+)
+
+
+__all__ = ["AbstractWebExtension"]
+
+
+class AbstractWebExtension(ABC):
+	"""
+	Abstract base class for managing browser extensions.
+
+	Defines the interface for installing and uninstalling web extensions.
+	"""
+	
+	@abstractmethod
+	def install(
+			self,
+			path: Optional[str] = None,
+			archive_path: Optional[str] = None,
+			base64_value: Optional[str] = None,
+	) -> Mapping[str, Any]:
+		"""
+		Installs a web extension.
+
+		Args:
+			path (Optional[str]): Path to the extension file (.crx or .xpi).
+			archive_path (Optional[str]): Path to a zipped extension directory.
+			base64_value (Optional[str]): Base64 encoded extension data.
+
+		Returns:
+			Mapping[str, Any]: A dictionary containing the result of the installation,
+							   typically including the extension ID.
+		"""
+		
+		...
+	
+	@property
+	@abstractmethod
+	def legacy(self) -> legacyWebExtension:
+		"""
+		Returns the underlying legacy Selenium WebExtension instance.
+
+		This provides a way to access the original Selenium object for operations
+		not covered by this abstract interface.
+
+		Returns:
+			legacyWebExtension: The legacy Selenium WebExtension object.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def uninstall(self, extension_id_or_result: Union[str, Mapping[str, Any]]) -> None:
+		"""
+		Uninstalls a web extension.
+
+		Args:
+			extension_id_or_result (Union[str, Mapping[str, Any]]): The ID of the extension
+				or the result dictionary from an install operation.
+		"""
+		
+		...