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

osn_selenium/webdrivers/_args_helpers.py

@@ -0,0 +1,181 @@
+import trio
+from typing import Any, Callable, Dict
+from osn_selenium.instances.protocols import AnyInstanceWrapper
+from osn_selenium.exceptions.protocol import (
+	ProtocolComplianceError
+)
+from osn_selenium.webdrivers._typehints import (
+	ANY_WEBDRIVER_PROTOCOL_TYPEHINT
+)
+from osn_selenium.instances.sync.web_element import (
+	WebElement as SyncWebElement
+)
+from selenium.webdriver.remote.webelement import (
+	WebElement as SeleniumWebElement
+)
+from osn_selenium.webdrivers.protocols import (
+	SyncWebDriver,
+	TrioThreadWebDriver
+)
+from osn_selenium.instances.trio_threads.web_element import (
+	WebElement as TrioThreadWebElement
+)
+from osn_selenium.instances.convert import (
+	get_sync_instance_wrapper,
+	get_trio_thread_instance_wrapper
+)
+
+
+__all__ = [
+	"build_cdp_kwargs",
+	"get_wrap_args_function",
+	"unwrap_args",
+	"wrap_sync_args",
+	"wrap_trio_thread_args"
+]
+
+
+def unwrap_args(args: Any) -> Any:
+	"""
+	Recursively unwraps objects by extracting the legacy Selenium object from wrappers.
+
+	Args:
+		args (Any): Data structure containing potential instance wrappers.
+
+	Returns:
+		Any: Data structure with raw Selenium objects.
+	"""
+	
+	if isinstance(args, list):
+		return [unwrap_args(arg) for arg in args]
+	
+	if isinstance(args, set):
+		return {unwrap_args(arg) for arg in args}
+	
+	if isinstance(args, tuple):
+		return (unwrap_args(arg) for arg in args)
+	
+	if isinstance(args, dict):
+		return {unwrap_args(key): unwrap_args(value) for key, value in args.items()}
+	
+	if isinstance(args, AnyInstanceWrapper):
+		return args.legacy
+	
+	return args
+
+
+def wrap_trio_thread_args(args: Any, lock: trio.Lock, limiter: trio.CapacityLimiter) -> Any:
+	"""
+	Recursively wraps Selenium WebElements into TrioThreadWebElement instances.
+
+	Args:
+		args (Any): Data structure containing potential Selenium WebElements.
+		lock (trio.Lock): Trio lock for synchronization.
+		limiter (trio.CapacityLimiter): Trio capacity limiter.
+
+	Returns:
+		Any: Data structure with wrapped elements.
+	"""
+	
+	if isinstance(args, list):
+		return [wrap_trio_thread_args(arg, lock=lock, limiter=limiter) for arg in args]
+	
+	if isinstance(args, set):
+		return {wrap_trio_thread_args(arg, lock=lock, limiter=limiter) for arg in args}
+	
+	if isinstance(args, tuple):
+		return (wrap_trio_thread_args(arg, lock=lock, limiter=limiter) for arg in args)
+	
+	if isinstance(args, dict):
+		return {
+			wrap_trio_thread_args(key, lock=lock, limiter=limiter): wrap_trio_thread_args(value, lock=lock, limiter=limiter)
+			for key, value in args.items()
+		}
+	
+	if isinstance(args, SeleniumWebElement):
+		return get_trio_thread_instance_wrapper(
+				wrapper_class=TrioThreadWebElement,
+				legacy_object=args,
+				lock=lock,
+				limiter=limiter,
+		)
+	
+	return args
+
+
+def wrap_sync_args(args: Any) -> Any:
+	"""
+	Recursively wraps Selenium WebElements into SyncWebElement instances.
+
+	Args:
+		args (Any): Data structure containing potential Selenium WebElements.
+
+	Returns:
+		Any: Data structure with wrapped elements.
+	"""
+	
+	if isinstance(args, list):
+		return [wrap_sync_args(arg) for arg in args]
+	
+	if isinstance(args, set):
+		return {wrap_sync_args(arg) for arg in args}
+	
+	if isinstance(args, tuple):
+		return (wrap_sync_args(arg) for arg in args)
+	
+	if isinstance(args, dict):
+		return {wrap_sync_args(key): wrap_sync_args(value) for key, value in args.items()}
+	
+	if isinstance(args, SeleniumWebElement):
+		return get_sync_instance_wrapper(wrapper_class=SyncWebElement, legacy_object=args)
+	
+	return args
+
+
+def get_wrap_args_function(driver: ANY_WEBDRIVER_PROTOCOL_TYPEHINT) -> Callable[[Any], Any]:
+	"""
+	Determines the appropriate argument wrapping function based on the driver's architecture.
+
+	Args:
+		driver (ANY_WEBDRIVER_PROTOCOL): The driver instance.
+
+	Returns:
+		Callable[[Any], Any]: A function to wrap elements.
+
+	Raises:
+		ExpectedTypeError: If the driver instance type is not supported.
+	"""
+	
+	if isinstance(driver, SyncWebDriver) and driver.architecture == "sync":
+		def wrapper(args: Any) -> Any:
+			return wrap_sync_args(args)
+	
+		return wrapper
+	
+	if isinstance(driver, TrioThreadWebDriver) and driver.architecture == "trio_threads":
+		def wrapper(args: Any) -> Any:
+			return wrap_trio_thread_args(args, lock=driver.lock, limiter=driver.capacity_limiter)
+	
+		return wrapper
+	
+	raise ProtocolComplianceError(instance=driver, expected_protocols=(SyncWebDriver, TrioThreadWebDriver))
+
+
+def build_cdp_kwargs(**kwargs: Any) -> Dict[str, Any]:
+	"""
+	Builds a dictionary of keyword arguments for a CDP command, excluding None values.
+
+	Args:
+		**kwargs (Any): Keyword arguments to filter.
+
+	Returns:
+		Dict[str, Any]: A dictionary containing only the non-None keyword arguments.
+	"""
+	
+	dict_ = {}
+	
+	for key, value in kwargs.items():
+		if value is not None:
+			dict_[key] = value
+	
+	return dict_

