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

osn_selenium/_base_models.py

@@ -0,0 +1,41 @@
+from pydantic import (
+	BaseModel,
+	ConfigDict
+)
+
+
+__all__ = ["DictModel", "ExtraDictModel"]
+
+
+class ExtraDictModel(BaseModel):
+	"""
+	Base class for Pydantic models that allows extra fields.
+
+	This configuration allows the model to accept fields that are not
+	explicitly defined in the model's schema.
+	"""
+	
+	model_config = ConfigDict(
+			populate_by_name=True,
+			extra="allow",
+			use_enum_values=True,
+			str_strip_whitespace=True,
+			validate_assignment=True,
+	)
+
+
+class DictModel(BaseModel):
+	"""
+	Base class for Pydantic models with a predefined configuration.
+
+	This configuration enforces strict validation rules such as forbidding extra
+	fields and stripping whitespace from string inputs.
+	"""
+	
+	model_config = ConfigDict(
+			populate_by_name=True,
+			extra="forbid",
+			use_enum_values=True,
+			str_strip_whitespace=True,
+			validate_assignment=True,
+	)

osn_selenium/_cdp_import.py

@@ -0,0 +1,253 @@
+import re
+import sys
+import pathlib
+import importlib.util
+import urllib.request
+from types import ModuleType
+from datetime import datetime, timedelta
+from importlib.abc import MetaPathFinder
+from importlib.machinery import ModuleSpec
+from osn_selenium._typehints import PATH_TYPEHINT
+from typing import (
+	Dict,
+	Mapping,
+	Optional,
+	Sequence,
+	Tuple,
+	Union
+)
+
+
+__all__ = ["check_cdp_version_exists_on_github", "install_cdp_hook"]
+
+_SELENIUM_CDP_PATTERN = re.compile(r"selenium\.webdriver\.common\.devtools\.v(\d+)(.*)")
+_INTERNAL_CDP_PATTERN = re.compile(r"osn_selenium_cdp_v(\d+)(?!\.legacy)(.*)")
+
+_GITHUB_VERSIONS_CACHE: Dict[str, Tuple[bool, datetime]] = {}
+_CDP_PACKAGE_ERROR = None
+
+
+def _build_cdp_package_error(version: int) -> Exception:
+	"""
+	Creates an instance of the CDPPackageError exception.
+
+	Args:
+		version (int): The version of the CDP package.
+
+	Returns:
+		Exception: An instance of the CDPPackageError.
+	"""
+	
+	global _CDP_PACKAGE_ERROR
+	
+	if _CDP_PACKAGE_ERROR is None:
+		from osn_selenium.exceptions.dependencies import CDPPackageError
+		_CDP_PACKAGE_ERROR = CDPPackageError
+	
+	return _CDP_PACKAGE_ERROR(version=version)
+
+
+def _get_external_spec(fullname: str, root_path: pathlib.Path, submodule_part: str) -> Optional[ModuleSpec]:
+	"""
+	Creates a module spec for an external path.
+
+	Args:
+		fullname (str): The full name of the module.
+		root_path (pathlib.Path): The root directory where the module is located.
+		submodule_part (str): The part of the name representing submodules.
+
+	Returns:
+		Optional[ModuleSpec]: The module spec if found, otherwise None.
+	"""
+	
+	if not submodule_part:
+		target_path = root_path / "__init__.py"
+		is_package = True
+	else:
+		rel_path = submodule_part.lstrip(".").replace(".", "/")
+		target_path = root_path / f"{rel_path}.py"
+	
+		if not target_path.exists():
+			target_path = root_path / rel_path / "__init__.py"
+			is_package = True
+		else:
+			is_package = False
+	
+	if target_path.exists():
+		spec = importlib.util.spec_from_file_location(
+				name=fullname,
+				location=str(target_path),
+				submodule_search_locations=[str(root_path)]
+				if is_package
+				else None
+		)
+	
+		return spec
+	
+	return None
+
+
+class _CdpMetaPathFinder(MetaPathFinder):
+	"""
+	A custom meta path finder to redirect Selenium CDP imports.
+	"""
+	
+	def __init__(
+			self,
+			cdp_paths: Optional[Mapping[int, PATH_TYPEHINT]] = None,
+			ignore_package_missing: bool = True
+	) -> None:
+		"""
+		Initializes the finder with user-defined CDP paths.
+
+		Args:
+			cdp_paths (Optional[Mapping[int, PATH_TYPEHINT]]): Mapping of versions to paths.
+			ignore_package_missing (bool): Whether to ignore missing package errors.
+		"""
+		
+		self._user_cdp_paths = {k: pathlib.Path(v).resolve() for k, v in (cdp_paths or {}).items()}
+		
+		self._ignore_package_missing = ignore_package_missing
+	
+	def _find_spec_bypassing_self(self, fullname: str, path: Optional[Sequence[str]]) -> Optional[ModuleSpec]:
+		"""
+		Attempts to find the module specification using other finders in sys.meta_path.
+
+		Args:
+			fullname (str): The full name of the module.
+			path (Optional[Sequence[str]]): The search path for the module.
+
+		Returns:
+			Optional[ModuleSpec]: The module spec if found, otherwise None.
+		"""
+		
+		for finder in sys.meta_path:
+			if finder is self:
+				continue
+		
+			try:
+				if hasattr(finder, "find_spec"):
+					spec = finder.find_spec(fullname, path)
+		
+					if spec:
+						return spec
+			except (Exception,):
+				continue
+		
+		return None
+	
+	def find_spec(
+			self,
+			fullname: str,
+			path: Optional[Sequence[str]],
+			target: Optional[ModuleType] = None,
+	) -> Optional[ModuleSpec]:
+		"""
+		Finds the specification for the requested module if it matches the CDP pattern.
+
+		Args:
+			fullname (str): The full name of the module to find.
+			path (Optional[Sequence[str]]): The search path for the module.
+			target (Optional[ModuleType]): The module object if it is being reloaded.
+
+		Returns:
+			Optional[ModuleSpec]: The module spec if found, otherwise None.
+		"""
+		
+		selenium_match = _SELENIUM_CDP_PATTERN.match(fullname)
+		internal_match = _INTERNAL_CDP_PATTERN.match(fullname)
+		
+		if not (selenium_match or internal_match):
+			return None
+		
+		match = selenium_match or internal_match
+		version_part = int(match.group(1))
+		submodule_part = match.group(2)
+		
+		user_cdp_path = self._user_cdp_paths.get(version_part, None)
+		if user_cdp_path is not None:
+			root = (user_cdp_path / "legacy") if selenium_match else user_cdp_path
+			return _get_external_spec(fullname=fullname, root_path=root, submodule_part=submodule_part)
+		
+		spec = None
+		
+		if selenium_match:
+			target_name = f"osn_selenium_cdp_v{version_part}.legacy{submodule_part}"
+			spec = importlib.util.find_spec(target_name, path)
+		
+		if internal_match:
+			target_name = f"osn_selenium_cdp_v{version_part}{submodule_part}"
+			spec = self._find_spec_bypassing_self(target_name, path)
+		
+		try:
+			if spec:
+				return importlib.util.spec_from_file_location(
+						name=fullname,
+						location=spec.origin,
+						submodule_search_locations=spec.submodule_search_locations,
+				)
+		except ModuleNotFoundError:
+			if self._ignore_package_missing:
+				return None
+		
+			raise _build_cdp_package_error(version=version_part)
+		
+		return None
+
+
+def install_cdp_hook(
+		cdp_paths: Optional[Mapping[int, PATH_TYPEHINT]] = None,
+		ignore_package_missing: bool = True,
+) -> None:
+	"""
+	Installs the CDP meta path finder into sys.meta_path.
+
+	Args:
+		cdp_paths (Optional[Mapping[int, PATH_TYPEHINT]]): Mapping of versions to custom local paths.
+		ignore_package_missing (bool): Whether to ignore missing package errors.
+	"""
+	
+	for finder in sys.meta_path:
+		if isinstance(finder, _CdpMetaPathFinder):
+			finder._user_cdp_paths.update({k: pathlib.Path(v).resolve() for k, v in (cdp_paths or {}).items()})
+			finder._ignore_package_missing = ignore_package_missing
+	
+			return
+	
+	sys.meta_path.insert(
+			0,
+			_CdpMetaPathFinder(cdp_paths=cdp_paths, ignore_package_missing=ignore_package_missing)
+	)
+
+
+def check_cdp_version_exists_on_github(version: Union[int, str]) -> bool:
+	"""
+	Checks if a specific CDP version exists in the remote repository.
+
+	Args:
+		version (Union[int, str]): The version of package.
+
+	Returns:
+		bool: True if the version exists, False otherwise.
+	"""
+	
+	branch_name = version if isinstance(version, str) else f"v{version}"
+	
+	cached_answer = _GITHUB_VERSIONS_CACHE.get(branch_name, None)
+	if cached_answer and datetime.now() - cached_answer[1] < timedelta(hours=12):
+		return cached_answer[0]
+	
+	repo_url = f"https://api.github.com/repos/oddshellnick/osn-selenium-cdp/branches/{branch_name}"
+	
+	try:
+		request = urllib.request.Request(url=repo_url, headers={"User-Agent": "osn-selenium"})
+		request.get_method = lambda: "HEAD"
+	
+		with urllib.request.urlopen(url=request, timeout=5.0) as response:
+			existing = response.status == 200
+			_GITHUB_VERSIONS_CACHE[branch_name] = (existing, datetime.now())
+	
+			return existing
+	except (Exception,):
+		_GITHUB_VERSIONS_CACHE[branch_name] = (False, datetime.now())
+		return False

