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

osn_selenium/exceptions/devtools.py

@@ -0,0 +1,114 @@
+import trio
+from osn_selenium.exceptions.base import OSNSeleniumError
+from osn_selenium.dev_tools._exception_helpers import (
+	extract_exception_trace
+)
+from selenium.webdriver.common.bidi.cdp import (
+	BrowserError,
+	CdpConnectionClosed
+)
+
+
+__all__ = [
+	"BidiConnectionNotEstablishedError",
+	"CDPCommandNotFoundError",
+	"CDPEndExceptions",
+	"CantEnterDevToolsContextError",
+	"DevToolsError",
+	"ExceptionThrown",
+	"TrioEndExceptions"
+]
+
+
+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) -> None:
+		"""
+		Initializes the ExceptionThrown wrapper.
+
+		Args:
+			exception (BaseException): The exception to wrap.
+		"""
+		
+		self.exception = exception
+		self.traceback = extract_exception_trace(exception)
+
+
+class DevToolsError(OSNSeleniumError):
+	"""
+	Base exception for all DevTools-related operations.
+	"""
+	
+	pass
+
+
+class CantEnterDevToolsContextError(DevToolsError):
+	"""
+	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) -> None:
+		"""
+		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 CDPCommandNotFoundError(DevToolsError):
+	"""
+	Error raised when a requested CDP command attribute is not found in the specified module.
+	"""
+	
+	def __init__(self, object_: str, module_: str):
+		"""
+		Initializes CDPCommandNotFoundError.
+
+		Args:
+			object_ (str): The name of the missing attribute.
+			module_ (str): The name of the module where the attribute was expected.
+		"""
+		
+		super().__init__(f"Attribute '{object_}' not found in '{module_}'")
+
+
+class BidiConnectionNotEstablishedError(DevToolsError):
+	"""
+	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) -> None:
+		"""
+		Initializes BidiConnectionNotEstablishedError.
+		"""
+		
+		super().__init__("Bidi connection not established. Enter the DevTools context first!")
+
+
+TrioEndExceptions = (trio.Cancelled, trio.EndOfChannel, trio.ClosedResourceError)
+CDPEndExceptions = (
+		trio.Cancelled,
+		trio.EndOfChannel,
+		trio.ClosedResourceError,
+		CdpConnectionClosed,
+		BrowserError
+)

osn_selenium/exceptions/flags.py

@@ -0,0 +1,45 @@
+from osn_selenium.exceptions.base import OSNSeleniumError
+
+
+__all__ = ["FlagError", "FlagNotDefinedError", "FlagTypeNotDefinedError"]
+
+
+class FlagError(OSNSeleniumError):
+	"""
+	Base class for errors related to management flags.
+	"""
+	
+	pass
+
+
+class FlagTypeNotDefinedError(FlagError):
+	"""
+	Error raised when a requested flag category is not recognized by the manager.
+	"""
+	
+	def __init__(self, flag_type: str) -> None:
+		"""
+		Initializes FlagTypeNotDefinedError.
+
+		Args:
+			flag_type (str): The name of the undefined flag category.
+		"""
+		
+		super().__init__(f"Flag category '{flag_type}' is not defined for this manager.")
+
+
+class FlagNotDefinedError(FlagError):
+	"""
+	Error raised when a specific flag is not defined within a recognized category.
+	"""
+	
+	def __init__(self, flag_name: str, flag_type: str) -> None:
+		"""
+		Initializes FlagNotDefinedError.
+
+		Args:
+			flag_name (str): The name of the missing flag.
+			flag_type (str): The category where the flag was expected.
+		"""
+		
+		super().__init__(f"Flag '{flag_name}' is not defined for type '{flag_type}'.")

osn_selenium/exceptions/instance.py

@@ -0,0 +1,92 @@
+from osn_selenium._functions import flatten_types
+from typing import (
+	Any,
+	Iterable,
+	Type,
+	Union
+)
+from osn_selenium.exceptions.base import OSNSeleniumError
+from osn_selenium._typehints import (
+	TYPES_FOR_FLATTENING_TYPEHINT
+)
+
+
+__all__ = [
+	"CannotConvertTypeError",
+	"ElementInteractionError",
+	"ElementNotVisibleError",
+	"InstanceError",
+	"NotExpectedTypeError"
+]
+
+
+class InstanceError(OSNSeleniumError):
+	"""
+	Base class for errors related to object instances and types.
+	"""
+	
+	pass
+
+
+class NotExpectedTypeError(InstanceError):
+	"""
+	Error raised when an object is not of the expected type.
+	"""
+	
+	def __init__(
+			self,
+			expected_type: Union[TYPES_FOR_FLATTENING_TYPEHINT, Iterable[TYPES_FOR_FLATTENING_TYPEHINT]],
+			received_instance: Any
+	) -> None:
+		"""
+		Initializes the error with expected types and the actual received instance.
+
+		Args:
+			expected_type (Any): The type or collection of types expected.
+			received_instance (Any): The actual instance received.
+		"""
+		
+		super().__init__(
+				f"Expected one of [{', '.join(flatten_types(expected_type))}], got {type(received_instance).__name__}"
+		)
+
+
+class ElementInteractionError(InstanceError):
+	"""
+	Error raised when an interaction with a web element fails.
+	"""
+	
+	pass
+
+
+class ElementNotVisibleError(ElementInteractionError):
+	"""
+	Error raised when a web element is not visible or has no size on the page.
+	"""
+	
+	def __init__(self, element_id: str) -> None:
+		"""
+		Initializes ElementNotVisibleError.
+
+		Args:
+			element_id (str): The identifier of the hidden element.
+		"""
+		
+		super().__init__(f"Element '{element_id}' is not visible or has no size.")
+
+
+class CannotConvertTypeError(InstanceError):
+	"""
+	Error raised when conversion between two types is not possible.
+	"""
+	
+	def __init__(self, from_: Type, to_: Any) -> None:
+		"""
+		Initializes the error with the source and target objects.
+
+		Args:
+			from_ (Any): The object being converted from.
+			to_ (Any): The object being converted to.
+		"""
+		
+		super().__init__(f"Cannot convert {from_.__name__} to {type(to_).__name__}")

osn_selenium/exceptions/javascript.py

@@ -0,0 +1,31 @@
+from typing import Iterable, Union
+from osn_selenium.exceptions.base import OSNSeleniumError
+
+
+__all__ = ["JavaScriptError", "JavaScriptResourceError"]
+
+
+class JavaScriptError(OSNSeleniumError):
+	"""
+	Base class for JavaScript-related errors.
+	"""
+	
+	pass
+
+
+class JavaScriptResourceError(JavaScriptError):
+	"""
+	Error raised when required JavaScript resources or scripts are missing.
+	"""
+	
+	def __init__(self, missing_script: Union[str, Iterable[str]]) -> None:
+		"""
+		Initializes JavaScriptResourceError.
+
+		Args:
+			missing_script (Union[str, Iterable[str]]): The name or names of the missing scripts.
+		"""
+		
+		missing_string = missing_script if isinstance(missing_script, str) else "\n\t- ".join(missing_script)
+		
+		super().__init__(f"Required JavaScript resources are missing:\n\t- {missing_string}")

osn_selenium/exceptions/logic.py

@@ -0,0 +1,31 @@
+from osn_selenium.exceptions.base import OSNSeleniumError
+
+
+__all__ = ["AbstractImplementationError", "LogicError"]
+
+
+class LogicError(OSNSeleniumError):
+	"""
+	Base class for internal logic and implementation errors.
+	"""
+	
+	pass
+
+
+class AbstractImplementationError(LogicError):
+	"""
+	Error raised when an abstract method is not implemented in a subclass.
+	"""
+	
+	def __init__(self, method_name: str, class_name: str) -> None:
+		"""
+		Initializes AbstractImplementationError.
+
+		Args:
+			method_name (str): The name of the method that should have been implemented.
+			class_name (str): The name of the base class defining the abstract method.
+		"""
+		
+		super().__init__(
+				f"Method '{method_name}' must be implemented in subclass of '{class_name}'."
+		)

osn_selenium/exceptions/path.py

@@ -0,0 +1,77 @@
+from typing import Any
+from osn_selenium._typehints import PATH_TYPEHINT
+from osn_selenium.exceptions.base import OSNSeleniumError
+
+
+__all__ = [
+	"BrowserExecutableNotFoundError",
+	"ExecutableError",
+	"PathError",
+	"PathValidationError",
+	"WebDriverExecutableNotFoundError"
+]
+
+
+class PathError(OSNSeleniumError):
+	"""
+	Base class for file system and path-related errors.
+	"""
+	
+	pass
+
+
+class ExecutableError(PathError):
+	"""
+	Base class for errors related to binary executables.
+	"""
+	
+	pass
+
+
+class WebDriverExecutableNotFoundError(ExecutableError):
+	"""
+	Error raised when the WebDriver executable file cannot be found.
+	"""
+	
+	def __init__(self, path: PATH_TYPEHINT) -> None:
+		"""
+		Initializes WebDriverExecutableNotFoundError.
+
+		Args:
+			path (PATH_TYPEHINT): The path where the WebDriver was expected.
+		"""
+		
+		super().__init__(f"WebDriver executable not found at: {path}")
+
+
+class PathValidationError(PathError):
+	"""
+	Error raised when a path fails to meet specific validation criteria.
+	"""
+	
+	def __init__(self, path: Any, exception: Exception) -> None:
+		"""
+		Initializes PathValidationError.
+
+		Args:
+			path (Any): The path that failed validation.
+			exception (Exception): The original exception caught during validation.
+		"""
+		
+		super().__init__(f"Path '{path}' validation error:\n{exception}")
+
+
+class BrowserExecutableNotFoundError(ExecutableError):
+	"""
+	Error raised when the browser executable binary cannot be found.
+	"""
+	
+	def __init__(self, path: PATH_TYPEHINT) -> None:
+		"""
+		Initializes BrowserExecutableNotFoundError.
+
+		Args:
+			path (PATH_TYPEHINT): The path where the browser binary was expected.
+		"""
+		
+		super().__init__(f"Browser executable not found at: {path}")

osn_selenium/exceptions/platform.py

@@ -0,0 +1,33 @@
+from osn_selenium.exceptions.base import OSNSeleniumError
+
+
+__all__ = ["PlatformError", "PlatformNotSupportedError"]
+
+
+class PlatformError(OSNSeleniumError):
+	"""
+	Base class for environment and platform-specific errors.
+	"""
+	
+	pass
+
+
+class PlatformNotSupportedError(PlatformError):
+	"""
+	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) -> None:
+		"""
+		Initializes a new instance of `PlatformNotSupportedError`.
+
+		Args:
+		   platform (str): The name of the unsupported operating system.
+		"""
+		
+		super().__init__(
+				f"Platform not supported: {platform}. Currently supported: Windows, Linux."
+		)