osn_selenium/webdrivers/_bridges.py

@@ -0,0 +1,57 @@
+from typing import Any, Callable, Dict
+from osn_selenium.webdrivers._typehints import (
+	ANY_WEBDRIVER_PROTOCOL_TYPEHINT
+)
+from osn_selenium.webdrivers._args_helpers import (
+	get_wrap_args_function,
+	unwrap_args
+)
+
+
+__all__ = ["get_cdp_executor_bridge", "get_js_executor_bridge"]
+
+
+def get_js_executor_bridge(driver: ANY_WEBDRIVER_PROTOCOL_TYPEHINT) -> Callable[[str, Any], Any]:
+	"""
+	Creates a bridge function for executing JavaScript in the browser.
+
+	Args:
+		driver (ANY_WEBDRIVER_PROTOCOL): The driver instance.
+
+	Returns:
+		Callable[[str, Any], Any]: A wrapper for execute_script.
+	"""
+	
+	def wrapper(script: str, *args: Any) -> Any:
+		args = unwrap_args(args)
+		
+		result = driver.driver.execute_script(script, *args)
+		
+		return wrapper_function(result)
+	
+	wrapper_function = get_wrap_args_function(driver=driver)
+	
+	return wrapper
+
+
+def get_cdp_executor_bridge(driver: ANY_WEBDRIVER_PROTOCOL_TYPEHINT) -> Callable[[str, Dict[str, Any]], Any]:
+	"""
+	Creates a bridge function for executing CDP commands in the browser.
+
+	Args:
+		driver (ANY_WEBDRIVER_PROTOCOL): The driver instance.
+
+	Returns:
+		Callable[[str, Dict[str, Any]], Any]: A wrapper for execute_cdp_cmd.
+	"""
+	
+	def wrapper(cmd: str, cmd_args: Dict[str, Any]) -> Any:
+		cmd_args = unwrap_args(cmd_args)
+		
+		result = driver.driver.execute_cdp_cmd(cmd, cmd_args)
+		
+		return wrapper_function(result)
+	
+	wrapper_function = get_wrap_args_function(driver=driver)
+	
+	return wrapper

