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

osn_selenium/dev_tools/_decorators.py

@@ -0,0 +1,149 @@
+import trio
+import inspect
+import warnings
+import functools
+from osn_selenium.exceptions.devtools import ExceptionThrown
+from osn_selenium.exceptions.instance import NotExpectedTypeError
+from osn_selenium.dev_tools._exception_helpers import log_exception
+from typing import (
+	Any,
+	Callable,
+	ParamSpec,
+	TYPE_CHECKING,
+	TypeVar,
+	Union
+)
+
+
+__all__ = ["background_task_decorator", "log_on_error", "warn_if_active"]
+
+if TYPE_CHECKING:
+	from osn_selenium.dev_tools.manager import DevTools
+	from osn_selenium.dev_tools.target.base import BaseMixin
+	from osn_selenium.dev_tools.target import DevToolsTarget
+	from osn_selenium.dev_tools._typehints import DEVTOOLS_BACKGROUND_FUNCTION_TYPEHINT
+
+_METHOD_INPUT = ParamSpec("_METHOD_INPUT")
+_METHOD_OUTPUT = TypeVar("_METHOD_OUTPUT")
+_METHOD = TypeVar("_METHOD", bound=Callable[..., Any])
+
+
+def warn_if_active(func: _METHOD) -> _METHOD:
+	"""
+	Decorator to warn if DevTools operations are attempted while DevTools is active.
+
+	This decorator is used to wrap methods in the DevTools class that should not be called
+	while the DevTools event handler context manager is active. It checks the `is_active` flag
+	of the DevTools instance. If DevTools is active, it issues a warning; otherwise, it proceeds
+	to execute the original method.
+
+	Args:
+		func (_METHOD): The function to be wrapped. This should be a method of the DevTools class.
+
+	Returns:
+		_METHOD: The wrapped function. When called, it will check if DevTools is active and either
+				  execute the original function or issue a warning.
+	"""
+	
+	@functools.wraps(func)
+	def sync_wrapper(
+			self: "DevTools",
+			*args: _METHOD_INPUT.args,
+			**kwargs: _METHOD_INPUT.kwargs
+	) -> Any:
+		if self.is_active:
+			warnings.warn("DevTools is active. Exit dev_tools context before changing settings.")
+		
+		return func(self, *args, **kwargs)
+	
+	@functools.wraps(func)
+	async def async_wrapper(
+			self: "DevTools",
+			*args: _METHOD_INPUT.args,
+			**kwargs: _METHOD_INPUT.kwargs
+	) -> Any:
+		if self.is_active:
+			warnings.warn("DevTools is active. Exit dev_tools context before changing settings.")
+		
+		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)
+
+
+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)
+
+
+def background_task_decorator(func: "DEVTOOLS_BACKGROUND_FUNCTION_TYPEHINT") -> "DEVTOOLS_BACKGROUND_FUNCTION_TYPEHINT":
+	"""
+	Decorator for target background tasks to manage their lifecycle.
+
+	This decorator wraps a target's background task function. It ensures that
+	`target.background_task_ended` event is set when the function completes,
+	allowing the `BaseTargetMixin` to track the task's termination.
+
+	Args:
+		func ("DEVTOOLS_BACKGROUND_FUNCTION_TYPEHINT"): The asynchronous background task function
+		to be wrapped. It should accept a target instance.
+
+	Returns:
+		"DEVTOOLS_BACKGROUND_FUNCTION_TYPEHINT": The wrapped function.
+	"""
+	
+	@functools.wraps(func)
+	async def wrapper(target: Union["BaseMixin", "DevToolsTarget"]) -> Any:
+		if not target.about_to_stop_event.is_set():
+			with trio.CancelScope() as cancel_scope:
+				target.cancel_scopes["background_task"] = cancel_scope
+		
+				try:
+					target.background_task_ended = trio.Event()
+		
+					await func(target)
+		
+					target.background_task_ended.set()
+				finally:
+					target.cancel_scopes.pop("background_task")
+	
+	return wrapper

osn_selenium/dev_tools/_exception_helpers.py