osn_selenium/exceptions/protocol.py

@@ -0,0 +1,86 @@
+from osn_selenium.exceptions.base import OSNSeleniumError
+from typing import (
+	Any,
+	Iterable,
+	Protocol,
+	Type,
+	Union,
+	get_origin
+)
+
+
+__all__ = ["ProtocolComplianceError", "ProtocolError"]
+
+
+class ProtocolError(OSNSeleniumError):
+	"""
+	Base class for errors related to Protocol contract violations.
+	"""
+	
+	pass
+
+
+class ProtocolComplianceError(ProtocolError):
+	"""
+	Error raised when an object fails to implement the required protocol members.
+
+	Attributes:
+		instance (Any): The object instance that failed the check.
+		instance_name (str): The name of the instance class.
+		expected_list (list): A list of protocols the instance was checked against.
+	"""
+	
+	def __init__(self, instance: Any, expected_protocols: Union[Type, Iterable[Type]]) -> None:
+		"""
+		Initializes ProtocolComplianceError.
+
+		Args:
+			instance (Any): The object instance that failed the check.
+			expected_protocols (Union[Type, Iterable[Type]]): The protocol or protocols expected.
+		"""
+		
+		self.instance = instance
+		
+		self.instance_name = type(instance).__name__
+		
+		if isinstance(expected_protocols, type) or get_origin(expected_protocols) is not None:
+			self.expected_list = [expected_protocols]
+		else:
+			self.expected_list = list(expected_protocols)
+		
+		super().__init__(self._generate_report())
+	
+	def _generate_report(self) -> str:
+		"""
+		Generates a detailed report of missing members for the protocols.
+
+		Returns:
+			str: A formatted string containing missing members and compliance status.
+		"""
+		
+		report = [f"Object '{self.instance_name}' failed protocol compliance check."]
+		
+		for proto in self.expected_list:
+			proto_name = getattr(proto, "__name__", str(proto))
+			needed_attrs = getattr(proto, "__protocol_attrs__", set())
+		
+			if not needed_attrs:
+				report.append(f"\t- Protocol '{proto_name}': No checkable attributes found.")
+				continue
+		
+			missing = [attr for attr in needed_attrs if not hasattr(self.instance, attr)]
+		
+			if missing:
+				report.append(
+						f"\t- Protocol '{proto_name}' requires missing members: {', '.join(missing)}"
+				)
+			else:
+				report.append(
+						f"\t- Protocol '{proto_name}': Members present, but contract check failed."
+				)
+		
+		report.append(
+				f"Please ensure the object implements all required properties and methods defined in the Protocol."
+		)
+		
+		return "\n".join(report)