osn_selenium/webdrivers/_decorators.py

@@ -0,0 +1,83 @@
+import inspect
+import functools
+from typing import (
+	Any,
+	Callable,
+	ParamSpec,
+	TypeVar
+)
+from osn_selenium.exceptions.instance import NotExpectedTypeError
+
+
+__all__ = ["requires_driver"]
+
+_METHOD_INPUT = ParamSpec("_METHOD_INPUT")
+_METHOD_OUTPUT = TypeVar("_METHOD_OUTPUT")
+_METHOD = TypeVar("_METHOD", bound=Callable[..., Any])
+
+
+def requires_driver(func: _METHOD) -> _METHOD:
+	"""
+	A decorator that ensures a '_ensure_driver' method is called before
+	executing the decorated method.
+
+	This decorator handles both synchronous and asynchronous methods,
+	calling '_ensure_driver' on the instance (self) before delegating
+	to the original method.
+
+	Args:
+		func (_METHOD): The method to decorate.
+
+	Returns:
+		_METHOD: The wrapped synchronous or asynchronous method.
+	"""
+	
+	@functools.wraps(func)
+	def sync_wrapper(
+			self: object,
+			*args: _METHOD_INPUT.args,
+			**kwargs: _METHOD_INPUT.kwargs
+	) -> _METHOD_OUTPUT:
+		"""
+		Synchronous wrapper for methods decorated with requires_driver.
+
+		Args:
+			self (object): The instance on which the method is called.
+			*args (_METHOD_INPUT.args): Positional arguments for the wrapped method.
+			**kwargs (_METHOD_INPUT.kwargs): Keyword arguments for the wrapped method.
+
+		Returns:
+			_METHOD_OUTPUT: The result of the wrapped method.
+		"""
+		
+		getattr(self, "_ensure_driver")()
+		return func(self, *args, **kwargs)
+	
+	@functools.wraps(func)
+	async def async_wrapper(
+			self: object,
+			*args: _METHOD_INPUT.args,
+			**kwargs: _METHOD_INPUT.kwargs
+	) -> _METHOD_OUTPUT:
+		"""
+		Asynchronous wrapper for methods decorated with requires_driver.
+
+		Args:
+			self (object): The instance on which the method is called.
+			*args (_METHOD_INPUT.args): Positional arguments for the wrapped method.
+			**kwargs (_METHOD_INPUT.kwargs): Keyword arguments for the wrapped method.
+
+		Returns:
+			_METHOD_OUTPUT: The result of the wrapped method.
+		"""
+		
+		getattr(self, "_ensure_driver")()
+		return await func(self, *args, **kwargs)
+	
+	if inspect.iscoroutinefunction(func):
+		return async_wrapper
+	
+	if inspect.isfunction(func):
+		return sync_wrapper
+	
+	raise NotExpectedTypeError(expected_type=["coroutine function", "function"], received_instance=func)

osn_selenium/webdrivers/_executable_tables/__init__.py

@@ -0,0 +1 @@
+

osn_selenium/webdrivers/_executable_tables/functions.py

