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

osn_selenium/abstract/webdriver/yandex/settings.py

@@ -0,0 +1,110 @@
+from typing import Optional
+from abc import abstractmethod
+from osn_selenium.models import WindowRect
+from osn_selenium._typehints import PATH_TYPEHINT
+from osn_selenium.flags.models.yandex import YandexFlags
+from osn_selenium.abstract.webdriver.chrome.settings import (
+	AbstractChromeSettingsMixin
+)
+
+
+__all__ = ["AbstractYandexSettingsMixin"]
+
+
+class AbstractYandexSettingsMixin(AbstractChromeSettingsMixin):
+	"""
+	Abstract mixin for managing Yandex browser settings.
+
+	Provides methods to update or reset configuration parameters such as flags,
+	executable paths, and window dimensions for the Yandex WebDriver.
+	"""
+	
+	@abstractmethod
+	def reset_settings(
+			self,
+			flags: Optional[YandexFlags] = None,
+			browser_exe: Optional[PATH_TYPEHINT] = None,
+			browser_name_in_system: Optional[str] = None,
+			use_browser_exe: Optional[bool] = None,
+			start_page_url: str = "",
+			window_rect: Optional[WindowRect] = None,
+	):
+		"""
+		Resets various configurable browser settings to their specified or default values.
+
+		This method allows for reconfiguring the WebDriver's operational parameters,
+		such as browser flags, executable path, start URL, window dimensions, and
+		concurrency limits. It is crucial that the browser session is *not* active
+		when this method is called; otherwise, a warning will be issued, and no changes
+		will be applied.
+
+		Args:
+			flags (Optional[YandexFlags]): New browser flags to apply.
+				If provided, existing flags are cleared and replaced with these.
+				If `None`, all custom flags are cleared, and the browser will start with default flags.
+			browser_exe (Optional[PATH_TYPEHINT]): The explicit path to the browser executable.
+				If provided, this path will be used. If `None`, the executable path managed by the
+				flags manager will be cleared, and then potentially re-detected based on
+				`use_browser_exe` and `browser_name_in_system`.
+			browser_name_in_system (Optional[str]): The common name of the browser (e.g., "Yandex").
+				Used in conjunction with `use_browser_exe` to automatically detect the browser executable path.
+				This parameter only takes effect if `use_browser_exe` is explicitly `True` or `False`.
+				If `None`, no automatic detection based on name will occur through this method call.
+			use_browser_exe (Optional[bool]): Controls the automatic detection of the browser executable.
+				If `True` (and `browser_name_in_system` is provided), the browser executable path
+				will be automatically detected if `browser_exe` is `None`.
+				If `False` (and `browser_name_in_system` is provided), any existing `browser_exe`
+				path in the flags manager will be cleared.
+				If `None`, the current `use_browser_exe` state is maintained for the `_detect_browser_exe` logic.
+			start_page_url (str): The URL that the browser will attempt to navigate to
+				immediately after starting. Defaults to an empty string.
+			window_rect (Optional[WindowRect]): The initial window size and position settings.
+				If `None`, it defaults to a new `WindowRect()` instance, effectively resetting
+				to the browser's default window behavior.
+		"""
+		
+		...
+	
+	@abstractmethod
+	def update_settings(
+			self,
+			flags: Optional[YandexFlags] = None,
+			browser_exe: Optional[PATH_TYPEHINT] = None,
+			browser_name_in_system: Optional[str] = None,
+			use_browser_exe: Optional[bool] = None,
+			start_page_url: Optional[str] = None,
+			window_rect: Optional[WindowRect] = None,
+	):
+		"""
+		Updates various browser settings selectively without resetting others.
+
+		This method allows for dynamic updating of browser settings. Only the settings
+		for which a non-None value is provided will be updated. Settings passed as `None`
+		will retain their current values. This method can be called whether the browser
+		is active or not, but some changes might only take effect after the browser is
+		restarted.
+
+		Args:
+			flags (Optional[YandexFlags]): New browser flags to update.
+				If provided, these flags will be merged with or overwrite existing flags
+				within the flags manager. If `None`, existing flags remain unchanged.
+			browser_exe (Optional[PATH_TYPEHINT]): The new path to the browser executable.
+				If provided, this path will be set in the flags manager. If `None`, the
+				current browser executable path remains unchanged.
+			browser_name_in_system (Optional[str]): The common name of the browser (e.g., "Yandex").
+				Used in conjunction with `use_browser_exe` to automatically detect the browser executable path.
+				This parameter only takes effect if `use_browser_exe` is explicitly provided.
+				If `None`, no automatic detection based on name will occur through this method call.
+			use_browser_exe (Optional[bool]): Controls the automatic detection of the browser executable.
+				If `True` (and `browser_name_in_system` is provided), the browser executable path
+				will be automatically detected if `browser_exe` is `None`.
+				If `False` (and `browser_name_in_system` is provided), any existing `browser_exe`
+				path in the flags manager will be cleared.
+				If `None`, the current `use_browser_exe` state is maintained for the `_detect_browser_exe` logic.
+			start_page_url (Optional[str]): The new URL that the browser will attempt to navigate to
+				immediately after starting. If `None`, the current start page URL remains unchanged.
+			window_rect (Optional[WindowRect]): The new window size and position settings.
+				If `None`, the current window rectangle settings remain unchanged.
+		"""
+		
+		...