osn_selenium/_decorators.py

@@ -0,0 +1,57 @@
+import inspect
+import functools
+from osn_selenium.exceptions.base import ExceptionThrown
+from osn_selenium._exception_helpers import log_exception
+from typing import (
+	Any,
+	Callable,
+	ParamSpec,
+	TypeVar
+)
+from osn_selenium.exceptions.instance import NotExpectedTypeError
+
+
+__all__ = ["log_on_error"]
+
+_METHOD_INPUT = ParamSpec("_METHOD_INPUT")
+_METHOD_OUTPUT = TypeVar("_METHOD_OUTPUT")
+_METHOD = TypeVar("_METHOD", bound=Callable[..., Any])
+
+
+def log_on_error(func: _METHOD) -> _METHOD:
+	"""
+	Decorator that logs any `BaseException` raised by the decorated async function.
+
+	If an exception occurs, it is logged using `log_exception`, and an `ExceptionThrown`
+	object wrapping the exception is returned instead of re-raising it.
+
+	Args:
+		func (_METHOD): The asynchronous function to be wrapped.
+
+	Returns:
+		_METHOD: The wrapped asynchronous function.
+	"""
+	
+	@functools.wraps(func)
+	def sync_wrapper(*args: _METHOD_INPUT.args, **kwargs: _METHOD_INPUT.kwargs) -> _METHOD_OUTPUT:
+		try:
+			return func(*args, **kwargs)
+		except BaseException as exception:
+			log_exception(exception)
+			return ExceptionThrown(exception)
+	
+	@functools.wraps(func)
+	async def async_wrapper(*args: _METHOD_INPUT.args, **kwargs: _METHOD_INPUT.kwargs) -> _METHOD_OUTPUT:
+		try:
+			return await func(*args, **kwargs)
+		except BaseException as exception:
+			log_exception(exception)
+			return ExceptionThrown(exception)
+	
+	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/_trio_threads_helpers.py