@@ -0,0 +1,113 @@
+import re
+import psutil
+from typing import Iterator, Optional
+from osn_selenium._functions import validate_path
+from osn_selenium._typehints import PATH_TYPEHINT
+from osn_system_utils.api._utils import LOCALHOST_IPS
+from osn_selenium.webdrivers._executable_tables.models import ExecutablesTableRow
+
+
+__all__ = [
+	"find_browser_previous_session",
+	"get_active_executables_table",
+	"get_found_profile_dir"
+]
+
+
+def get_found_profile_dir(row: ExecutablesTableRow, profile_dir_command: str) -> Optional[str]:
+	"""
+	Extracts the profile directory path from the command line of a running process.
+
+	Args:
+		row (ExecutablesTableRow): The data row containing the PID of the process.
+		profile_dir_command (str): The command line pattern to search for, using `{value}` as placeholder.
+
+	Returns:
+		Optional[str]: The extracted profile directory path if found, otherwise None.
+	"""
+	
+	try:
+		proc = psutil.Process(row.pid)
+		cmdline_args = proc.cmdline()
+	
+		found_command_line = " ".join(cmdline_args)
+		pattern = profile_dir_command.format(value="(.*?)")
+	
+		found_profile_dir = re.search(pattern=pattern, string=found_command_line)
+	
+		if found_profile_dir is not None:
+			result = found_profile_dir.group(1)
+	
+			return result
+	except (psutil.NoSuchProcess, psutil.AccessDenied, psutil.ZombieProcess):
+		return None
+	
+	return None
+
+
+def get_active_executables_table(browser_exe: PATH_TYPEHINT) -> Iterator[ExecutablesTableRow]:
+	"""
+	Iterates through active network connections to find processes matching the browser executable.
+
+	Args:
+		browser_exe (PATH_TYPEHINT): Path or name of the browser executable.
+
+	Returns:
+		Iterator[ExecutablesTableRow]: An iterator of matching process information rows.
+	"""
+	
+	target_name = validate_path(path=browser_exe).name
+	
+	for conn in psutil.net_connections(kind="inet"):
+		if (
+				conn.status != psutil.CONN_LISTEN
+				or not conn.laddr
+				or conn.laddr.ip not in LOCALHOST_IPS
+				or not conn.pid
+		):
+			continue
+	
+		try:
+			process = psutil.Process(conn.pid)
+			process_name = process.name()
+	
+			if process_name.lower() == target_name.lower():
+				yield ExecutablesTableRow(
+						executable=process_name,
+						address=f"{conn.laddr.ip}:{conn.laddr.port}",
+						pid=conn.pid,
+				)
+		except (psutil.NoSuchProcess, psutil.AccessDenied, psutil.ZombieProcess):
+			continue
+
+
+def find_browser_previous_session(
+		browser_exe: PATH_TYPEHINT,
+		profile_dir_command: str,
+		profile_dir: Optional[str]
+) -> Optional[int]:
+	"""
+	Finds the port number of a previously opened browser session, if it exists.
+
+	This function checks for an existing browser session by examining network connections.
+	It searches for listening connections associated with the given browser executable and profile directory.
+
+	Args:
+		browser_exe (PATH_TYPEHINT): Path to the browser executable or just the executable name.
+		profile_dir_command (str): Command line pattern to find the profile directory argument.
+								   Should use `{value}` as a placeholder for the directory path.
+		profile_dir (Optional[str]): The expected profile directory path to match against.
+
+	Returns:
+		Optional[int]: The port number of the previous session if found and matched, otherwise None.
+	"""
+	
+	ip_pattern = re.compile(r"127\.0\.0\.1:(\d+)")
+	
+	for row in get_active_executables_table(browser_exe=browser_exe):
+		found_profile_dir = get_found_profile_dir(row=row, profile_dir_command=profile_dir_command)
+	
+		if found_profile_dir == profile_dir:
+			return int(re.search(pattern=ip_pattern, string=row.address).group(1))
+	
+	return None

osn_selenium/webdrivers/_executable_tables/models.py

@@ -0,0 +1,19 @@
+from osn_selenium._base_models import DictModel
+
+
+__all__ = ["ExecutablesTableRow"]
+
+
+class ExecutablesTableRow(DictModel):
+	"""
+	Represents a row in the executables table containing process information.
+
+	Attributes:
+		executable (str): The name of the executable file.
+		address (str): The network address (IP:Port) the process is listening on.
+		pid (int): The process identifier.
+	"""
+	
+	executable: str
+	address: str
+	pid: int

