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

osn_selenium/dev_tools/utils.py

@@ -1,509 +0,0 @@
-import trio
-import shutil
-import logging
-import warnings
-import traceback
-import functools
-from pathlib import Path
-from dataclasses import dataclass
-from osn_selenium.dev_tools.errors import cdp_end_exceptions
-from osn_selenium.dev_tools._types import (
-	devtools_background_func_type
-)
-from typing import (
-	Any,
-	Callable,
-	Iterable,
-	Literal,
-	Optional,
-	TYPE_CHECKING,
-	Union
-)
-
-
-if TYPE_CHECKING:
-	from osn_selenium.dev_tools.logger import LoggerSettings
-	from osn_selenium.dev_tools.manager import DevTools, DevToolsTarget
-
-
-def warn_if_active(func: Callable) -> Callable:
-	"""
-	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 (Callable): The function to be wrapped. This should be a method of the DevTools class.
-
-	Returns:
-		Callable: 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 wrapper(self: "DevTools", *args: Any, **kwargs: Any) -> Any:
-		if self.is_active:
-			warnings.warn("DevTools is active. Exit dev_tools context before changing settings.")
-		
-		return func(self, *args, **kwargs)
-	
-	return wrapper
-
-
-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()
-
-
-def log_on_error(func: Callable) -> Callable:
-	"""
-	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 (Callable): The asynchronous function to be wrapped.
-
-	Returns:
-		Callable: The wrapped asynchronous function.
-	"""
-	
-	@functools.wraps(func)
-	async def wrapper(*args: Any, **kwargs: Any) -> Any:
-		try:
-			return await func(*args, **kwargs)
-		except BaseException as exception:
-			log_exception(exception)
-			return ExceptionThrown(exception)
-	
-	return wrapper
-
-
-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 flatten_exceptions(exception_: BaseException) -> list[BaseException]:
-		"""Recursively flattens an ExceptionGroup into a list of individual 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
-	
-	def format_exception(exception_: BaseException) -> str:
-		"""Formats a single exception's traceback into a string."""
-		
-		return "".join(
-				traceback.format_exception(exception_.__class__, exception_, exception_.__traceback__)
-		)
-	
-	return "\n".join(format_exception(exc) for exc in flatten_exceptions(exception))
-
-
-def log_exception(exception: BaseException):
-	"""
-	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.
-	"""
-	
-	logging.log(logging.ERROR, extract_exception_trace(exception))
-
-
-class ExceptionThrown:
-	"""
-	A wrapper class to indicate that an exception was thrown during an operation.
-
-	This is used in `execute_cdp_command` when `error_mode` is "log" or "pass"
-	to return an object indicating an error occurred without re-raising it immediately.
-
-	Attributes:
-		exception (BaseException): The exception that was caught.
-		traceback (str): The formatted traceback string of the exception.
-	"""
-	
-	def __init__(self, exception: BaseException):
-		"""
-		Initializes the ExceptionThrown wrapper.
-
-		Args:
-			exception (BaseException): The exception to wrap.
-		"""
-		
-		self.exception = exception
-		self.traceback = extract_exception_trace(exception)
-
-
-async def execute_cdp_command(
-		self: "DevToolsTarget",
-		error_mode: Literal["raise", "log", "pass"],
-		function: Callable[..., Any],
-		*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 ("DevToolsTarget"): The `DevToolsTarget` instance through which the command is executed.
-		error_mode (Literal["raise", "log", "pass"]): Defines how exceptions are handled.
-			"raise": Re-raises the exception.
-			"log": Logs the exception and returns `ExceptionThrown`.
-			"pass": Returns `ExceptionThrown` without logging.
-		function (Callable[..., Any]): The CDP command function to execute (e.g., `devtools.page.navigate`).
-		*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:
-		cdp_end_exceptions: 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:
-		return await self.cdp_session.execute(function(*args, **kwargs))
-	except cdp_end_exceptions as error:
-		raise error
-	except BaseException as error:
-		if error_mode == "raise":
-			raise error
-		elif error_mode == "log":
-			await self.log_error(error=error)
-			return ExceptionThrown(exception=error)
-		elif error_mode == "pass":
-			return ExceptionThrown(exception=error)
-		else:
-			raise ValueError(f"Wrong error_mode: {error_mode}. Expected: 'raise', 'log', 'pass'.")
-
-
-def _validate_log_filter(
-		filter_mode: Literal["include", "exclude"],
-		log_filter: Optional[Union[Any, Iterable[Any]]]
-) -> Callable[[Any], bool]:
-	"""
-	Creates a callable filter function based on the specified filter mode and values.
-
-	This function generates a lambda that can be used to check if a given log level
-	or target type should be processed, based on whether the filter is set to
-	"include" (only process items in the filter) or "exclude" (process all items
-	except those in the filter).
-
-	Args:
-		filter_mode (Literal["include", "exclude"]): The mode of the filter.
-			"include" means only items present in `log_filter` will pass.
-			"exclude" means all items except those present in `log_filter` will pass.
-		log_filter (Optional[Union[Any, Sequence[Any]]]):
-			A single log filter item or a sequence of such items.
-			If None:
-				- In "include" mode, the generated filter will always return False (nothing is included).
-				- In "exclude" mode, the generated filter will always return True (nothing is excluded).
-
-	Returns:
-		Callable[[Any], bool]: A callable function that takes a single argument (e.g., a log level or target type)
-			and returns True if it passes the filter, False otherwise.
-
-	Raises:
-		ValueError: If `filter_mode` is invalid.
-
-	EXAMPLES
-	________
-	>>> # Example 1: Include only "INFO" logs
-	... info_only_filter = _validate_log_filter("include", "INFO")
-	... print(info_only_filter("INFO"))	# True
-	... print(info_only_filter("ERROR"))   # False
-
-	>>> # Example 2: Exclude "DEBUG" and "WARNING" logs
-	... no_debug_warning_filter = _validate_log_filter("exclude", ["DEBUG", "WARNING"])
-	... print(no_debug_warning_filter("INFO"))	# True
-	... print(no_debug_warning_filter("DEBUG"))   # False
-
-	>>> # Example 3: No filter (exclude mode, so everything passes)
-	... all_logs_filter = _validate_log_filter("exclude", None)
-	... print(all_logs_filter("INFO"))	 # True
-	... print(all_logs_filter("ERROR"))	# True
-
-	>>> # Example 4: No filter (include mode, so nothing passes)
-	... no_logs_filter = _validate_log_filter("include", None)
-	... print(no_logs_filter("INFO"))	  # False
-	... print(no_logs_filter("ERROR"))	 # False
-	"""
-	
-	if log_filter is None:
-		if filter_mode == "include":
-			return lambda x: False
-		elif filter_mode == "exclude":
-			return lambda x: True
-	
-		raise ValueError(f"Invalid log filter_mode ({filter_mode}).")
-	
-	if isinstance(log_filter, Iterable):
-		if filter_mode == "include":
-			return lambda x: x in log_filter
-		elif filter_mode == "exclude":
-			return lambda x: x not in log_filter
-	
-		raise ValueError(f"Invalid log filter_mode ({filter_mode}).")
-	
-	if filter_mode == "include":
-		return lambda x: x == log_filter
-	elif filter_mode == "exclude":
-		return lambda x: x != log_filter
-	
-	raise ValueError(f"Invalid log filter_mode ({filter_mode}).")
-
-
-def _validate_type_filter(
-		type_: str,
-		filter_mode: Literal["include", "exclude"],
-		filter_instances: Any
-):
-	"""
-	Validates a target type against a given filter mode and filter instances.
-
-	This is a wrapper around `_validate_log_filter` specifically for target types.
-
-	Args:
-		type_ (str): The target type string to check (e.g., "page", "iframe").
-		filter_mode (Literal["include", "exclude"]): The mode of the filter ("include" or "exclude").
-		filter_instances (Any): The filter value(s) (e.g., a string or a sequence of strings).
-
-	Returns:
-		bool: True if the `type_` passes the filter, False otherwise.
-	"""
-	
-	return _validate_log_filter(filter_mode, filter_instances)(type_)
-
-
-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.log_dir_path, Path) and (
-			logger_settings.log_dir_path.is_dir()
-			or not logger_settings.log_dir_path.exists()
-	):
-		if not logger_settings.log_dir_path.exists():
-			logger_settings.log_dir_path.mkdir(parents=True)
-		elif logger_settings.renew_log:
-			shutil.rmtree(logger_settings.log_dir_path)
-	
-			logger_settings.log_dir_path.mkdir()
-	elif logger_settings.log_dir_path is not None:
-		raise ValueError(
-				f"'log_dir_path' must be a pathlib.Path to directory or None, got {logger_settings.log_dir_path} (type: {type(logger_settings.log_dir_path)})"
-		)
-
-
-def _background_task_decorator(func: devtools_background_func_type) -> devtools_background_func_type:
-	"""
-	Decorator for DevToolsTarget 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 `DevToolsTarget` to track the task's termination.
-
-	Args:
-		func (devtools_background_func_type): The asynchronous background task function
-											  to be wrapped. It should accept a `DevToolsTarget` instance.
-
-	Returns:
-		devtools_background_func_type: The wrapped function.
-	"""
-	
-	@functools.wraps(func)
-	async def wrapper(target: "DevToolsTarget") -> Any:
-		target.background_task_ended = trio.Event()
-		
-		await func(target)
-		
-		target.background_task_ended.set()
-	
-	return wrapper
-
-
-@dataclass
-class TargetFilter:
-	"""
-	Dataclass to define a filter for discovering new browser targets.
-
-	Used in `DevToolsSettings` to specify which types of targets (e.g., "page", "iframe")
-	should be automatically attached to or excluded.
-
-	Attributes:
-		type_ (Optional[str]): The type of target to filter by (e.g., "page", "iframe").
-			If None, this filter applies regardless of type.
-		exclude (Optional[bool]): If True, targets matching `type_` will be excluded.
-			If False or None, targets matching `type_` will be included.
-	"""
-	
-	type_: Optional[str] = None
-	exclude: Optional[bool] = None
-	
-	def to_dict(self) -> dict[str, Any]:
-		"""
-		Converts the target filter to a dictionary suitable for CDP command parameters.
-
-		Returns:
-			dict[str, Any]: A dictionary representation of the target filter.
-		"""
-		
-		dict_ = {}
-		
-		if self.type_ is not None:
-			dict_["type"] = self.type_
-		
-		if self.exclude is not None:
-			dict_["exclude"] = self.exclude
-		
-		return dict_
-
-
-@dataclass
-class TargetData:
-	"""
-	Dataclass to hold essential information about a browser target (e.g., a tab, iframe, or worker).
-
-	Attributes:
-		target_id (Optional[str]): The unique identifier for the target.
-		type_ (Optional[str]): The type of the target (e.g., "page", "iframe", "worker").
-		title (Optional[str]): The title of the target (e.g., the page title).
-		url (Optional[str]): The URL of the target.
-		attached (Optional[bool]): Indicates if the DevTools session is currently attached to this target.
-	"""
-	
-	target_id: Optional[str] = None
-	type_: Optional[str] = None
-	title: Optional[str] = None
-	url: Optional[str] = None
-	attached: Optional[bool] = None
-	can_access_opener: Optional[bool] = None
-	opener_id: Optional[str] = None
-	opener_frame_id: Optional[str] = None
-	browser_context_id: Optional[str] = None
-	subtype: Optional[str] = None
-	
-	def to_dict(self) -> dict[str, Any]:
-		"""
-		Converts the target data to a dictionary.
-
-		Returns:
-			dict[str, Any]: A dictionary representation of the target data.
-		"""
-		
-		return {
-			"target_id": self.target_id,
-			"type": self.type_,
-			"title": self.title,
-			"url": self.url,
-		}
-	
-	def to_json(self) -> dict[str, Any]:
-		"""
-		Converts the target data to a JSON-serializable dictionary.
-
-		Note: `cdp_session` is converted to its string representation as it's not directly JSON-serializable.
-
-		Returns:
-			dict[str, Any]: A JSON-serializable dictionary representation of the target data.
-		"""
-		
-		return {
-			"target_id": self.target_id,
-			"type": self.type_,
-			"title": self.title,
-			"url": self.url,
-		}