@@ -0,0 +1,157 @@
+import sys
+import trio
+import contextvars
+from contextlib import asynccontextmanager
+from typing import (
+	Any,
+	AsyncContextManager,
+	AsyncIterator,
+	Callable,
+	ContextManager,
+	Coroutine,
+	ParamSpec,
+	Tuple,
+	TypeVar
+)
+
+
+__all__ = ["sync_to_trio", "sync_to_trio_context"]
+
+_METHOD_INPUT = ParamSpec("_METHOD_INPUT")
+_METHOD_OUTPUT = TypeVar("_METHOD_OUTPUT")
+
+
+def sync_to_trio_context(
+		context_manager_factory: Callable[_METHOD_INPUT, ContextManager[_METHOD_OUTPUT]],
+		lock_object: trio.Lock,
+		capacity_limiter_object: trio.CapacityLimiter,
+		lock: bool,
+		exchange_context: bool,
+) -> Callable[_METHOD_INPUT, AsyncContextManager[_METHOD_OUTPUT]]:
+	"""
+	Converts a synchronous context manager factory to an asynchronous Trio-compatible context manager.
+
+	Args:
+		context_manager_factory (Callable[_METHOD_INPUT, ContextManager[_METHOD_OUTPUT]]): Factory function returning a context manager.
+		lock_object (trio.Lock): Trio lock for synchronization.
+		capacity_limiter_object (trio.CapacityLimiter): Trio capacity limiter.
+		lock (bool): Whether to use the internal lock for synchronization.
+		exchange_context (bool): Whether to synchronize context variables between threads.
+
+	Returns:
+		Callable[_METHOD_INPUT, AsyncContextManager[_METHOD_OUTPUT]]: An async function returning an async context manager.
+	"""
+	
+	@asynccontextmanager
+	async def wrapper(*args: _METHOD_INPUT.args, **kwargs: _METHOD_INPUT.kwargs) -> AsyncIterator[_METHOD_OUTPUT]:
+		"""
+		Internal async context manager wrapper.
+
+		Args:
+			*args (_METHOD_INPUT.args): Positional arguments for the factory.
+			**kwargs (_METHOD_INPUT.kwargs): Keyword arguments for the factory.
+
+		Returns:
+			AsyncIterator[_METHOD_OUTPUT]: An async iterator yielding the context resource.
+		"""
+		
+		sync_context_manager = await sync_to_trio(
+				sync_function=context_manager_factory,
+				lock_object=lock_object,
+				capacity_limiter_object=capacity_limiter_object,
+				lock=lock,
+				exchange_context=exchange_context,
+		)(*args, **kwargs)
+		
+		enter_ = sync_to_trio(
+				sync_function=sync_context_manager.__enter__,
+				lock_object=lock_object,
+				capacity_limiter_object=capacity_limiter_object,
+				lock=lock,
+				exchange_context=exchange_context,
+		)
+		exit_ = sync_to_trio(
+				sync_function=sync_context_manager.__exit__,
+				lock_object=lock_object,
+				capacity_limiter_object=capacity_limiter_object,
+				lock=lock,
+				exchange_context=exchange_context,
+		)
+		
+		try:
+			result = await enter_()
+		
+			yield result
+		except Exception as e:
+			exc_type, exc_val, exc_tb = sys.exc_info()
+		
+			if not await exit_(exc_type, exc_val, exc_tb):
+				raise e
+		else:
+			await exit_(None, None, None)
+	
+	return wrapper
+
+
+def sync_to_trio(
+		sync_function: Callable[_METHOD_INPUT, _METHOD_OUTPUT],
+		lock_object: trio.Lock,
+		capacity_limiter_object: trio.CapacityLimiter,
+		lock: bool,
+		exchange_context: bool,
+) -> Callable[_METHOD_INPUT, Coroutine[Any, Any, _METHOD_OUTPUT]]:
+	"""
+	Wraps a synchronous function to run within a Trio thread pool using a lock and limiter.
+
+	Args:
+		sync_function (Callable[_METHOD_INPUT, _METHOD_OUTPUT]): The synchronous function to wrap.
+		lock_object (trio.Lock): Trio lock for synchronization.
+		capacity_limiter_object (trio.CapacityLimiter): Trio capacity limiter.
+		lock (bool): Whether to use the provided lock.
+		exchange_context (bool): Whether to synchronize context variables between threads.
+
+	Returns:
+		Callable[_METHOD_INPUT, Coroutine[Any, Any, _METHOD_OUTPUT]]: An async wrapper for the sync function.
+	"""
+	
+	async def wrapper(*args: _METHOD_INPUT.args, **kwargs: _METHOD_INPUT.kwargs) -> _METHOD_OUTPUT:
+		"""
+	Internal async wrapper for the synchronous function.
+
+	Args:
+		*args (_METHOD_INPUT.args): Positional arguments for the sync function.
+		**kwargs (_METHOD_INPUT.kwargs): Keyword arguments for the sync function.
+
+	Returns:
+		_METHOD_OUTPUT: The result of the synchronous function execution.
+	"""
+		
+		def function_with_kwargs(*args_) -> Tuple[_METHOD_OUTPUT, contextvars.Context]:
+			"""
+		Helper to pass keyword arguments to trio.to_thread.run_sync.
+
+		Args:
+			*args_: Positional arguments passed from the outer scope.
+
+		Returns:
+			Tuple[_METHOD_OUTPUT, contextvars.Context]: Result of original sync function and the thread context.
+		"""
+			
+			sync_result = sync_function(*args_, **kwargs)
+			context_vars = contextvars.copy_context()
+			
+			return sync_result, context_vars
+		
+		if lock:
+			async with lock_object:
+				result, child_context_vars = await trio.to_thread.run_sync(function_with_kwargs, *args, limiter=capacity_limiter_object)
+		else:
+			result, child_context_vars = await trio.to_thread.run_sync(function_with_kwargs, *args, limiter=capacity_limiter_object)
+		
+		if exchange_context:
+			for var, value in child_context_vars.items():
+				var.set(value)
+		
+		return result
+	
+	return wrapper