osn_selenium/webdrivers/_typehints.py

@@ -0,0 +1,10 @@
+from typing import Union
+from osn_selenium.webdrivers.protocols import (
+	SyncWebDriver,
+	TrioThreadWebDriver
+)
+
+
+__all__ = ["ANY_WEBDRIVER_PROTOCOL_TYPEHINT"]
+
+ANY_WEBDRIVER_PROTOCOL_TYPEHINT = Union[SyncWebDriver, TrioThreadWebDriver]

osn_selenium/webdrivers/protocols.py

@@ -0,0 +1,50 @@
+import trio
+from typing import (
+	Optional,
+	Protocol,
+	runtime_checkable
+)
+from selenium.webdriver.remote.webdriver import (
+	WebDriver as legacyWebDriver
+)
+
+
+__all__ = ["SyncWebDriver", "TrioThreadWebDriver"]
+
+
+@runtime_checkable
+class TrioThreadWebDriver(Protocol):
+	"""
+	Protocol for a WebDriver that operates within a Trio thread pool.
+	"""
+	
+	@property
+	def architecture(self) -> str:
+		...
+	
+	@property
+	def capacity_limiter(self) -> trio.CapacityLimiter:
+		...
+	
+	@property
+	def driver(self) -> Optional[legacyWebDriver]:
+		...
+	
+	@property
+	def lock(self) -> trio.Lock:
+		...
+
+
+@runtime_checkable
+class SyncWebDriver(Protocol):
+	"""
+	Protocol for a synchronous WebDriver.
+	"""
+	
+	@property
+	def architecture(self) -> str:
+		...
+	
+	@property
+	def driver(self) -> Optional[legacyWebDriver]:
+		...

osn_selenium/webdrivers/sync/__init__.py

@@ -0,0 +1 @@
+

osn_selenium/webdrivers/sync/blink/__init__.py