@@ -0,0 +1,116 @@
+import json
+import logging
+import traceback
+from typing import (
+	Any,
+	Dict,
+	List,
+	Optional
+)
+
+
+__all__ = ["extract_exception_trace", "log_exception"]
+
+
+def extract_exception_trace(exception: BaseException) -> str:
+	"""
+	Extracts a comprehensive traceback string for an exception, including handling for `ExceptionGroup`s.
+
+	This function recursively flattens `ExceptionGroup`s to ensure all nested exceptions
+	have their tracebacks included in the final output string.
+
+	Args:
+		exception (BaseException): The exception object to extract the trace from.
+
+	Returns:
+		str: A multi-line string containing the formatted traceback(s) for the given exception
+			 and any nested exceptions within an `ExceptionGroup`.
+
+	EXAMPLES
+	________
+	>>> try:
+	...	 raise ValueError("Simple error occurred")
+	... except ValueError as e:
+	...	 trace = extract_exception_trace(e)
+	...	 # The first line typically indicates the start of a traceback
+	...	 print(trace.splitlines()[0].strip())
+	>>> try:
+	...	 raise ExceptionGroup(
+	...		 "Multiple issues",
+	...		 [
+	...			 TypeError("Invalid type provided"),
+	...			 ValueError("Value out of range")
+	...		 ]
+	...	 )
+	... except ExceptionGroup as eg:
+	...	 trace = extract_exception_trace(eg)
+	...	 # Check if tracebacks for both nested exceptions are present
+	...	 print("TypeError" in trace and "ValueError" in trace)
+	"""
+	
+	def format_exception(exception_: BaseException) -> str:
+		"""
+		Formats a single exception's traceback into a string.
+
+		Args:
+			exception_ (BaseException): The exception to format.
+
+		Returns:
+			str: The formatted exception string.
+		"""
+		
+		return "".join(
+				traceback.format_exception(exception_.__class__, exception_, exception_.__traceback__)
+		)
+	
+	def flatten_exceptions(exception_: BaseException) -> List[BaseException]:
+		"""
+		Recursively flattens an ExceptionGroup into a List of individual exceptions.
+
+		Args:
+			exception_ (BaseException): The exception to flatten.
+
+		Returns:
+			List[BaseException]: A list of flattened exceptions.
+		"""
+		
+		if isinstance(exception_, ExceptionGroup):
+			inner_exceptions = exception_.exceptions
+		else:
+			return [exception_]
+		
+		result = []
+		
+		for exception__ in inner_exceptions:
+			result.extend(flatten_exceptions(exception__))
+		
+		return result
+	
+	return "\n".join(format_exception(exc) for exc in flatten_exceptions(exception))
+
+
+def log_exception(exception: BaseException, extra_data: Optional[Dict[str, Any]] = None):
+	"""
+	Logs the full traceback of an exception at the ERROR level.
+
+	This function uses `extract_exception_trace` to get a comprehensive traceback string
+	and then logs it using the standard logging module.
+
+	Args:
+		exception (BaseException): The exception object to log.
+		extra_data (Optional[Dict[str, Any]]): Additional data to log with the exception.
+	"""
+	
+	if extra_data is None:
+		exception_data = extract_exception_trace(exception)
+	else:
+		trace = extract_exception_trace(exception)
+		max_len = max(len(line) for line in trace.splitlines())
+	
+		exception_data = "{bound}\n{exception}\nWith extra data:\n{extra_data}\n{bound}".format(
+				bound="=" * max_len,
+				exception=trace,
+				extra_data=json.dumps(extra_data, indent=4, ensure_ascii=False)
+		)
+	
+	logging.log(logging.ERROR, exception_data)

osn_selenium/dev_tools/_functions.py