osn_selenium/_typehints.py

@@ -14,6 +14,6 @@ __all__ = [
 ]
 
 DEVICES_TYPEHINT = Union[PointerInput, KeyInput, WheelInput]
-ARCHITECTURES_TYPEHINT = Literal["sync", "trio_threads"]
+ARCHITECTURES_TYPEHINT = Literal["sync", "trio_threads", "trio_bidi"]
 PATH_TYPEHINT = Union[str, bytes, pathlib.Path, os.PathLike]
 TYPES_FOR_FLATTENING_TYPEHINT = Union[str, Type]

osn_selenium/abstract/executors/cdp.py

@@ -0,0 +1,63 @@
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+
+__all__ = ["AbstractCDPExecutor"]
+
+if TYPE_CHECKING:
+	from osn_selenium_cdp_v140.executors.abstract import AbstractCDP140Executor
+	from osn_selenium_cdp_v141.executors.abstract import AbstractCDP141Executor
+	from osn_selenium_cdp_v142.executors.abstract import AbstractCDP142Executor
+	from osn_selenium_cdp_v143.executors.abstract import AbstractCDP143Executor
+	from osn_selenium_cdp_v144.executors.abstract import AbstractCDP144Executor
+
+
+class AbstractCDPExecutor(ABC):
+	"""
+	Global abstract interface for accessing different versions of CDP.
+	"""
+
+	@property
+	@abstractmethod
+	def v140(self) -> "AbstractCDP140Executor":
+		"""
+		Access CDP version 140 interface.
+		"""
+
+		...
+
+	@property
+	@abstractmethod
+	def v141(self) -> "AbstractCDP141Executor":
+		"""
+		Access CDP version 141 interface.
+		"""
+
+		...
+
+	@property
+	@abstractmethod
+	def v142(self) -> "AbstractCDP142Executor":
+		"""
+		Access CDP version 142 interface.
+		"""
+
+		...
+
+	@property
+	@abstractmethod
+	def v143(self) -> "AbstractCDP143Executor":
+		"""
+		Access CDP version 143 interface.
+		"""
+
+		...
+
+	@property
+	@abstractmethod
+	def v144(self) -> "AbstractCDP144Executor":
+		"""
+		Access CDP version 144 interface.
+		"""
+
+		...