osn_selenium/exceptions/webdriver.py

@@ -0,0 +1,44 @@
+from osn_selenium.exceptions.base import OSNSeleniumError
+
+
+__all__ = [
+	"WebDriverAlreadyRunningError",
+	"WebDriverError",
+	"WebDriverNotStartedError"
+]
+
+
+class WebDriverError(OSNSeleniumError):
+	"""
+	Base class for WebDriver lifecycle and control errors.
+	"""
+	
+	pass
+
+
+class WebDriverNotStartedError(WebDriverError):
+	"""
+	Error raised when an operation is performed while the WebDriver session is not active.
+	"""
+	
+	def __init__(self) -> None:
+		"""
+		Initializes WebDriverNotStartedError.
+		"""
+		
+		super().__init__("WebDriver is not started. Call start_webdriver() first.")
+
+
+class WebDriverAlreadyRunningError(WebDriverError):
+	"""
+	Error raised when an attempt is made to start a WebDriver that is already active.
+	"""
+	
+	def __init__(self) -> None:
+		"""
+		Initializes WebDriverAlreadyRunningError.
+		"""
+		
+		super().__init__(
+				"WebDriver is already active. Stop it or use restart_webdriver() to apply changes."
+		)

osn_selenium/exceptions/window.py

@@ -0,0 +1,63 @@
+from osn_selenium.exceptions.base import OSNSeleniumError
+
+
+__all__ = [
+	"InvalidWindowHandleError",
+	"InvalidWindowIndexError",
+	"NoWindowHandlesFoundError",
+	"WindowManagementError"
+]
+
+
+class WindowManagementError(OSNSeleniumError):
+	"""
+	Base class for errors related to window and tab management.
+	"""
+	
+	pass
+
+
+class NoWindowHandlesFoundError(WindowManagementError):
+	"""
+	Error raised when the WebDriver session reports having no windows.
+	"""
+	
+	def __init__(self) -> None:
+		"""
+		Initializes NoWindowHandlesFoundError.
+		"""
+		
+		super().__init__("No window handles found in session.")
+
+
+class InvalidWindowIndexError(WindowManagementError):
+	"""
+	Error raised when trying to access a window by an out-of-bounds index.
+	"""
+	
+	def __init__(self, index: int, handles_length: int) -> None:
+		"""
+		Initializes InvalidWindowIndexError.
+
+		Args:
+			index (int): The requested index.
+			handles_length (int): The current count of window handles.
+		"""
+		
+		super().__init__(f"Window index {index} out of range [0, {handles_length - 1}]")
+
+
+class InvalidWindowHandleError(WindowManagementError):
+	"""
+	Error raised when a specific window handle string is not recognized in the session.
+	"""
+	
+	def __init__(self, handle: str) -> None:
+		"""
+		Initializes InvalidWindowHandleError.
+
+		Args:
+			handle (str): The invalid window handle string.
+		"""
+		
+		super().__init__(f"Handle: {handle} not found in session.")

osn_selenium/executors/__init__.py

@@ -0,0 +1 @@
+

osn_selenium/executors/sync/__init__.py

@@ -0,0 +1 @@
+