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

osn_selenium/abstract/webdriver/core/window.py

@@ -0,0 +1,237 @@
+from abc import ABC, abstractmethod
+from typing import (
+	List,
+	Literal,
+	Optional,
+	Union
+)
+from osn_selenium.models import (
+	Position,
+	Rectangle,
+	Size
+)
+from osn_selenium.abstract.instances.switch_to import AbstractSwitchTo
+
+
+__all__ = ["AbstractCoreWindowMixin"]
+
+
+class AbstractCoreWindowMixin(ABC):
+	"""Mixin responsible for window management, switching, and geometry."""
+	
+	@abstractmethod
+	def close(self) -> None:
+		"""
+		Closes the current window.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def close_all_windows(self) -> None:
+		"""
+		Closes all open windows in the current session.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def close_window(self, window: Optional[Union[str, int]] = None) -> None:
+		"""
+		Closes a specific window by handle or index, or the current window if not specified.
+		If the closed window was the current one, attempts to switch to the last remaining window.
+
+		Args:
+			window (Optional[Union[str, int]]): The window handle (str) or index (int) to close.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def current_window_handle(self) -> str:
+		"""
+		Returns the handle of the current window.
+
+		Returns:
+			str: The handle of the current window.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def fullscreen_window(self) -> None:
+		"""
+		Invokes the window manager-specific "full screen" operation.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def get_window_handle(self, window: Optional[Union[str, int]] = None) -> str:
+		"""
+		Gets the handle of a specific window by handle or index.
+
+		Args:
+			window (Optional[Union[str, int]]): The specific window handle (str) or index (int).
+				If None, defaults to the current window.
+
+		Returns:
+			str: The window handle.
+
+		Raises:
+			IndexError: If the numeric window index is out of range.
+			RuntimeError: If no window handles are available.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def get_window_position(self, window_handle: str = "current") -> Position:
+		"""
+		Gets the position of a window.
+
+		Args:
+			window_handle (str): The handle of the window.
+
+		Returns:
+			Position: An object containing the 'x' and 'y' coordinates of the window.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def get_window_rect(self) -> Rectangle:
+		"""
+		Gets the position and size of the current window.
+
+		Returns:
+			Rectangle: An object with 'x', 'y', 'width', and 'height' properties.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def get_window_size(self, window_handle: str = "current") -> Size:
+		"""
+		Gets the size of a window.
+
+		Args:
+			window_handle (str): The handle of the window.
+
+		Returns:
+			Size: An object containing the 'width' and 'height' of the window.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def maximize_window(self) -> None:
+		"""
+		Maximizes the current window.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def minimize_window(self) -> None:
+		"""
+		Minimizes the current window.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def orientation(self) -> Literal["LANDSCAPE", "PORTRAIT"]:
+		"""
+		Gets the current orientation of the browser.
+
+		Returns:
+			Literal["LANDSCAPE", "PORTRAIT"]: The current orientation.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def set_orientation(self, value: Literal["LANDSCAPE", "PORTRAIT"]) -> None:
+		"""
+		Sets the browser orientation.
+
+		Args:
+			value (Literal["LANDSCAPE", "PORTRAIT"]): The new orientation.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def set_window_position(self, x: int, y: int, window_handle: str = "current") -> Position:
+		"""
+		Sets the position of a window.
+
+		Args:
+			x (int): The x-coordinate of the top-left corner.
+			y (int): The y-coordinate of the top-left corner.
+			window_handle (str): The handle of the window to move.
+
+		Returns:
+			Position: An object representing the new window position.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def set_window_rect(
+			self,
+			x: Optional[int] = None,
+			y: Optional[int] = None,
+			width: Optional[int] = None,
+			height: Optional[int] = None,
+	) -> Rectangle:
+		"""
+		Sets the position and size of the current window.
+
+		Args:
+			x (Optional[int]): The x-coordinate of the top-left corner.
+			y (Optional[int]): The y-coordinate of the top-left corner.
+			width (Optional[int]): The new width of the window.
+			height (Optional[int]): The new height of the window.
+
+		Returns:
+			Rectangle: An object representing the new window rectangle.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def set_window_size(self, width: int, height: int, window_handle: str = "current") -> None:
+		"""
+		Sets the size of a window.
+
+		Args:
+			width (int): The new width in pixels.
+			height (int): The new height in pixels.
+			window_handle (str): The handle of the window to resize.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def switch_to(self) -> AbstractSwitchTo:
+		"""
+		Returns an object to switch context to another frame, window, or alert.
+
+		Returns:
+			AbstractSwitchTo: The SwitchTo instance for context switching.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def window_handles(self) -> List[str]:
+		"""
+		Returns the handles of all windows within the current session.
+
+		Returns:
+			List[str]: A list of window handles.
+		"""
+		
+		...

osn_selenium/abstract/webdriver/edge/__init__.py

@@ -0,0 +1,18 @@
+from abc import ABC
+from osn_selenium.abstract.webdriver.blink import (
+	AbstractBlinkWebDriver
+)
+
+
+__all__ = ["AbstractEdgeWebDriver"]
+
+
+class AbstractEdgeWebDriver(AbstractBlinkWebDriver, ABC):
+	"""
+	Abstract composite class representing a full Edge WebDriver.
+
+	Combines lifecycle, settings, and base functionality for Edge browser.
+	Serves as the main entry point for abstract Edge implementations.
+	"""
+	
+	pass

osn_selenium/abstract/webdriver/edge/base.py

@@ -0,0 +1,36 @@
+from typing import Optional
+from abc import abstractmethod
+from selenium.webdriver.edge.webdriver import (
+	WebDriver as legacyWebDriver
+)
+from osn_selenium.abstract.webdriver.blink.base import (
+	AbstractBlinkBaseMixin
+)
+
+
+__all__ = ["AbstractEdgeBaseMixin"]
+
+
+class AbstractEdgeBaseMixin(AbstractBlinkBaseMixin):
+	"""
+	Abstract mixin defining the base interface for Edge WebDriver.
+
+	This class serves as a foundational component for Edge WebDriver implementations,
+	providing access to the underlying Selenium WebDriver instance.
+	"""
+	
+	@property
+	@abstractmethod
+	def driver(self) -> Optional[legacyWebDriver]:
+		"""
+		Gets the underlying Selenium WebDriver instance associated with this object.
+
+		This property provides direct access to the WebDriver object (e.g., Edge)
+		that is being controlled, allowing for direct Selenium operations if needed.
+
+		Returns:
+			Optional[legacyWebDriver]:
+				The active WebDriver instance, or None if no driver is currently set or active.
+		"""
+		
+		...

osn_selenium/abstract/webdriver/edge/lifecycle.py

@@ -0,0 +1,92 @@
+from typing import Optional
+from abc import abstractmethod
+from osn_selenium.models import WindowRect
+from osn_selenium._typehints import PATH_TYPEHINT
+from osn_selenium.flags.models.edge import EdgeFlags
+from osn_selenium.abstract.webdriver.blink.lifecycle import (
+	AbstractBlinkLifecycleMixin
+)
+
+
+__all__ = ["AbstractEdgeLifecycleMixin"]
+
+
+class AbstractEdgeLifecycleMixin(AbstractBlinkLifecycleMixin):
+	"""
+	Abstract mixin managing the lifecycle of a Edge WebDriver session.
+
+	Defines the contract for creating, starting, and restarting the Edge browser
+	and its associated WebDriver service.
+	"""
+	
+	@abstractmethod
+	def restart_webdriver(
+			self,
+			flags: Optional[EdgeFlags] = None,
+			browser_exe: Optional[PATH_TYPEHINT] = None,
+			browser_name_in_system: Optional[str] = None,
+			use_browser_exe: Optional[bool] = None,
+			start_page_url: Optional[str] = None,
+			window_rect: Optional[WindowRect] = None,
+	):
+		"""
+		Restarts the WebDriver and browser session gracefully.
+
+		Performs a clean restart by first closing the existing WebDriver session and browser
+		(using `close_webdriver`), and then initiating a new session (using `start_webdriver`)
+		with potentially updated settings. If settings arguments are provided, they override
+		the existing settings for the new session; otherwise, the current settings are used.
+
+		Args:
+			flags (Optional[EdgeFlags]): Override flags for the new session.
+				If provided, these flags will be applied. If `None`, current settings are used.
+			browser_exe (Optional[PATH_TYPEHINT]): Override browser executable for the new session.
+				If provided, this path will be used. If `None`, current settings are used.
+			browser_name_in_system (Optional[str]): Override browser name for auto-detection for the new session.
+				Only takes effect if `use_browser_exe` is also provided. If `None`, current settings are used.
+			use_browser_exe (Optional[bool]): Override auto-detection behavior for the new session.
+				If provided, this boolean determines if the browser executable is auto-detected.
+				If `None`, current settings are used.
+			start_page_url (Optional[str]): Override start page URL for the new session.
+				If provided, this URL will be used. If `None`, current setting is used.
+			window_rect (Optional[WindowRect]): Override window rectangle for the new session.
+				If provided, these dimensions will be used. If `None`, current settings are used.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def start_webdriver(
+			self,
+			flags: Optional[EdgeFlags] = None,
+			browser_exe: Optional[PATH_TYPEHINT] = None,
+			browser_name_in_system: Optional[str] = None,
+			use_browser_exe: Optional[bool] = None,
+			start_page_url: Optional[str] = None,
+			window_rect: Optional[WindowRect] = None,
+	):
+		"""
+		Starts the WebDriver service and the browser session.
+
+		Initializes and starts the WebDriver instance and the associated browser process.
+		It first updates settings based on provided parameters (if the driver is not already running),
+		checks if a browser process needs to be started, starts it if necessary using Popen,
+		waits for it to become active, and then creates the WebDriver client instance (`self.driver`).
+
+		Args:
+			flags (Optional[EdgeFlags]): Override flags for this start.
+				If provided, these flags will be applied. If `None`, current settings are used.
+			browser_exe (Optional[PATH_TYPEHINT]): Override browser executable path for this start.
+				If provided, this path will be used. If `None`, current settings are used.
+			browser_name_in_system (Optional[str]): Override browser name for auto-detection for this start.
+				Only takes effect if `use_browser_exe` is also provided. If `None`, current settings are used.
+			use_browser_exe (Optional[bool]): Override auto-detection behavior for this start.
+				If provided, this boolean determines if the browser executable is auto-detected.
+				If `None`, current settings are used.
+			start_page_url (Optional[str]): Override start page URL for this start.
+				If provided, this URL will be used. If `None`, current setting is used.
+			window_rect (Optional[WindowRect]): Override window rectangle for this start.
+				If provided, these dimensions will be used. If `None`, current settings are used.
+		"""
+		
+		...