osn_selenium/abstract/webdriver/blink/base.py

@@ -2,6 +2,7 @@ from abc import abstractmethod
 from selenium import webdriver
 from typing import Optional, Union
 from osn_selenium._typehints import PATH_TYPEHINT
+from osn_selenium.abstract.executors.cdp import AbstractCDPExecutor
 from osn_selenium.abstract.webdriver.core.base import (
 	AbstractCoreBaseMixin
 )
@@ -31,6 +32,19 @@ class AbstractBlinkBaseMixin(AbstractCoreBaseMixin):
 		
 		...
 	
+	@property
+	@abstractmethod
+	def cdp(self) -> AbstractCDPExecutor:
+		"""
+		Returns the CDP (Chrome DevTools Protocol) executor.
+
+		Returns:
+			AbstractCDPExecutor: The CDP executor instance used for sending
+			commands directly to the browser via the DevTools protocol.
+		"""
+		
+		...
+	
 	@property
 	@abstractmethod
 	def debugging_ip(self) -> Optional[str]:

osn_selenium/abstract/webdriver/blink/lifecycle.py

@@ -19,14 +19,6 @@ class AbstractBlinkLifecycleMixin(AbstractCoreLifecycleMixin):
 	and the associated browser process.
 	"""
 	
-	@abstractmethod
-	async def close_webdriver(self) -> None:
-		"""
-		Closes the WebDriver connection and terminates the browser process.
-		"""
-		
-		...
-	
 	@abstractmethod
 	async def restart_webdriver(
 			self,
@@ -74,3 +66,11 @@ class AbstractBlinkLifecycleMixin(AbstractCoreLifecycleMixin):
 		"""
 		
 		...
