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

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

osn_selenium/abstract/webdriver/blink/__init__.py

@@ -0,0 +1,18 @@
+from abc import ABC
+from osn_selenium.abstract.webdriver.core import (
+	AbstractCoreWebDriver as AbstractBaseWebDriver
+)
+
+
+__all__ = ["AbstractBlinkWebDriver"]
+
+
+class AbstractBlinkWebDriver(AbstractBaseWebDriver, ABC):
+	"""
+	Abstract base class for Blink-based WebDrivers.
+
+	Combines the standard WebDriver interface with Blink-specific functionality,
+	specifically access to the Chrome DevTools Protocol (CDP).
+	"""
+	
+	pass

osn_selenium/abstract/webdriver/blink/base.py

@@ -0,0 +1,80 @@
+from abc import abstractmethod
+from selenium import webdriver
+from typing import Optional, Union
+from osn_selenium._typehints import PATH_TYPEHINT
+from osn_selenium.abstract.webdriver.core.base import (
+	AbstractCoreBaseMixin
+)
+
+
+__all__ = ["AbstractBlinkBaseMixin"]
+
+
+class AbstractBlinkBaseMixin(AbstractCoreBaseMixin):
+	"""
+	Abstract mixin defining the base interface for Blink-based WebDrivers (Chrome, Edge).
+
+	This mixin establishes the contract for managing the browser executable path,
+	debugging connection details, and the underlying Selenium driver instance.
+	"""
+	
+	@property
+	@abstractmethod
+	def browser_exe(self) -> Optional[PATH_TYPEHINT]:
+		"""
+		Returns the file path to the browser executable.
+
+		Returns:
+			Optional[PATH_TYPEHINT]: The path to the executable,
+			or None if not managed by this instance.
+		"""
+		
+		...
+	
+	@property
+	@abstractmethod
+	def debugging_ip(self) -> Optional[str]:
+		"""
+		Returns the IP address used for the remote debugging protocol.
+
+		Returns:
+			Optional[str]: The debugging IP address (e.g., "127.0.0.1"), or None if not set.
+		"""
+		
+		...
+	
+	@property
+	@abstractmethod
+	def debugging_port(self) -> Optional[int]:
+		"""
+		Returns the port number used for the remote debugging protocol.
+
+		Returns:
+			Optional[int]: The debugging port, or None if not set.
+		"""
+		
+		...
+	
+	@property
+	@abstractmethod
+	def driver(self) -> Optional[Union[webdriver.Chrome, webdriver.Edge]]:
+		"""
+		Returns the underlying Selenium WebDriver instance.
+
+		Returns:
+			Optional[Union[webdriver.Chrome, webdriver.Edge]]: The driver instance,
+			or None if not started.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def set_start_page_url(self, start_page_url: str) -> None:
+		"""
+		Sets the URL that the browser should navigate to upon startup.
+
+		Args:
+			start_page_url (str): The URL to set as the start page.
+		"""
+		
+		...

osn_selenium/abstract/webdriver/blink/casting.py

@@ -0,0 +1,82 @@
+from typing import Any, Dict, List
+from abc import ABC, abstractmethod
+
+
+__all__ = ["AbstractBlinkCastingMixin"]
+
+
+class AbstractBlinkCastingMixin(ABC):
+	"""
+	Abstract mixin defining the interface for casting/mirroring functionality
+	in Blink-based browsers.
+
+	Provides methods to discover sinks (receivers) and control tab or desktop mirroring sessions.
+	"""
+	
+	@abstractmethod
+	def get_sinks(self) -> List[Dict[str, Any]]:
+		"""
+		Retrieves a list of available casting sinks (receivers).
+
+		Returns:
+			List[Dict[str, Any]]: A list of dictionaries, where each dictionary represents
+			a discovered sink and its properties.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def set_sink_to_use(self, sink_name: str) -> Dict[str, Any]:
+		"""
+		Selects a specific sink to be used for future casting operations.
+
+		Args:
+			sink_name (str): The name of the sink to select.
+
+		Returns:
+			Dict[str, Any]: A dictionary containing the command response or status.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def start_desktop_mirroring(self, sink_name: str) -> Dict[str, Any]:
+		"""
+		Starts mirroring the entire desktop to the specified sink.
+
+		Args:
+			sink_name (str): The name of the sink to cast the desktop to.
+
+		Returns:
+			Dict[str, Any]: A dictionary containing the command response or status.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def start_tab_mirroring(self, sink_name: str) -> Dict[str, Any]:
+		"""
+		Starts mirroring the current browser tab to the specified sink.
+
+		Args:
+			sink_name (str): The name of the sink to cast the tab to.
+
+		Returns:
+			Dict[str, Any]: A dictionary containing the command response or status.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def stop_casting(self, sink_name: str) -> Dict[str, Any]:
+		"""
+		Stops the active casting session on the specified sink.
+
+		Args:
+			sink_name (str): The name of the sink (receiver) to stop casting to.
+
+		Returns:
+			Dict[str, Any]: A dictionary containing the command response or status.
+		"""
+		
+		...

osn_selenium/abstract/webdriver/blink/features.py

@@ -0,0 +1,51 @@
+from typing import Any, Dict
+from abc import ABC, abstractmethod
+
+
+__all__ = ["AbstractBlinkFeaturesMixin"]
+
+
+class AbstractBlinkFeaturesMixin(ABC):
+	"""
+	Abstract mixin defining the interface for specific Blink browser features.
+
+	Includes functionality for handling permissions, launching apps, and retrieving
+	browser issue messages.
+	"""
+	
+	@abstractmethod
+	def get_issue_message(self) -> Any:
+		"""
+		Retrieves the current issue message or status from the browser, if any.
+
+		Returns:
+			Any: The issue message object or string.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def launch_app(self, id: str) -> Dict[str, Any]:
+		"""
+		Launches an installed application within the browser by its ID.
+
+		Args:
+			id (str): The identifier of the application to launch.
+
+		Returns:
+			Dict[str, Any]: A dictionary containing the result of the launch operation.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def set_permissions(self, name: str, value: str) -> None:
+		"""
+		Sets a specific permission for the browser context.
+
+		Args:
+			name (str): The name of the permission (e.g., "camera", "microphone").
+			value (str): The value to set (e.g., "granted", "denied").
+		"""
+		
+		...