osn_selenium/abstract/webdriver/edge/settings.py

@@ -0,0 +1,110 @@
+from typing import Optional
+from abc import abstractmethod
+from osn_selenium.models import WindowRect
+from osn_selenium._typehints import PATH_TYPEHINT
+from osn_selenium.flags.models.edge import EdgeFlags
+from osn_selenium.abstract.webdriver.blink.settings import (
+	AbstractBlinkSettingsMixin
+)
+
+
+__all__ = ["AbstractEdgeSettingsMixin"]
+
+
+class AbstractEdgeSettingsMixin(AbstractBlinkSettingsMixin):
+	"""
+	Abstract mixin for managing Edge browser settings.
+
+	Provides methods to update or reset configuration parameters such as flags,
+	executable paths, and window dimensions for the Edge WebDriver.
+	"""
+	
+	@abstractmethod
+	def reset_settings(
+			self,
+			flags: Optional[EdgeFlags] = None,
+			browser_exe: Optional[PATH_TYPEHINT] = None,
+			browser_name_in_system: Optional[str] = None,
+			use_browser_exe: Optional[bool] = None,
+			start_page_url: str = "",
+			window_rect: Optional[WindowRect] = None,
+	):
+		"""
+		Resets various configurable browser settings to their specified or default values.
+
+		This method allows for reconfiguring the WebDriver's operational parameters,
+		such as browser flags, executable path, start URL, window dimensions, and
+		concurrency limits. It is crucial that the browser session is *not* active
+		when this method is called; otherwise, a warning will be issued, and no changes
+		will be applied.
+
+		Args:
+			flags (Optional[EdgeFlags]): New browser flags to apply.
+				If provided, existing flags are cleared and replaced with these.
+				If `None`, all custom flags are cleared, and the browser will start with default flags.
+			browser_exe (Optional[PATH_TYPEHINT]): The explicit path to the browser executable.
+				If provided, this path will be used. If `None`, the executable path managed by the
+				flags manager will be cleared, and then potentially re-detected based on
+				`use_browser_exe` and `browser_name_in_system`.
+			browser_name_in_system (Optional[str]): The common name of the browser (e.g., "Edge").
+				Used in conjunction with `use_browser_exe` to automatically detect the browser executable path.
+				This parameter only takes effect if `use_browser_exe` is explicitly `True` or `False`.
+				If `None`, no automatic detection based on name will occur through this method call.
+			use_browser_exe (Optional[bool]): Controls the automatic detection of the browser executable.
+				If `True` (and `browser_name_in_system` is provided), the browser executable path
+				will be automatically detected if `browser_exe` is `None`.
+				If `False` (and `browser_name_in_system` is provided), any existing `browser_exe`
+				path in the flags manager will be cleared.
+				If `None`, the current `use_browser_exe` state is maintained for the `_detect_browser_exe` logic.
+			start_page_url (str): The URL that the browser will attempt to navigate to
+				immediately after starting. Defaults to an empty string.
+			window_rect (Optional[WindowRect]): The initial window size and position settings.
+				If `None`, it defaults to a new `WindowRect()` instance, effectively resetting
+				to the browser's default window behavior.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def update_settings(
+			self,
+			flags: Optional[EdgeFlags] = None,
+			browser_exe: Optional[PATH_TYPEHINT] = None,
+			browser_name_in_system: Optional[str] = None,
+			use_browser_exe: Optional[bool] = None,
+			start_page_url: Optional[str] = None,
+			window_rect: Optional[WindowRect] = None,
+	):
+		"""
+		Updates various browser settings selectively without resetting others.
+
+		This method allows for dynamic updating of browser settings. Only the settings
+		for which a non-None value is provided will be updated. Settings passed as `None`
+		will retain their current values. This method can be called whether the browser
+		is active or not, but some changes might only take effect after the browser is
+		restarted.
+
+		Args:
+			flags (Optional[EdgeFlags]): New browser flags to update.
+				If provided, these flags will be merged with or overwrite existing flags
+				within the flags manager. If `None`, existing flags remain unchanged.
+			browser_exe (Optional[PATH_TYPEHINT]): The new path to the browser executable.
+				If provided, this path will be set in the flags manager. If `None`, the
+				current browser executable path remains unchanged.
+			browser_name_in_system (Optional[str]): The common name of the browser (e.g., "Edge").
+				Used in conjunction with `use_browser_exe` to automatically detect the browser executable path.
+				This parameter only takes effect if `use_browser_exe` is explicitly provided.
+				If `None`, no automatic detection based on name will occur through this method call.
+			use_browser_exe (Optional[bool]): Controls the automatic detection of the browser executable.
+				If `True` (and `browser_name_in_system` is provided), the browser executable path
+				will be automatically detected if `browser_exe` is `None`.
+				If `False` (and `browser_name_in_system` is provided), any existing `browser_exe`
+				path in the flags manager will be cleared.
+				If `None`, the current `use_browser_exe` state is maintained for the `_detect_browser_exe` logic.
+			start_page_url (Optional[str]): The new URL that the browser will attempt to navigate to
+				immediately after starting. If `None`, the current start page URL remains unchanged.
+			window_rect (Optional[WindowRect]): The new window size and position settings.
+				If `None`, the current window rectangle settings remain unchanged.
+		"""
+		
+		...

osn_selenium/abstract/webdriver/yandex/__init__.py

@@ -0,0 +1,18 @@
+from abc import ABC
+from osn_selenium.abstract.webdriver.chrome import (
+	AbstractChromeWebDriver
+)
+
+
+__all__ = ["AbstractYandexWebDriver"]
+
+
+class AbstractYandexWebDriver(AbstractChromeWebDriver, ABC):
+	"""
+	Abstract composite class representing a full Yandex WebDriver.
+
+	Combines lifecycle, settings, and base functionality for Yandex browser.
+	Serves as the main entry point for abstract Yandex implementations.
+	"""
+	
+	pass

osn_selenium/abstract/webdriver/yandex/base.py

@@ -0,0 +1,18 @@
+from abc import ABC
+from osn_selenium.abstract.webdriver.chrome.base import (
+	AbstractChromeBaseMixin
+)
+
+
+__all__ = ["AbstractYandexBaseMixin"]
+
+
+class AbstractYandexBaseMixin(AbstractChromeBaseMixin, ABC):
+	"""
+	Abstract mixin defining the base interface for Yandex WebDriver.
+
+	This class serves as a foundational component for Yandex WebDriver implementations,
+	providing access to the underlying Selenium WebDriver instance.
+	"""
+	
+	pass

osn_selenium/abstract/webdriver/yandex/lifecycle.py

@@ -0,0 +1,92 @@
+from typing import Optional
+from abc import abstractmethod
+from osn_selenium.models import WindowRect
+from osn_selenium._typehints import PATH_TYPEHINT
+from osn_selenium.flags.models.yandex import YandexFlags
+from osn_selenium.abstract.webdriver.chrome.lifecycle import (
+	AbstractChromeLifecycleMixin
+)
+
+
+__all__ = ["AbstractYandexLifecycleMixin"]
+
+
+class AbstractYandexLifecycleMixin(AbstractChromeLifecycleMixin):
+	"""
+	Abstract mixin managing the lifecycle of a Yandex WebDriver session.
+
+	Defines the contract for creating, starting, and restarting the Yandex browser
+	and its associated WebDriver service.
+	"""
+	
+	@abstractmethod
+	def restart_webdriver(
+			self,
+			flags: Optional[YandexFlags] = None,
+			browser_exe: Optional[PATH_TYPEHINT] = None,
+			browser_name_in_system: Optional[str] = None,
+			use_browser_exe: Optional[bool] = None,
+			start_page_url: Optional[str] = None,
+			window_rect: Optional[WindowRect] = None,
+	):
+		"""
+		Restarts the WebDriver and browser session gracefully.
+
+		Performs a clean restart by first closing the existing WebDriver session and browser
+		(using `close_webdriver`), and then initiating a new session (using `start_webdriver`)
+		with potentially updated settings. If settings arguments are provided, they override
+		the existing settings for the new session; otherwise, the current settings are used.
+
+		Args:
+			flags (Optional[YandexFlags]): Override flags for the new session.
+				If provided, these flags will be applied. If `None`, current settings are used.
+			browser_exe (Optional[PATH_TYPEHINT]): Override browser executable for the new session.
+				If provided, this path will be used. If `None`, current settings are used.
+			browser_name_in_system (Optional[str]): Override browser name for auto-detection for the new session.
+				Only takes effect if `use_browser_exe` is also provided. If `None`, current settings are used.
+			use_browser_exe (Optional[bool]): Override auto-detection behavior for the new session.
+				If provided, this boolean determines if the browser executable is auto-detected.
+				If `None`, current settings are used.
+			start_page_url (Optional[str]): Override start page URL for the new session.
+				If provided, this URL will be used. If `None`, current setting is used.
+			window_rect (Optional[WindowRect]): Override window rectangle for the new session.
+				If provided, these dimensions will be used. If `None`, current settings are used.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def start_webdriver(
+			self,
+			flags: Optional[YandexFlags] = None,
+			browser_exe: Optional[PATH_TYPEHINT] = None,
+			browser_name_in_system: Optional[str] = None,
+			use_browser_exe: Optional[bool] = None,
+			start_page_url: Optional[str] = None,
+			window_rect: Optional[WindowRect] = None,
+	):
+		"""
+		Starts the WebDriver service and the browser session.
+
+		Initializes and starts the WebDriver instance and the associated browser process.
+		It first updates settings based on provided parameters (if the driver is not already running),
+		checks if a browser process needs to be started, starts it if necessary using Popen,
+		waits for it to become active, and then creates the WebDriver client instance (`self.driver`).
+
+		Args:
+			flags (Optional[YandexFlags]): Override flags for this start.
+				If provided, these flags will be applied. If `None`, current settings are used.
+			browser_exe (Optional[PATH_TYPEHINT]): Override browser executable path for this start.
+				If provided, this path will be used. If `None`, current settings are used.
+			browser_name_in_system (Optional[str]): Override browser name for auto-detection for this start.
+				Only takes effect if `use_browser_exe` is also provided. If `None`, current settings are used.
+			use_browser_exe (Optional[bool]): Override auto-detection behavior for this start.
+				If provided, this boolean determines if the browser executable is auto-detected.
+				If `None`, current settings are used.
+			start_page_url (Optional[str]): Override start page URL for this start.
+				If provided, this URL will be used. If `None`, current setting is used.
+			window_rect (Optional[WindowRect]): Override window rectangle for this start.
+				If provided, these dimensions will be used. If `None`, current settings are used.
+		"""
+		
+		...