+	
+	@abstractmethod
+	async def stop_webdriver(self) -> None:
+		"""
+		Stops the WebDriver connection and terminates the browser process.
+		"""
+		
+		...

osn_selenium/abstract/webdriver/core/base.py

@@ -11,7 +11,6 @@ from osn_selenium._typehints import (
 	ARCHITECTURES_TYPEHINT
 )
 from selenium.webdriver.remote.errorhandler import ErrorHandler
-from osn_selenium.abstract.executors.cdp import AbstractCDPExecutor
 from selenium.webdriver.remote.locator_converter import LocatorConverter
 from selenium.webdriver.remote.remote_connection import RemoteConnection
 from osn_selenium.abstract.executors.javascript import AbstractJSExecutor
@@ -90,19 +89,6 @@ class AbstractCoreBaseMixin(ABC):
 		
 		...
 	
-	@property
-	@abstractmethod
-	def cdp(self) -> AbstractCDPExecutor:
-		"""
-		Returns the CDP (Chrome DevTools Protocol) executor.
-
-		Returns:
-			AbstractCDPExecutor: The CDP executor instance used for sending
-			commands directly to the browser via the DevTools protocol.
-		"""
-		
-		...
-	
 	@property
 	@abstractmethod
 	def command_executor(self) -> RemoteConnection:

osn_selenium/abstract/webdriver/core/capture.py

@@ -1,5 +1,6 @@
-from typing import Any, Optional
+from typing import Optional
 from abc import ABC, abstractmethod
+from selenium.webdriver.common.print_page_options import PrintOptions
 
 
 __all__ = ["AbstractCoreCaptureMixin"]
@@ -56,12 +57,12 @@ class AbstractCoreCaptureMixin(ABC):
 		...
 	
 	@abstractmethod
-	def print_page(self, print_options: Optional[Any] = None) -> str:
+	def print_page(self, print_options: Optional[PrintOptions] = None) -> str:
 		"""
 		Prints the current page to a PDF.
 
 		Args:
-			print_options (Optional[Any]): Options for printing the page.
+			print_options (Optional[PrintOptions]): Options for printing the page.
 
 		Returns:
 			str: A base64-encoded string of the PDF.