@@ -0,0 +1,174 @@
+import trio
+import random
+from typing import (
+	Any,
+	Callable,
+	Literal,
+	TYPE_CHECKING,
+	Union
+)
+from osn_selenium.exceptions.configuration import (
+	NotExpectedValueError
+)
+from osn_selenium.exceptions.devtools import (
+	CDPEndExceptions,
+	ExceptionThrown
+)
+
+
+__all__ = ["cdp_command_error", "execute_cdp_command", "wait_one"]
+
+if TYPE_CHECKING:
+	from osn_selenium.dev_tools.target.logging import LoggingMixin as LoggingTargetMixin
+
+
+async def wait_one(*events: trio.Event):
+	"""
+	Waits for the first of multiple Trio events to be set.
+
+	This function creates a nursery and starts a task for each provided event.
+	As soon as any event is set, it receives a signal, cancels the nursery,
+	and returns.
+
+	Args:
+		*events (trio.Event): One or more Trio Event objects to wait for.
+	"""
+	
+	async def waiter(event: trio.Event, send_chan_: trio.MemorySendChannel):
+		"""Internal helper to wait for an event and send a signal."""
+		
+		await event.wait()
+		await send_chan_.send(0)
+	
+	send_chan, receive_chan = trio.open_memory_channel(0)
+	
+	async with trio.open_nursery() as nursery:
+		for event_ in events:
+			nursery.start_soon(waiter, event_, send_chan.clone())
+	
+		await receive_chan.receive()
+		nursery.cancel_scope.cancel()
+
+
+async def cdp_command_error(
+		self: "LoggingTargetMixin",
+		error: BaseException,
+		error_mode: Literal["raise", "log", "log_without_args", "pass"],
+		command_name: str,
+		*args: Any,
+		**kwargs: Any,
+):
+	"""
+	Handles errors occurring during CDP command execution based on the specified error mode.
+
+	Args:
+		self ("LoggingTargetMixin"): The instance executing the command.
+		error (BaseException): The exception that was caught.
+		error_mode (Literal["raise", "log", "log_without_args", "pass"]): Strategy for handling the error.
+		command_name (str): Name of the CDP command that failed.
+		*args (Any): Positional arguments passed to the command.
+		**kwargs (Any): Keyword arguments passed to the command.
+
+	Returns:
+		Union[Any, ExceptionThrown]: Returns ExceptionThrown if not raising.
+
+	Raises:
+		BaseException: The original error if error_mode is "raise".
+		NotExpectedValueError: If an invalid error_mode is provided.
+	"""
+	
+	if error_mode == "raise":
+		raise error
+	
+	if error_mode == "log":
+		await self.log_cdp_error(
+				error=error,
+				extra_data={"cdp_command": command_name, "args": args, "kwargs": kwargs}
+		)
+	
+		return ExceptionThrown(exception=error)
+	
+	if error_mode == "log_without_args":
+		await self.log_cdp_error(error=error, extra_data={"cdp_command": command_name})
+	
+		return ExceptionThrown(exception=error)
+	
+	if error_mode == "pass":
+		return ExceptionThrown(exception=error)
+	
+	raise NotExpectedValueError(
+			value_name="error_mode",
+			value=error_mode,
+			valid_values=["raise", "log", "pass"]
+	)
+
+
+async def execute_cdp_command(
+		self: "LoggingTargetMixin",
+		function: Callable[..., Any],
+		cdp_error_mode: Literal["raise", "log", "log_without_args", "pass"] = "raise",
+		error_mode: Literal["raise", "log", "log_without_args", "pass"] = "raise",
+		command_retries: int = 0,
+		*args: Any,
+		**kwargs: Any,
+) -> Union[Any, ExceptionThrown]:
+	"""
+	Executes a Chrome DevTools Protocol (CDP) command with specified error handling.
+
+	This function attempts to execute a CDP command via the `cdp_session`.
+	It provides different behaviors based on the `error_mode` if an exception occurs:
+	- "raise": Re-raises the exception immediately.
+	- "log": Logs the exception using the target's logger and returns an `ExceptionThrown` object.
+	- "pass": Returns an `ExceptionThrown` object without logging the exception.
+
+	Args:
+		self ("LoggingTargetMixin"): The `LoggingTargetMixin` instance through which the command is executed.
+		function (Callable[..., Any]): The CDP command function to execute (e.g., `devtools.page.navigate`).
+		cdp_error_mode (Literal["raise", "log", "log_without_args", "pass"]): Strategy for connection errors.
+		error_mode (Literal["raise", "log", "log_without_args", "pass"]): Strategy for general execution errors.
+		command_retries (int): Number of times to retry the command on failure.
+		*args (Any): Positional arguments to pass to the CDP command function.
+		**kwargs (Any): Keyword arguments to pass to the CDP command function.
+
+	Returns:
+		Union[Any, ExceptionThrown]: The result of the CDP command if successful,
+			or an `ExceptionThrown` object if an error occurred and `error_mode` is "log" or "pass".
+
+	Raises:
+		CDPEndExceptions: If a CDP-related connection error occurs, these are always re-raised.
+		BaseException: If `error_mode` is "raise" and any other exception occurs.
+		ValueError: If an unknown `error_mode` is provided.
+	"""
+	
+	try:
+		await self.log_cdp(
+				level="DEBUG",
+				message=f"Executing CDP command: {function.__name__}",
+				extra_data={"args": args, "kwargs": kwargs}
+		)
+	
+		for i in range(command_retries):
+			try:
+				return await self.cdp_session.execute(function(*args, **kwargs))
+			except* (BaseException,):
+				await trio.sleep(random.uniform(0.5, 1.5))
+	
+		return await self.cdp_session.execute(function(*args, **kwargs))
+	except CDPEndExceptions as error:
+		return await cdp_command_error(
+				self=self,
+				error=error,
+				error_mode=cdp_error_mode,
+				command_name=function.__name__,
+				*args,
+				**kwargs
+		)
+	except BaseException as error:
+		return await cdp_command_error(
+				self=self,
+				error=error,
+				error_mode=error_mode,
+				command_name=function.__name__,
+				*args,
+				**kwargs
+		)

