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

{osn_selenium-0.0.0.dist-info → osn_selenium-1.0.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (80.10.1)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

osn_selenium/captcha_workers/__init__.py

@@ -1,26 +0,0 @@
-from typing import (
-	Callable,
-	TYPE_CHECKING,
-	TypedDict
-)
-
-
-if TYPE_CHECKING:
-	from osn_selenium.webdrivers.BaseDriver.webdriver import BrowserWebDriver
-
-
-class CaptchaWorkerSettings(TypedDict):
-	"""
-	Typed dictionary for defining a captcha worker.
-
-	Attributes:
-		name (str): A unique name for the captcha worker.
-		check_func (Callable[["BrowserWebDriver"], bool]): A callable function that takes a
-			`BrowserWebDriver` instance and returns `True` if a captcha is detected.
-		solve_func (Callable[["BrowserWebDriver"], None]): A callable function that takes a
-			`BrowserWebDriver` instance and attempts to solve the captcha.
-	"""
-	
-	name: str
-	check_func: Callable[["BrowserWebDriver"], bool]
-	solve_func: Callable[["BrowserWebDriver"], None]

osn_selenium/dev_tools/_types.py

@@ -1,22 +0,0 @@
-from typing import (
-	Awaitable,
-	Callable,
-	Literal,
-	TYPE_CHECKING
-)
-
-
-if TYPE_CHECKING:
-	from osn_selenium.dev_tools.manager import DevToolsTarget
-
-
-devtools_background_func_type = Callable[["DevToolsTarget"], Awaitable[None]]
-LogLevelsType = Literal[
-	"INFO",
-	"ERROR",
-	"DEBUG",
-	"WARNING",
-	"RequestPaused",
-	"AuthRequired",
-	"Building Kwargs"
-]

osn_selenium/dev_tools/errors.py

@@ -1,89 +0,0 @@
-import trio
-from selenium.webdriver.common.bidi.cdp import CdpConnectionClosed
-
-
-class WrongHandlerSettingsTypeError(Exception):
-	"""
-	Custom exception raised when the event handler settings type is incorrect.
-
-	This exception is raised when the provided handler settings is not a dictionary,
-	but expected to be for proper configuration of event handlers.
-	"""
-	
-	def __init__(self, handler_settings_type: type):
-		"""
-		Initializes WrongHandlerSettingsTypeError with the incorrect settings type.
-
-		Args:
-			handler_settings_type (type): The type of the handler settings that caused the error.
-		"""
-		
-		super().__init__(
-				f"Wrong event handler settings type ({handler_settings_type}). It must be a dict!"
-		)
-
-
-class WrongHandlerSettingsError(Exception):
-	"""
-	Custom exception raised when event handler settings are incorrect.
-
-	This exception is raised if the provided handler settings dictionary does not contain
-	exactly one of the expected keys, as specified in the `one_of` attribute.
-	"""
-	
-	def __init__(self, handler_settings: dict, one_of: list[str]):
-		"""
-		Initializes WrongHandlerSettingsError with the incorrect handler settings and expected keys.
-
-		Args:
-			handler_settings (dict[str, Any]): The dictionary of handler settings that caused the error.
-			one_of (Sequence[str]): A list of expected keys, exactly one of which should be in `handler_settings`.
-		"""
-		
-		super().__init__(
-				f"Wrong event handler settings ({handler_settings})\n\nIt must contain exactly one of {one_of} keys!"
-		)
-
-
-class CantEnterDevToolsContextError(Exception):
-	"""
-	Custom exception raised when unable to enter the DevTools context.
-
-	This exception is raised when the attempt to switch the WebDriver's context to
-	the DevTools frame fails, preventing further DevTools interactions.
-	"""
-	
-	def __init__(self, reason: str):
-		"""
-		Initializes CantEnterDevToolsContextError with the reason of failure.
-
-		Args:
-			reason (str): The reason why entering the DevTools context failed.
-		"""
-		
-		super().__init__(f"Can't enter devtools context! Reason: {reason}.")
-
-
-class BidiConnectionNotEstablishedError(Exception):
-	"""
-	Custom exception raised when a BiDi connection is required but not established.
-
-	This indicates that a DevTools operation was attempted before the `DevTools`
-	context manager was entered, which establishes the necessary BiDi connection.
-	"""
-	
-	def __init__(self):
-		"""
-		Initializes BidiConnectionNotEstablishedError.
-		"""
-		
-		super().__init__("Bidi connection not established. Enter the DevTools context first!")
-
-
-trio_end_exceptions = (trio.Cancelled, trio.EndOfChannel, trio.ClosedResourceError)
-cdp_end_exceptions = (
-		trio.Cancelled,
-		trio.EndOfChannel,
-		trio.ClosedResourceError,
-		CdpConnectionClosed
-)

osn_selenium/dev_tools/logger.py

@@ -1,558 +0,0 @@
-import json
-import trio
-from pathlib import Path
-from datetime import datetime
-from dataclasses import dataclass
-from osn_selenium.dev_tools._types import LogLevelsType
-from osn_selenium.dev_tools.errors import trio_end_exceptions
-from osn_selenium.dev_tools.utils import (
-	_validate_log_filter,
-	log_exception
-)
-from typing import (
-	Any,
-	Literal,
-	Optional,
-	Sequence,
-	TYPE_CHECKING,
-	Union
-)
-
-
-if TYPE_CHECKING:
-	from osn_selenium.dev_tools.utils import TargetData
-
-
-@dataclass
-class LoggerSettings:
-	"""
-	Settings for configuring the LoggerManager.
-
-	Attributes:
-		log_dir_path (Optional[Path]): The base directory where log files will be stored.
-			If None, logging will only happen in memory and not be written to files.
-			Defaults to None.
-		renew_log (bool): If True and `log_dir_path` is provided, the log directory
-			will be cleared (recreated) on initialization. Defaults to True.
-		log_level_filter_mode (Literal["exclude", "include"]): The mode for filtering log levels.
-			"exclude" means log levels in `log_level_filter` will be excluded.
-			"include" means only log levels in `log_level_filter` will be included.
-			Defaults to "exclude".
-		log_level_filter (Optional[Union[LogLevelsType, Sequence[LogLevelsType]]]):
-			A single log level or a sequence of log levels to filter by.
-			Used in conjunction with `log_level_filter_mode`. Defaults to None.
-		target_type_filter_mode (Literal["exclude", "include"]): The mode for filtering target types.
-			"exclude" means target types in `target_type_filter` will be excluded.
-			"include" means only target types in `target_type_filter` will be included.
-			Defaults to "exclude".
-		target_type_filter (Optional[Union[str, Sequence[str]]]):
-			A single target type string or a sequence of target type strings to filter by.
-			Used in conjunction with `target_type_filter_mode`. Defaults to None.
-	"""
-	
-	log_dir_path: Optional[Path] = None
-	renew_log: bool = True
-	log_level_filter_mode: Literal["exclude", "include"] = "exclude"
-	log_level_filter: Optional[Union[LogLevelsType, Sequence[LogLevelsType]]] = None
-	target_type_filter_mode: Literal["exclude", "include"] = "exclude"
-	target_type_filter: Optional[Union[str, Sequence[str]]] = None
-
-
-@dataclass(frozen=True)
-class LogEntry:
-	"""
-	Represents a single log entry with detailed information.
-
-	Attributes:
-		target_data ("TargetData"): Data about the target (browser tab/session) from which the log originated.
-		message (str): The main log message.
-		level (LogLevelsType): The severity level of the log (e.g., "INFO", "ERROR").
-		timestamp (datetime): The exact time when the log entry was created.
-		source_function (str): The name of the function that generated the log.
-		extra_data (Optional[dict[str, Any]]): Optional additional data associated with the log.
-	"""
-	
-	target_data: "TargetData"
-	message: str
-	level: LogLevelsType
-	timestamp: datetime
-	source_function: str
-	extra_data: Optional[dict[str, Any]] = None
-	
-	def to_json(self) -> dict[str, Any]:
-		"""
-		Converts the log entry to a JSON-serializable dictionary.
-
-		Returns:
-			dict[str, Any]: A dictionary representation of the log entry.
-		"""
-		
-		log_dict = {
-			"target_data": self.target_data.to_json(),
-			"timestamp": self.timestamp.isoformat(),
-			"level": self.level,
-			"source_function": self.source_function,
-			"message": self.message,
-		}
-		
-		if self.extra_data is not None:
-			log_dict["extra_data"] = {key: str(value) for key, value in self.extra_data.items()}
-		
-		return log_dict
-	
-	def to_string(self) -> str:
-		"""
-		Converts the log entry to a human-readable string format.
-
-		Returns:
-			str: A multi-line string representation of the log entry.
-		"""
-		
-		return "\n\n".join(
-				f"{key}: {json.dumps(value, indent=4, ensure_ascii=False)}"
-				for key, value in self.to_json().items()
-		)
-
-
-class TargetLogger:
-	"""
-	Manages logging for a specific browser target (e.g., a tab or iframe).
-
-	Each `TargetLogger` instance is responsible for writing log entries
-	related to its associated `TargetData` to a dedicated file.
-
-	Attributes:
-		_target_data ("TargetData"): The data of the browser target this logger is associated with.
-		_nursery_object (trio.Nursery): The Trio nursery for managing concurrent tasks.
-		_receive_channel (trio.MemoryReceiveChannel[LogEntry]): The receive channel for log entries specific to this target.
-		_log_level_filter (Callable[[Any], bool]): Filter function for log levels.
-		_target_type_filter (Callable[[Any], bool]): Filter function for target types.
-		_file_writing_stopped (Optional[trio.Event]): An event set when file writing task stops.
-		_file_path (Optional[Path]): The path to the target-specific log file.
-		_is_active (bool): Flag indicating if the target logger is active.
-	"""
-	
-	def __init__(
-			self,
-			target_data: "TargetData",
-			nursery_object: trio.Nursery,
-			receive_channel: trio.MemoryReceiveChannel[LogEntry],
-			logger_settings: LoggerSettings,
-	):
-		"""
-		Initializes the TargetLogger.
-
-		Args:
-			target_data ("TargetData"): The data of the browser target this logger will log for.
-			nursery_object (trio.Nursery): The Trio nursery to spawn background tasks.
-		"""
-		
-		self._target_data = target_data
-		self._nursery_object = nursery_object
-		self._receive_channel = receive_channel
-		
-		self._log_level_filter = _validate_log_filter(
-				logger_settings.log_level_filter_mode,
-				logger_settings.log_level_filter
-		)
-		
-		self._target_type_filter = _validate_log_filter(
-				logger_settings.target_type_filter_mode,
-				logger_settings.target_type_filter
-		)
-		
-		self._file_writing_stopped: Optional[trio.Event] = None
-		
-		if logger_settings.log_dir_path is None:
-			self._file_path = None
-		else:
-			self._file_path = logger_settings.log_dir_path.joinpath(f"{target_data.target_id}.txt")
-			
-			if self._file_path.exists():
-				with open(self._file_path, "w", encoding="utf-8") as file:
-					file.write("")
-		
-		self._is_active = False
-	
-	@property
-	def is_active(self) -> bool:
-		"""
-		Checks if the target logger is currently active.
-
-		Returns:
-			bool: True if the logger is active and running, False otherwise.
-		"""
-		
-		return self._is_active
-	
-	async def close(self):
-		"""
-		Closes the target logger, including its receive channel.
-		"""
-		
-		if self._receive_channel is not None:
-			await self._receive_channel.aclose()
-			self._receive_channel = None
-		
-		if self._file_writing_stopped is not None:
-			await self._file_writing_stopped.wait()
-			self._file_writing_stopped = None
-		
-		self._is_active = False
-	
-	async def _write_file(self):
-		"""
-		Asynchronously writes log entries to the target-specific file.
-
-		This method continuously receives `LogEntry` objects from its channel
-		and appends their string representation to the configured file,
-		applying log level and target type filters.
-		It runs as a background task.
-
-		Raises:
-			BaseException: If an unexpected error occurs during file writing.
-		"""
-		
-		try:
-			end_of_entry = "\n\n" + "=" * 100 + "\n\n"
-		
-			async with await trio.open_file(self._file_path, "a+", encoding="utf-8") as file:
-				async for log_entry in self._receive_channel:
-					if self._log_level_filter(log_entry.level) and self._target_type_filter(log_entry.target_data.type_):
-						await file.write(log_entry.to_string() + end_of_entry)
-		except* trio_end_exceptions:
-			pass
-		except* BaseException as error:
-			log_exception(error)
-		finally:
-			if self._file_writing_stopped is not None:
-				self._file_writing_stopped.set()
-	
-	async def run(self):
-		"""Starts the target logger, setting up its receive channel and file writing task."""
-		
-		try:
-			if not self._is_active:
-				self._file_writing_stopped = trio.Event()
-		
-				if self._file_path is not None:
-					self._nursery_object.start_soon(self._write_file,)
-		
-				self._is_active = True
-		except* trio_end_exceptions:
-			await self.close()
-		except* BaseException as error:
-			log_exception(error)
-			await self.close()
-
-
-def build_target_logger(
-		target_data: "TargetData",
-		nursery_object: trio.Nursery,
-		logger_settings: LoggerSettings
-) -> tuple[trio.MemorySendChannel[LogEntry], TargetLogger]:
-	"""
-	Builds and initializes a `TargetLogger` instance along with its send channel.
-
-	Args:
-		target_data ("TargetData"): The data for the target this logger will serve.
-		nursery_object (trio.Nursery): The Trio nursery to associate with the logger for background tasks.
-		logger_settings (LoggerSettings): The logger configuration settings.
-
-	Returns:
-		tuple[trio.MemorySendChannel[LogEntry], TargetLogger]: A tuple containing
-			the send channel for `LogEntry` objects and the initialized `TargetLogger` instance.
-	"""
-	
-	send_channel, receive_channel = trio.open_memory_channel(1000)
-	target_logger = TargetLogger(target_data, nursery_object, receive_channel, logger_settings)
-	
-	return send_channel, target_logger
-
-
-@dataclass
-class LogLevelStats:
-	"""
-	Dataclass to store statistics for a specific log level.
-
-	Attributes:
-		num_logs (int): The total number of logs recorded for this level.
-		last_log_time (datetime): The timestamp of the most recent log entry for this level.
-	"""
-	
-	num_logs: int
-	last_log_time: datetime
-	
-	def to_json(self) -> dict[str, Any]:
-		"""
-		Converts the statistics to a JSON-serializable dictionary.
-
-		Returns:
-			dict[str, Any]: A dictionary representation of the log level statistics.
-		"""
-		
-		return {
-			"num_logs": self.num_logs,
-			"last_log_time": self.last_log_time.isoformat()
-		}
-
-
-@dataclass
-class LoggerChannelStats:
-	"""
-	Dataclass to store statistics for a specific logging channel (per target).
-
-	Attributes:
-		target_id (str): The unique ID of the target associated with this channel.
-		title (str): The title of the target (e.g., page title).
-		url (str): The URL of the target.
-		num_logs (int): The total number of log entries for this channel.
-		last_log_time (datetime): The timestamp of the most recent log entry for this channel.
-		log_level_stats (dict[str, LogLevelStats]): A dictionary mapping log levels to their specific statistics.
-	"""
-	
-	target_id: str
-	title: str
-	url: str
-	num_logs: int
-	last_log_time: datetime
-	log_level_stats: dict[str, LogLevelStats]
-	
-	async def add_log(self, log_entry: LogEntry):
-		"""
-		Updates the channel statistics based on a new log entry.
-
-		Args:
-			log_entry (LogEntry): The new log entry to incorporate into the statistics.
-		"""
-		
-		self.num_logs += 1
-		self.last_log_time = log_entry.timestamp
-		
-		if log_entry.level not in self.log_level_stats:
-			self.log_level_stats[log_entry.level] = LogLevelStats(num_logs=1, last_log_time=log_entry.timestamp)
-		else:
-			self.log_level_stats[log_entry.level].num_logs += 1
-			self.log_level_stats[log_entry.level].last_log_time = log_entry.timestamp
-	
-	def to_json(self) -> dict[str, Any]:
-		"""
-		Converts the channel statistics to a JSON-serializable dictionary.
-
-		Nested statistics objects are converted to their JSON representations.
-
-		Returns:
-			dict[str, Any]: A dictionary representation of the logger channel statistics.
-		"""
-		
-		return {
-			"target_id": self.target_id,
-			"title": self.title,
-			"url": self.url,
-			"num_logs": self.num_logs,
-			"last_log_time": self.last_log_time.isoformat(),
-			"log_level_stats": {
-				log_level: log_level_stats.to_json()
-				for log_level, log_level_stats in self.log_level_stats.items()
-			}
-		}
-
-
-@dataclass
-class TargetTypeStats:
-	"""
-	Dataclass to store statistics for a specific target type.
-
-	Attributes:
-		num_targets (int): The count of targets of this type.
-	"""
-	
-	num_targets: int
-	
-	def to_json(self) -> dict[str, Any]:
-		"""
-		Converts the statistics to a JSON-serializable dictionary.
-
-		Returns:
-			dict[str, Any]: A dictionary representation of the target type statistics.
-		"""
-		
-		return {"num_targets": self.num_targets}
-
-
-@dataclass(frozen=True)
-class MainLogEntry:
-	"""
-	Represents a summary log entry for the entire logging system.
-
-	Attributes:
-		num_channels (int): The total number of active logging channels (targets).
-		targets_types_stats (dict[str, TargetTypeStats]): Statistics grouped by target type.
-		num_logs (int): The total number of log entries across all channels.
-		log_level_stats (dict[str, LogLevelStats]): Overall statistics for each log level.
-		channels_stats (Sequence[LoggerChannelStats]): A list of statistics for each active logging channel.
-	"""
-	
-	num_channels: int
-	targets_types_stats: dict[str, TargetTypeStats]
-	num_logs: int
-	log_level_stats: dict[str, LogLevelStats]
-	channels_stats: Sequence[LoggerChannelStats]
-	
-	def to_json(self) -> dict[str, Any]:
-		"""
-		Converts the main log entry to a JSON-serializable dictionary.
-
-		Nested statistics objects are converted to their JSON representations.
-
-		Returns:
-			dict[str, Any]: A dictionary representation of the main log entry.
-		"""
-		
-		return {
-			"num_channels": self.num_channels,
-			"targets_types_stats": {
-				type_: target_type_stats.to_json()
-				for type_, target_type_stats in self.targets_types_stats.items()
-			},
-			"num_logs": self.num_logs,
-			"log_level_stats": {
-				log_level: log_level_stats.to_json()
-				for log_level, log_level_stats in self.log_level_stats.items()
-			},
-			"channels_stats": [channel_stats.to_json() for channel_stats in self.channels_stats]
-		}
-	
-	def to_string(self) -> str:
-		"""
-		Converts the main log entry to a human-readable string format.
-
-		Returns:
-			str: A multi-line string representation of the main log entry.
-		"""
-		
-		return "\n\n".join(
-				f"{key}: {json.dumps(value, indent=4, ensure_ascii=False)}"
-				for key, value in self.to_json().items()
-		)
-
-
-class MainLogger:
-	"""
-	Manages the main log file, summarizing overall logging activity.
-
-	This logger is responsible for writing aggregated statistics about all active
-	logging channels and target types to a designated file.
-
-	Attributes:
-		_nursery_object (trio.Nursery): The Trio nursery for managing concurrent tasks.
-		_receive_channel (trio.MemoryReceiveChannel[MainLogEntry]): The receive channel for main log entries.
-		_file_writing_stopped (Optional[trio.Event]): An event set when the file writing task stops.
-		_is_active (bool): Flag indicating if the main logger is active.
-		_file_path (Optional[Path]): The path to the main log file.
-	"""
-	
-	def __init__(
-			self,
-			logger_settings: LoggerSettings,
-			nursery_object: trio.Nursery,
-			receive_channel: trio.MemoryReceiveChannel[MainLogEntry]
-	):
-		"""
-		Initializes the MainLogger.
-
-		Args:
-			logger_settings (LoggerSettings): The settings for logging, including log directory.
-			nursery_object (trio.Nursery): The Trio nursery to spawn background tasks.
-			receive_channel (trio.MemoryReceiveChannel[MainLogEntry]): The channel from which main log entries are received.
-		"""
-		
-		self._nursery_object = nursery_object
-		self._receive_channel = receive_channel
-		self._file_writing_stopped: Optional[trio.Event] = None
-		self._is_active = False
-		
-		if logger_settings.log_dir_path is None:
-			self._file_path = None
-		else:
-			self._file_path = logger_settings.log_dir_path.joinpath("__MAIN__.txt")
-	
-	async def close(self):
-		"""
-		Closes the main logger, including its receive channel.
-		"""
-		
-		if self._receive_channel is not None:
-			await self._receive_channel.aclose()
-			self._receive_channel = None
-		
-		if self._file_writing_stopped is not None:
-			await self._file_writing_stopped.wait()
-		
-		self._is_active = False
-	
-	async def _write_file(self):
-		"""
-		Asynchronously writes main log entries to the file.
-
-		This method continuously receives `MainLogEntry` objects from its channel
-		and overwrites the configured file with their string representation.
-		It runs as a background task.
-
-		Raises:
-			BaseException: If an unexpected error occurs during file writing.
-		"""
-		
-		try:
-			async with await trio.open_file(self._file_path, "w+", encoding="utf-8") as file:
-				async for log_entry in self._receive_channel:
-					await file.write(log_entry.to_string())
-					await file.seek(0)
-		except* trio_end_exceptions:
-			pass
-		except* BaseException as error:
-			log_exception(error)
-		finally:
-			if self._file_writing_stopped is not None:
-				self._file_writing_stopped.set()
-	
-	async def run(self):
-		"""
-		Starts the main logger, setting up its receive channel and file writing task.
-
-		Raises:
-			BaseException: If an error occurs during setup or if the logger fails to activate.
-		"""
-		
-		try:
-			if not self._is_active:
-				self._file_writing_stopped = trio.Event()
-		
-				if self._file_path is not None:
-					self._nursery_object.start_soon(self._write_file,)
-		
-				self._is_active = True
-		except* trio_end_exceptions:
-			await self.close()
-		except* BaseException as error:
-			log_exception(error)
-			await self.close()
-
-
-def build_main_logger(nursery_object: trio.Nursery, logger_settings: LoggerSettings) -> tuple[trio.MemorySendChannel[MainLogEntry], MainLogger]:
-	"""
-	Builds and initializes a `MainLogger` instance along with its send channel.
-
-	Args:
-		nursery_object (trio.Nursery): The Trio nursery to associate with the logger for background tasks.
-		logger_settings (LoggerSettings): The logger configuration settings.
-
-	Returns:
-		tuple[trio.MemorySendChannel[MainLogEntry], MainLogger]: A tuple containing
-			the send channel for `MainLogEntry` objects and the initialized `MainLogger` instance.
-	"""
-	
-	send_channel, receive_channel = trio.open_memory_channel(1000)
-	target_logger = MainLogger(logger_settings, nursery_object, receive_channel)
-	
-	return send_channel, target_logger