osn_selenium/errors.py

@@ -1,16 +0,0 @@
-class PlatformNotSupportedError(Exception):
-	"""
-	Custom exception raised when the current platform is not supported.
-
-	This exception is intended to be raised when the script or application is run on a platform that is not explicitly supported by the program logic.
-	"""
-	
-	def __init__(self, platform: str):
-		"""
-		Initializes a new instance of `PlatformNotSupportedError`.
-
-		Args:
-		   platform (str): The name of the unsupported operating system.
-		"""
-		
-		super().__init__(f"Platform not supported: {platform}.")

osn_selenium/types.py

@@ -1,118 +0,0 @@
-from win32api import GetSystemMetrics
-from typing import Optional, TypedDict
-
-
-class WindowRect:
-	"""
-	Represents a window rectangle with x, y, width, and height.
-
-	Attributes:
-		x (int): The x-coordinate of the top-left corner. Defaults to 1/4 of screen width.
-		y (int): The y-coordinate of the top-left corner. Defaults to 10% of screen height.
-		width (int): The width of the rectangle. Defaults to 1/2 of screen width.
-		height (int): The height of the rectangle. Defaults to 80% of screen height.
-	"""
-	
-	def __init__(
-			self,
-			x: Optional[int] = None,
-			y: Optional[int] = None,
-			width: Optional[int] = None,
-			height: Optional[int] = None
-	):
-		"""
-		Initializes WindowRect with optional x, y, width, and height values.
-
-		Args:
-			x (Optional[int]): The x-coordinate. Defaults to None.
-			y (Optional[int]): The y-coordinate. Defaults to None.
-			width (Optional[int]): The width. Defaults to None.
-			height (Optional[int]): The height. Defaults to None.
-		"""
-		
-		self.x = GetSystemMetrics(0) // 4
-		
-		self.y = int(GetSystemMetrics(1) * 0.1)
-		
-		self.width = GetSystemMetrics(0) // 2
-		
-		self.height = int(GetSystemMetrics(1) * 0.8)
-		
-		self.set_rect(x, y, width, height)
-	
-	def set_rect(
-			self,
-			x: Optional[int] = None,
-			y: Optional[int] = None,
-			width: Optional[int] = None,
-			height: Optional[int] = None
-	) -> "WindowRect":
-		"""
-		Sets the rectangle dimensions.
-
-		Args:
-			x (Optional[int]): The x-coordinate. Defaults to None.
-			y (Optional[int]): The y-coordinate. Defaults to None.
-			width (Optional[int]): The width. Defaults to None.
-			height (Optional[int]): The height. Defaults to None.
-
-		Returns:
-			WindowRect: Returns the instance for method chaining.
-		"""
-		
-		if x is not None:
-			self.x = x
-		
-		if y is not None:
-			self.y = y
-		
-		if width is not None:
-			self.width = width
-		
-		if height is not None:
-			self.height = height
-		
-		return self
-
-
-class Size(TypedDict):
-	"""
-	Represents a dictionary structure defining the size.
-
-	Attributes:
-		width (int): The width of the rectangle along the x-axis.
-		height (int): The height of the rectangle along the y-axis.
-	"""
-	
-	width: int
-	height: int
-
-
-class Rectangle(TypedDict):
-	"""
-	Represents a dictionary structure defining the properties of a rectangle.
-
-	Attributes:
-		x (int): The x-coordinate of the top-left corner of the rectangle.
-		y (int): The y-coordinate of the top-left corner of the rectangle.
-		width (int): The width of the rectangle along the x-axis.
-		height (int): The height of the rectangle along the y-axis.
-	"""
-	
-	x: int
-	y: int
-	width: int
-	height: int
-
-
-class Position(TypedDict):
-	"""
-	Represents a dictionary structure defining the position.
-
-	Attributes:
-		x (int): The x-coordinate of the top-left corner of the rectangle.
-		y (int): The y-coordinate of the top-left corner of the rectangle.
-	"""
-	
-	x: int
-	y: int