@@ -0,0 +1,124 @@
+from osn_selenium.models import WindowRect
+from typing import (
+	Mapping,
+	Optional,
+	Type
+)
+from osn_selenium._typehints import PATH_TYPEHINT
+from osn_selenium.flags.blink import BlinkFlagsManager
+from osn_selenium.flags.models.blink import BlinkFlags
+from osn_selenium.webdrivers.sync.core import CoreWebDriver
+from osn_selenium.webdrivers.sync.blink.base import BlinkBaseMixin
+from osn_selenium.webdrivers.sync.blink.casting import BlinkCastingMixin
+from osn_selenium.webdrivers.sync.blink.logging import BlinkLoggingMixin
+from osn_selenium.webdrivers.sync.blink.network import BlinkNetworkMixin
+from osn_selenium.webdrivers.sync.blink.features import BlinkFeaturesMixin
+from osn_selenium.webdrivers.sync.blink.settings import BlinkSettingsMixin
+from osn_selenium.webdrivers.sync.blink.lifecycle import BlinkLifecycleMixin
+from osn_selenium.abstract.webdriver.blink import (
+	AbstractBlinkWebDriver
+)
+
+
+__all__ = ["BlinkWebDriver"]
+
+
+class BlinkWebDriver(
+		BlinkBaseMixin,
+		BlinkCastingMixin,
+		BlinkFeaturesMixin,
+		BlinkLifecycleMixin,
+		BlinkLoggingMixin,
+		BlinkNetworkMixin,
+		BlinkSettingsMixin,
+		CoreWebDriver,
+		AbstractBlinkWebDriver
+):
+	"""
+	Concrete Blink WebDriver implementation combining all functional mixins.
+
+	This class aggregates lifecycle management, element interaction, navigation,
+	and browser-specific features into a single usable driver instance.
+	"""
+	
+	def __init__(
+			self,
+			browser_exe: Optional[PATH_TYPEHINT],
+			browser_name_in_system: str,
+			webdriver_path: str,
+			use_browser_exe: bool = True,
+			flags_manager_type: Type[BlinkFlagsManager] = BlinkFlagsManager,
+			flags: Optional[BlinkFlags] = None,
+			start_page_url: str = "",
+			implicitly_wait: int = 5,
+			page_load_timeout: int = 5,
+			script_timeout: int = 5,
+			window_rect: Optional[WindowRect] = None,
+			cdp_versioned_packages_paths: Optional[Mapping[int, PATH_TYPEHINT]] = None,
+			ignore_cdp_version_package_missing: bool = True,
+	):
+		"""
+		Initializes the BlinkWebDriver instance.
+
+		This constructor sets up the necessary components for controlling a Blink-based browser,
+		including paths, flag managers, timeouts, and integration with DevTools and Trio.
+		It also initializes properties related to console encoding and IP pattern matching
+		for managing browser processes.
+
+		Args:
+			browser_exe (Optional[PATH_TYPEHINT]): The path to the browser executable
+				(e.g., `chrome.exe` or `msedge.exe`). If None, the browser executable will not be
+				managed directly by this class (e.g., for remote WebDriver connections where the
+				browser is already running).
+			browser_name_in_system (str): The common name of the browser executable in the system
+				(e.g., "Chrome", "Edge"). Used to auto-detect `browser_exe` if `use_browser_exe` is True.
+			webdriver_path (str): The file path to the WebDriver executable (e.g., `chromedriver.exe`).
+			use_browser_exe (bool): If True, the browser executable path will be
+				automatically determined based on `browser_name_in_system` if `browser_exe`
+				is not explicitly provided. If False, `browser_exe` must be None.
+				Defaults to True.
+			flags_manager_type (Type[BlinkFlagsManager]): The type of flags manager to use.
+				Defaults to `BlinkFlagsManager`, which is suitable for Chrome/Edge.
+			flags (Optional[BlinkFlags]): Initial browser flags or options
+				specific to Blink-based browsers. Can be a `BlinkFlags` object or a generic mapping.
+				Defaults to None.
+			start_page_url (str): The URL that the browser will attempt to navigate to
+				immediately after starting. Defaults to an empty string.
+			implicitly_wait (int): The default implicit wait time in seconds for element searches.
+				Defaults to 5.
+			page_load_timeout (int): The default page load timeout in seconds. Defaults to 5.
+			script_timeout (int): The default asynchronous script timeout in seconds. Defaults to 5.
+			window_rect (Optional[WindowRect]): The initial window size and position. If None,
+				the browser's default window size will be used. Defaults to None.
+		"""
+		
+		CoreWebDriver.__init__(
+				self,
+				webdriver_path=webdriver_path,
+				flags_manager_type=flags_manager_type,
+				flags=flags,
+				implicitly_wait=implicitly_wait,
+				page_load_timeout=page_load_timeout,
+				script_timeout=script_timeout,
+				window_rect=window_rect,
+				cdp_versioned_packages_paths=cdp_versioned_packages_paths,
+				ignore_cdp_version_package_missing=ignore_cdp_version_package_missing,
+		)
+		
+		BlinkBaseMixin.__init__(
+				self,
+				browser_exe=browser_exe,
+				browser_name_in_system=browser_name_in_system,
+				use_browser_exe=use_browser_exe,
+				webdriver_path=webdriver_path,
+				architecture="sync",
+				flags_manager_type=flags_manager_type,
+				flags=flags,
+				start_page_url=start_page_url,
+				implicitly_wait=implicitly_wait,
+				page_load_timeout=page_load_timeout,
+				script_timeout=script_timeout,
+				window_rect=window_rect,
+				cdp_versioned_packages_paths=cdp_versioned_packages_paths,
+				ignore_cdp_version_package_missing=ignore_cdp_version_package_missing,
+		)