osn_selenium/dev_tools/_system_utils.py

@@ -0,0 +1,35 @@
+import shutil
+from pathlib import Path
+from osn_selenium.dev_tools.settings import LoggerSettings
+
+
+__all__ = ["prepare_log_dir"]
+
+
+def prepare_log_dir(logger_settings: LoggerSettings):
+	"""
+	Prepares the log directory based on the provided logger settings.
+
+	If `log_dir_path` is specified:
+	- Creates the directory if it doesn't exist.
+	- If `renew_log` is True and the directory exists, it is cleared (recreated).
+
+	Args:
+		logger_settings (LoggerSettings): The settings object containing log directory configuration.
+
+	Raises:
+		ValueError: If `log_dir_path` is provided but is not a valid `Path` object
+					or does not represent a directory.
+	"""
+	
+	if isinstance(logger_settings.dir_path, Path) and (logger_settings.dir_path.is_dir() or not logger_settings.dir_path.exists()):
+		if not logger_settings.dir_path.exists():
+			logger_settings.dir_path.mkdir(parents=True)
+		elif logger_settings.renew_log:
+			shutil.rmtree(logger_settings.dir_path)
+	
+			logger_settings.dir_path.mkdir()
+	elif logger_settings.dir_path is not None:
+		raise ValueError(
+				f"'log_dir_path' must be a pathlib.Path to directory or None, got {logger_settings.dir_path} (type: {type(logger_settings.dir_path).__name__})"
+		)

osn_selenium/dev_tools/_typehints.py

@@ -0,0 +1,35 @@
+from typing import (
+	Any,
+	Callable,
+	Coroutine,
+	Literal,
+	TYPE_CHECKING,
+	Union
+)
+
+
+__all__ = [
+	"CDP_LOG_LEVELS_TYPEHINT",
+	"DEVTOOLS_BACKGROUND_FUNCTION_TYPEHINT",
+	"FINGERPRINT_LOG_LEVELS_TYPEHINT"
+]
+
+if TYPE_CHECKING:
+	from osn_selenium.dev_tools.target.base import BaseMixin as BaseTargetMixin
+	from osn_selenium.dev_tools.target import DevToolsTarget
+else:
+	BaseTargetMixin = Any
+	DevToolsTarget = Any
+
+DEVTOOLS_BACKGROUND_FUNCTION_TYPEHINT = Callable[[Union[BaseTargetMixin, DevToolsTarget]], Coroutine[Any, Any, None]]
+
+CDP_LOG_LEVELS_TYPEHINT = Literal[
+	"INFO",
+	"ERROR",
+	"DEBUG",
+	"WARNING",
+	"RequestPaused",
+	"AuthRequired",
+	"Building Kwargs"
+]
+FINGERPRINT_LOG_LEVELS_TYPEHINT = Literal["Detect"]