osn_selenium/base_mixin.py

@@ -0,0 +1,122 @@
+import sys
+import trio
+from contextlib import asynccontextmanager
+from typing import (
+	Any,
+	AsyncContextManager,
+	AsyncIterator,
+	Callable,
+	ContextManager,
+	Coroutine,
+	ParamSpec,
+	TypeVar
+)
+
+
+__all__ = ["TrioThreadMixin"]
+
+_METHOD_INPUT = ParamSpec("_METHOD_INPUT")
+_METHOD_OUTPUT = TypeVar("_METHOD_OUTPUT")
+
+
+class TrioThreadMixin:
+	"""
+	Provides utilities for running synchronous functions in a Trio event loop
+	with a controlled concurrency, ensuring thread safety and resource limits.
+
+	Attributes:
+		_lock (trio.Lock): A Trio Lock to ensure exclusive access for certain operations.
+		_capacity_limiter (trio.CapacityLimiter): A Trio CapacityLimiter to control the number
+			of concurrent synchronous operations.
+	"""
+	
+	def __init__(self, lock: trio.Lock, limiter: trio.CapacityLimiter) -> None:
+		"""
+		Initializes the TrioThreadMixin with a Trio Lock and CapacityLimiter.
+
+		Args:
+			lock (trio.Lock): A Trio Lock for synchronization.
+			limiter (trio.CapacityLimiter): A limiter to control thread pool concurrency.
+		"""
+		
+		self._lock = lock
+		self._capacity_limiter = limiter
+	
+	@property
+	def capacity_limiter(self) -> trio.CapacityLimiter:
+		"""
+		The Trio CapacityLimiter used for concurrency control.
+
+		Returns:
+			trio.CapacityLimiter: The limiter instance.
+		"""
+		
+		return self._capacity_limiter
+	
+	@property
+	def lock(self) -> trio.Lock:
+		"""
+		The Trio Lock used for synchronization.
+
+		Returns:
+			trio.Lock: The lock instance.
+		"""
+		
+		return self._lock
+	
+	def sync_to_trio(self, sync_function: Callable[_METHOD_INPUT, _METHOD_OUTPUT]) -> Callable[_METHOD_INPUT, Coroutine[Any, Any, _METHOD_OUTPUT]]:
+		"""
+		Wraps a synchronous function to run within a Trio thread pool using a lock and limiter.
+
+		Args:
+			sync_function (Callable[_METHOD_INPUT, _METHOD_OUTPUT]): The synchronous function to wrap.
+
+		Returns:
+			Callable[_METHOD_INPUT, Coroutine[Any, Any, _METHOD_OUTPUT]]: An async wrapper for the sync function.
+		"""
+		
+		async def wrapper(*args: _METHOD_INPUT.args, **kwargs: _METHOD_INPUT.kwargs) -> _METHOD_OUTPUT:
+			def function_with_kwargs(*args_) -> _METHOD_OUTPUT:
+				return sync_function(*args_, **kwargs)
+			
+			async with self._lock:
+				result = await trio.to_thread.run_sync(function_with_kwargs, *args, limiter=self._capacity_limiter)
+			
+				return result
+		
+		return wrapper
+	
+	def sync_to_trio_context(
+			self,
+			context_manager_factory: Callable[_METHOD_INPUT, ContextManager[_METHOD_OUTPUT]]
+	) -> Callable[_METHOD_INPUT, AsyncContextManager[_METHOD_OUTPUT]]:
+		"""
+		Converts a synchronous context manager factory to an asynchronous Trio-compatible context manager.
+
+		Args:
+			context_manager_factory (Callable[_METHOD_INPUT, ContextManager[_METHOD_OUTPUT]]): A factory function returning a context manager.
+
+		Returns:
+			Callable[_METHOD_INPUT, AsyncContextManager[_METHOD_OUTPUT]]: An async function returning an async context manager.
+		"""
+		
+		@asynccontextmanager
+		async def wrapper(*args: _METHOD_INPUT.args, **kwargs: _METHOD_INPUT.kwargs) -> AsyncIterator[_METHOD_OUTPUT]:
+			sync_context_manager = await self.sync_to_trio(sync_function=context_manager_factory)(*args, **kwargs)
+			
+			enter_ = self.sync_to_trio(sync_function=sync_context_manager.__enter__)
+			exit_ = self.sync_to_trio(sync_function=sync_context_manager.__exit__)
+			
+			try:
+				result = await enter_()
+			
+				yield result
+			except Exception as e:
+				exc_type, exc_val, exc_tb = sys.exc_info()
+			
+				if not await exit_(exc_type, exc_val, exc_tb):
+					raise e
+			else:
+				await exit_(None, None, None)
+		
+		return wrapper

