osn-selenium 0.0.0__py3-none-any.whl → 1.1.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/_functions.py

@@ -0,0 +1,84 @@
+import pathlib
+from types import UnionType
+from osn_selenium.exceptions.path import PathValidationError
+from typing import (
+	Iterable,
+	Optional,
+	Set,
+	Union,
+	get_args,
+	get_origin
+)
+from osn_selenium._typehints import (
+	PATH_TYPEHINT,
+	TYPES_FOR_FLATTENING_TYPEHINT
+)
+
+
+__all__ = ["flatten_types", "validate_path"]
+
+
+def validate_path(path: Optional[PATH_TYPEHINT]) -> Optional[pathlib.Path]:
+	"""
+	Validates the provided path and converts it to a pathlib.Path object.
+
+	Args:
+		path (Optional[PATH_TYPEHINT]): The path to be validated and converted.
+
+	Returns:
+		Optional[pathlib.Path]: A Path object if valid, or None if the input was None.
+
+	Raises:
+		PathValidationError: If the path conversion fails due to an exception.
+	"""
+	
+	try:
+		if path is None:
+			return None
+	
+		return pathlib.Path(path)
+	except (Exception,) as exception:
+		raise PathValidationError(path=path, exception=exception)
+
+
+def flatten_types(
+		types_: Union[TYPES_FOR_FLATTENING_TYPEHINT, Iterable[TYPES_FOR_FLATTENING_TYPEHINT]]
+) -> Set[str]:
+	"""
+	Recursively extracts type names from a type, a union of types, or a collection of types.
+
+	Args:
+		types_ (Union[Type, Iterable[Type]]): The type definition or collection of types to flatten.
+
+	Returns:
+		Set[str]: A set of strings representing the names of the types found.
+	"""
+	
+	types_of_level = set()
+	
+	if isinstance(types_, Iterable) and not isinstance(types_, str):
+		for t in types_:
+			types_of_level.update(flatten_types(t))
+	
+		return types_of_level
+	
+	if isinstance(types_, str):
+		types_of_level.add(types_)
+	
+	origin = get_origin(types_)
+	args = get_args(types_)
+	
+	is_union = origin is Union or isinstance(types_, UnionType)
+	
+	if is_union:
+		for arg in args:
+			types_of_level.update(flatten_types(arg))
+	else:
+		if types_ is None or types_ is type(None):
+			types_of_level.add("NoneType")
+		elif hasattr(types_, "__name__"):
+			types_of_level.add(types_.__name__)
+		else:
+			types_of_level.add(str(types_))
+	
+	return types_of_level

osn_selenium/_typehints.py

@@ -0,0 +1,19 @@
+import os
+import pathlib
+from typing import Literal, Type, Union
+from selenium.webdriver.common.actions.key_input import KeyInput
+from selenium.webdriver.common.actions.wheel_input import WheelInput
+from selenium.webdriver.common.actions.pointer_input import PointerInput
+
+
+__all__ = [
+	"ARCHITECTURES_TYPEHINT",
+	"DEVICES_TYPEHINT",
+	"PATH_TYPEHINT",
+	"TYPES_FOR_FLATTENING_TYPEHINT"
+]
+
+DEVICES_TYPEHINT = Union[PointerInput, KeyInput, WheelInput]
+ARCHITECTURES_TYPEHINT = Literal["sync", "trio_threads"]
+PATH_TYPEHINT = Union[str, bytes, pathlib.Path, os.PathLike]
+TYPES_FOR_FLATTENING_TYPEHINT = Union[str, Type]