osn_selenium/webdrivers/BaseDriver/_utils.py

@@ -1,37 +0,0 @@
-import trio
-from trio import CapacityLimiter
-from functools import partial, wraps
-from typing import (
-	Any,
-	Callable,
-	Coroutine,
-	Optional,
-	ParamSpec,
-	TypeVar
-)
-
-
-TrioWrapInput = ParamSpec("TrioWrapInput")
-TrioWrapOutput = TypeVar("TrioWrapOutput")
-
-
-def trio_async_wrap(
-		func: Callable[TrioWrapInput, TrioWrapOutput],
-		trio_capacity_limiter: Optional[CapacityLimiter] = None
-) -> Callable[TrioWrapInput, Coroutine[Any, Any, TrioWrapOutput]]:
-	@wraps(func)
-	def wrapper(*args: TrioWrapInput.args, **kwargs: TrioWrapInput.kwargs) -> Coroutine[Any, Any, TrioWrapOutput]:
-		func_with_kwargs = partial(func, **kwargs)
-		return trio.to_thread.run_sync(func_with_kwargs, *args, limiter=trio_capacity_limiter)
-	
-	return wrapper
-
-
-def build_cdp_kwargs(**kwargs):
-	dict_ = {}
-	
-	for key, value in kwargs.items():
-		if value is not None:
-			dict_[key] = value
-	
-	return dict_