osn_selenium/browsers_handler/__init__.py

@@ -1,33 +1,63 @@
 import sys
 import pathlib
-from typing import Optional
-from osn_selenium.browsers_handler.types import Browser
-from osn_selenium.errors import (
+from typing import List, Optional
+from osn_selenium._typehints import PATH_TYPEHINT
+from osn_selenium.browsers_handler.models import Browser
+from osn_selenium.exceptions.platform import (
 	PlatformNotSupportedError
 )
-from osn_selenium.browsers_handler._windows import (
-	get_installed_browsers_win32
-)
 
 
-def get_installed_browsers() -> list[Browser]:
+__all__ = [
+	"get_installed_browsers",
+	"get_path_to_browser",
+	"get_version_of_browser",
+	"get_version_of_driver"
+]
+
+if sys.platform == "win32":
+	from osn_selenium.browsers_handler._windows import (
+			get_installed_browsers as _platform_get_installed_browsers,
+			get_webdriver_version as _platform_get_webdriver_version
+	)
+elif sys.platform == "linux":
+	from osn_selenium.browsers_handler._linux import (
+			get_installed_browsers as _platform_get_installed_browsers,
+			get_webdriver_version as _platform_get_webdriver_version
+	)
+else:
+	raise PlatformNotSupportedError(platform=sys.platform)
+
+
+def get_version_of_driver(driver_path: PATH_TYPEHINT) -> Optional[str]:
+	"""
+	Retrieves the version of a given webdriver executable based on the current platform.
+
+	Args:
+		driver_path (PATH_TYPEHINT): The path to the webdriver executable.
+
+	Returns:
+		Optional[str]: The version of the webdriver as a string, or None if not determined.
+	"""
+	
+	return _platform_get_webdriver_version(driver_path=driver_path)
+
+
+def get_installed_browsers() -> List[Browser]:
 	"""
-	Retrieves a list of installed browsers on the system.
+	Retrieves a List of installed browsers on the system.
 
 	This function detects and lists the browsers installed on the operating system.
 	It supports different operating systems and uses platform-specific methods to find installed browsers.
 
 	Returns:
-		list[Browser]: A list of installed browsers. Each item in the list is a dictionary of type `Browser` containing information about the browser like name, version, and path.
+		List[Browser]: A List of installed browsers. Each item in the List is a dictionary of type `Browser` containing information about the browser like name, version, and path.
 
 	Raises:
 		PlatformNotSupportedError: If the operating system is not supported.
 	"""
 	
-	if sys.platform == "win32":
-		return get_installed_browsers_win32()
-	else:
-		raise PlatformNotSupportedError(sys.platform)
+	return _platform_get_installed_browsers()
 
 
 def get_version_of_browser(browser_name: str) -> Optional[str]:
@@ -44,8 +74,8 @@ def get_version_of_browser(browser_name: str) -> Optional[str]:
 	"""
 	
 	for browser in get_installed_browsers():
-		if browser["name"] == browser_name:
-			return browser["version"]
+		if browser.name == browser_name:
+			return browser.version
 	
 	return None
 
@@ -64,7 +94,7 @@ def get_path_to_browser(browser_name: str) -> Optional[pathlib.Path]:
 	"""
 	
 	for browser in get_installed_browsers():
-		if browser["name"] == browser_name:
-			return browser["path"]
+		if browser.name == browser_name:
+			return browser.path
 	
 	return None

osn_selenium/browsers_handler/_linux.py

@@ -0,0 +1,226 @@
+import os
+import re
+import glob
+import shutil
+import pathlib
+import subprocess
+from osn_selenium._typehints import PATH_TYPEHINT
+from typing import (
+	List,
+	Optional,
+	Set,
+	Tuple
+)
+from osn_selenium.browsers_handler.models import Browser
+from osn_selenium.exceptions.path import (
+	BrowserExecutableNotFoundError
+)
+
+
+__all__ = [
+	"get_browser_version",
+	"get_installed_browsers",
+	"get_webdriver_version"
+]
+
+
+def _get_process_version(executable_path: PATH_TYPEHINT) -> Optional[str]:
+	"""
+	Executes a process with the --version flag and extracts the version string.
+
+	Args:
+		executable_path (PATH_TYPEHINT): The file system path to the executable.
+
+	Returns:
+		Optional[str]: The extracted version string if successful, otherwise None.
+	"""
+	
+	executable_path = pathlib.Path(executable_path)
+	
+	if not executable_path.exists():
+		return None
+	
+	try:
+		process = subprocess.Popen(
+				[str(executable_path), "--version"],
+				stdout=subprocess.PIPE,
+				stderr=subprocess.PIPE
+		)
+		stdout, stderr = process.communicate()
+	
+		output = (stdout.decode("utf-8") + stderr.decode("utf-8")).strip()
+	
+		match = re.search(r"(\d+(?:\.\d+)+)", output)
+	
+		if match:
+			return match.group(1)
+	
+		return None
+	except (Exception,):
+		return None
+
+
+def get_webdriver_version(driver_path: PATH_TYPEHINT) -> Optional[str]:
+	"""
+	Retrieves the version string of a WebDriver executable.
+
+	Args:
+		driver_path (PATH_TYPEHINT): The path to the WebDriver binary.
+
+	Returns:
+		Optional[str]: The version string if found, otherwise None.
+
+	Raises:
+		BrowserExecutableNotFoundError: If the provided driver path does not exist.
+	"""
+	
+	driver_path = pathlib.Path(driver_path)
+	
+	if not driver_path.exists():
+		raise BrowserExecutableNotFoundError(path=driver_path)
+	
+	version = _get_process_version(executable_path=driver_path)
+	
+	if version:
+		return version
+	
+	return None
+
+
+def get_browser_version(browser_path: PATH_TYPEHINT) -> str:
+	"""
+	Retrieves the version string of a browser executable.
+
+	Args:
+		browser_path (PATH_TYPEHINT): The path to the browser binary.
+
+	Returns:
+		str: The version string or 'unknown' if extraction fails.
+	"""
+	
+	return _get_process_version(executable_path=browser_path) or "unknown"
+
+
+def _get_browser_from_binary(browser_name: str, binary_name: str, processed_paths: Set[pathlib.Path]) -> Optional[Tuple[Browser, pathlib.Path]]:
+	"""
+	Attempts to locate a browser binary and create a Browser model.
+
+	Args:
+		browser_name (str): The display name of the browser.
+		binary_name (str): The command or path used to execute the browser.
+		processed_paths (Set[pathlib.Path]): A set of already identified paths to avoid duplicates.
+
+	Returns:
+		Optional[Tuple[Browser, pathlib.Path]]: A tuple containing the Browser model and its resolved path.
+	"""
+	
+	full_path = shutil.which(binary_name)
+	
+	if full_path:
+		path_obj = pathlib.Path(full_path)
+	
+		if path_obj in processed_paths:
+			return None
+	
+		version = get_browser_version(browser_path=path_obj)
+	
+		browser = Browser(name=browser_name, path=path_obj, version=version)
+	
+		return browser, path_obj
+	
+	return None
+
+
+def get_installed_browsers() -> List[Browser]:
+	"""
+	Scans the Linux system for installed web browsers.
+
+	Returns:
+		List[Browser]: A list of detected Browser instances.
+	"""
+	
+	found_browsers: List[Browser] = []
+	processed_paths: Set[pathlib.Path] = set()
+	
+	search_paths = [
+		"/usr/share/applications",
+		"/usr/local/share/applications",
+		os.path.expanduser("~/.local/share/applications")
+	]
+	
+	for app_dir in search_paths:
+		if not os.path.exists(app_dir):
+			continue
+	
+		for file_path in glob.glob(os.path.join(app_dir, "*.desktop")):
+			try:
+				with open(file_path, "r", encoding="utf-8", errors="ignore") as f:
+					content = f.read()
+	
+				if "WebBrowser" not in content:
+					continue
+	
+				name = None
+				exec_cmd = None
+	
+				for line in content.splitlines():
+					if line.startswith("Name=") and not name:
+						name = line.split("=", 1)[1].strip()
+	
+					if line.startswith("Exec=") and not exec_cmd:
+						raw_cmd = line.split("=", 1)[1].strip()
+						parts = raw_cmd.split()
+	
+						if parts:
+							exec_cmd = parts[0].strip('"')
+	
+				if name and exec_cmd:
+					result = _get_browser_from_binary(
+							browser_name=name,
+							binary_name=exec_cmd,
+							processed_paths=processed_paths
+					)
+	
+					if result is None:
+						continue
+	
+					found_browser, path_obj = result
+	
+					found_browsers.append(found_browser)
+					processed_paths.add(path_obj)
+			except (Exception,):
+				continue
+				
+	for name, binaries in _STANDARD_BROWSERS_BINARIES.items():
+		for binary in binaries:
+			result = _get_browser_from_binary(browser_name=name, binary_name=binary, processed_paths=processed_paths)
+	
+			if result is None:
+				continue
+	
+			found_browser, path_obj = result
+	
+			found_browsers.append(found_browser)
+			processed_paths.add(path_obj)
+	
+	return found_browsers
+
+
+_STANDARD_BROWSERS_BINARIES = {
+	"Google Chrome": [
+		"google-chrome",
+		"google-chrome-stable",
+		"google-chrome-beta",
+		"google-chrome-unstable",
+		"chrome"
+	],
+	"Chromium": ["chromium", "chromium-browser", "chromium-freeworld"],
+	"Microsoft Edge": [
+		"microsoft-edge",
+		"microsoft-edge-stable",
+		"microsoft-edge-beta",
+		"microsoft-edge-dev",
+		"microsoft-edge-canary"
+	],
+	"Yandex": ["yandex-browser", "yandex-browser-beta", "yandex_browser"]
+}

osn_selenium/browsers_handler/_windows.py

@@ -2,8 +2,9 @@ import re
 import winreg
 import pathlib
 import subprocess
-from typing import Optional, Union
-from osn_selenium.browsers_handler.types import Browser
+from typing import List, Optional
+from osn_selenium._typehints import PATH_TYPEHINT
+from osn_selenium.browsers_handler.models import Browser
 from win32api import (
 	GetFileVersionInfo,
 	HIWORD,
@@ -11,12 +12,19 @@ from win32api import (
 )
 
 
-def get_webdriver_version(driver_path: Union[pathlib.Path, str]) -> Optional[str]:
+__all__ = [
+	"get_browser_version",
+	"get_installed_browsers",
+	"get_webdriver_version"
+]
+
+
+def get_webdriver_version(driver_path: PATH_TYPEHINT) -> Optional[str]:
 	"""
 	Retrieves the version of a given webdriver executable.
 
 	Args:
-		driver_path (Union[pathlib.Path, str]): The path to the webdriver executable. It can be a string or a pathlib.Path object.
+		driver_path (PATH_TYPEHINT): The path to the webdriver executable. It can be a string or a Path object.
 
 	Returns:
 		Optional[str]: The version of the webdriver as a string, or None if the version cannot be determined.
@@ -26,8 +34,7 @@ def get_webdriver_version(driver_path: Union[pathlib.Path, str]) -> Optional[str
 		Exception: If there is an error executing the webdriver or parsing the output.
 	"""
 	
-	if isinstance(driver_path, str):
-		driver_path = pathlib.Path(driver_path)
+	driver_path = pathlib.Path(driver_path)
 	
 	if not driver_path.exists():
 		raise FileNotFoundError(f"{driver_path} not found.")
@@ -55,41 +62,41 @@ def get_webdriver_version(driver_path: Union[pathlib.Path, str]) -> Optional[str
 		raise e
 
 
-def get_browser_version(browser_path: Union[pathlib.Path, str]) -> str:
+def get_browser_version(browser_path: PATH_TYPEHINT) -> str:
 	"""
 	Retrieves the version of a browser given its file path.
 
 	This function uses the `GetFileVersionInfo` function from the `win32api` module to extract the browser's version information from the executable file.
 
 	Args:
-		browser_path (pathlib.Path): The file path to the browser executable.
+		browser_path (Path): The file path to the browser executable.
 
 	Returns:
 		str: The version of the browser as a string, or "unknown" if the file does not exist.
 	"""
 	
-	if isinstance(browser_path, str):
-		browser_path = pathlib.Path(browser_path)
+	browser_path = pathlib.Path(browser_path)
 	
 	if not browser_path.exists():
 		return "unknown"
 	
 	info = GetFileVersionInfo(str(browser_path.resolve()), "\\")
+	
 	ms = info["FileVersionMS"]
 	ls = info["FileVersionLS"]
 	
 	return ".".join(map(str, (HIWORD(ms), LOWORD(ms), HIWORD(ls), LOWORD(ls))))
 
 
-def get_installed_browsers_win32() -> list[Browser]:
+def get_installed_browsers() -> List[Browser]:
 	"""
-	Retrieves a list of installed browsers on a Windows system by querying the registry.
+	Retrieves a List of installed browsers on a Windows system by querying the registry.
 
 	This function iterates through different registry locations to identify installed browsers and their paths.
-	It constructs a list of unique `Browser` objects, each representing an installed browser.
+	It constructs a List of unique `Browser` objects, each representing an installed browser.
 
 	Returns:
-		list[Browser]: A list of unique installed browsers.
+		List[Browser]: A List of unique installed browsers.
 	"""
 	
 	installed_browsers = []

osn_selenium/browsers_handler/{types.py → models.py}

@@ -1,8 +1,11 @@
 import pathlib
-from typing import TypedDict
+from osn_selenium._base_models import DictModel
 
 
-class Browser(TypedDict):
+__all__ = ["Browser"]
+
+
+class Browser(DictModel):
 	"""
 	Represents a browser installed on the system.