osn-selenium 1.0.0__tar.gz → 1.2.0__tar.gz

{osn_selenium-1.0.0 → osn_selenium-1.2.0}/PKG-INFO

@@ -1,9 +1,11 @@
 Metadata-Version: 2.4
 Name: osn-selenium
-Version: 1.0.0
+Version: 1.2.0
 Summary: An advanced, asynchronous wrapper for Selenium designed for fine-grained browser control. It leverages `trio` for async operations, provides human-like action chains for more natural automation, and offers deep integration with the Chrome DevTools Protocol (CDP) for advanced features like network interception. The library is structured to be extensible, with built-in support for Blink-based browsers like Chrome, Edge, and Yandex.
-Author: oddshellnick
-Author-email: oddshellnick.programming@gmail.com
+Author-email: oddshellnick <oddshellnick.programming@gmail.com>
+Project-URL: Homepage, https://github.com/oddshellnick/osn-selenium
+Project-URL: Issues, https://github.com/oddshellnick/osn-selenium/issues
+Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 Requires-Dist: trio<1.0.0,>=0.32.0
 Requires-Dist: selenium<5.0.0,>=4.40.0
@@ -11,17 +13,13 @@ Requires-Dist: pydantic<3.0.0,>=2.0.0
 Requires-Dist: trio-websocket<1.0.0,>=0.12.0
 Requires-Dist: pywin32>=310; sys_platform == "win32"
 Requires-Dist: osn-system-utils<0.1.0,>=0.0.4
-Dynamic: author
-Dynamic: author-email
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: requires-dist
-Dynamic: summary
 
 # osn-selenium: Advanced Selenium Wrapper with Async Support and Fingerprinting Protection
 
 osn-selenium is a robust wrapper around Selenium WebDriver designed for automation of Blink-based browsers (Chrome, Edge, Yandex). It extends standard Selenium capabilities by providing native asynchronous support via Trio, deep integration with the Chrome DevTools Protocol (CDP), sophisticated browser fingerprint spoofing, and human-like user interaction simulation.
 
+For more detailed information, please visit the [wiki page](https://github.com/oddshellnick/osn-selenium/wiki).
+
 ## Technologies
 
 | Name       | Badge                                                                                                                                               | Description                                                                                                                                            |
@@ -67,12 +65,23 @@ osn-selenium is a robust wrapper around Selenium WebDriver designed for automati
         pip install osn-selenium
         ```
 
+        **With pip (beta versions):**
+        ```bash
+        pip install -i https://test.pypi.org/simple/ osn_system_utils
+        ```
+
     *   **With git:**
         ```bash
         pip install git+https://github.com/oddshellnick/osn-selenium.git
         ```
         *(Ensure you have git installed)*
 
+    *   **With git (beta versions):**
+        ```bash
+        pip install git+https://github.com/oddshellnick/osn-selenium.git@dev
+        ```
+        *(Ensure you have git installed)*
+
 2.  **Install the required Python packages using pip:**
 
     ```bash
@@ -224,10 +233,15 @@ Utilities for executing JS and managing browser fingerprints.
 
 ## Notes
 
+*   **CDP Versioning and External Packages:** 
+    This library supports a modular CDP (Chrome DevTools Protocol) architecture. Since standard Selenium distributions often deprecate or remove older protocol versions, we maintain a dedicated repository for all versions at [osn-selenium-cdp](https://github.com/oddshellnick/osn-selenium-cdp).
+    *   **Manual Installation:** You can install specific CDP support by targeting the corresponding branch (e.g., `pip install git+https://github.com/oddshellnick/osn-selenium-cdp.git@v131`).
+    *   **Structure Requirement:** If you choose to add or create CDP version packages manually, they **must strictly follow the directory structure** used in the `osn-selenium-cdp` repository. This ensures that the internal `MetaPathFinder` hook can correctly intercept and redirect imports from `selenium.webdriver.common.devtools`. Deviating from this structure will result in `CDPPackageError` or `ImportError`.
 *   **Concurrency Constraints in `trio_threads`:** 
     The `trio_threads` implementation is built using a unified `trio.Lock`. This means that every driver function and every associated instance (including `ActionChains`, `WebElement`, `Alert`, etc.) can execute only one operation at a time. Do not attempt to parallelize multiple operations (coroutines) within a single browser instance, as they will be queued sequentially. The primary purpose of this asynchronous implementation is to enable the simultaneous management of **multiple browser instances** within a single event loop, rather than concurrent interactions with one browser.
 *   **CDP Domains and Background Tasks:** 
     When configuring the domains for network interception, it is highly recommended to provide a `target_background_task` in your `DevToolsSettings`. This is especially critical for websites that dynamically create numerous targets (such as iframes or workers). Without a proper background task to handle these events, the browser's execution flow might hang or fail to process requests for nested targets properly.
+*   **Experimental `trio_bidi` Architecture:** A new experimental architecture, `trio_bidi`, has been introduced. While it currently does not cover 100% of browser capabilities, it supports all core functionalities, including page navigation and element interactions, through native BiDi communication.
 
 ## Future Notes
 
@@ -236,4 +250,4 @@ Utilities for executing JS and managing browser fingerprints.
 *   **macOS Support:** Extending browser auto-detection and lifecycle management for macOS environments.
 *   **High-Level CDP Handlers:** Expanding the `dev_tools.domains` module to include simplified event-driven logic for `Network`, `Page`, and `Runtime` domains, similar to the current `Fetch` implementation.
 *   **Enhanced Human-Like Actions:** Adding more complex Bezier-based mouse movement patterns and advanced typing jitter to further decrease automation footprints.
-*   **Single-Instance Internal Concurrency Research:** While the current `trio_threads` implementation is optimized for managing multiple browser instances concurrently, we are researching ways to enable parallel command execution within a *single* browser instance. This long-term goal involves moving away from the global `trio.Lock` toward a more granular task-dispatching system (potentially using `trio.MemorySendChannel` or direct CDP interaction) to allow simultaneous operations without protocol desynchronization.
+*   **Full BiDi Coverage:** Implementing comprehensive Selenium feature coverage using BiDi mappings to eventually replace the need for synchronous thread pools in async mode.

osn_selenium-1.0.0/osn_selenium.egg-info/PKG-INFO → osn_selenium-1.2.0/README.md

@@ -1,27 +1,9 @@
-Metadata-Version: 2.4
-Name: osn-selenium
-Version: 1.0.0
-Summary: An advanced, asynchronous wrapper for Selenium designed for fine-grained browser control. It leverages `trio` for async operations, provides human-like action chains for more natural automation, and offers deep integration with the Chrome DevTools Protocol (CDP) for advanced features like network interception. The library is structured to be extensible, with built-in support for Blink-based browsers like Chrome, Edge, and Yandex.
-Author: oddshellnick
-Author-email: oddshellnick.programming@gmail.com
-Description-Content-Type: text/markdown
-Requires-Dist: trio<1.0.0,>=0.32.0
-Requires-Dist: selenium<5.0.0,>=4.40.0
-Requires-Dist: pydantic<3.0.0,>=2.0.0
-Requires-Dist: trio-websocket<1.0.0,>=0.12.0
-Requires-Dist: pywin32>=310; sys_platform == "win32"
-Requires-Dist: osn-system-utils<0.1.0,>=0.0.4
-Dynamic: author
-Dynamic: author-email
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: requires-dist
-Dynamic: summary
-
 # osn-selenium: Advanced Selenium Wrapper with Async Support and Fingerprinting Protection
 
 osn-selenium is a robust wrapper around Selenium WebDriver designed for automation of Blink-based browsers (Chrome, Edge, Yandex). It extends standard Selenium capabilities by providing native asynchronous support via Trio, deep integration with the Chrome DevTools Protocol (CDP), sophisticated browser fingerprint spoofing, and human-like user interaction simulation.
 
+For more detailed information, please visit the [wiki page](https://github.com/oddshellnick/osn-selenium/wiki).
+
 ## Technologies
 
 | Name       | Badge                                                                                                                                               | Description                                                                                                                                            |
@@ -67,12 +49,23 @@ osn-selenium is a robust wrapper around Selenium WebDriver designed for automati
         pip install osn-selenium
         ```
 
+        **With pip (beta versions):**
+        ```bash
+        pip install -i https://test.pypi.org/simple/ osn_system_utils
+        ```
+
     *   **With git:**
         ```bash
         pip install git+https://github.com/oddshellnick/osn-selenium.git
         ```
         *(Ensure you have git installed)*
 
+    *   **With git (beta versions):**
+        ```bash
+        pip install git+https://github.com/oddshellnick/osn-selenium.git@dev
+        ```
+        *(Ensure you have git installed)*
+
 2.  **Install the required Python packages using pip:**
 
     ```bash
@@ -224,10 +217,15 @@ Utilities for executing JS and managing browser fingerprints.
 
 ## Notes
 
+*   **CDP Versioning and External Packages:** 
+    This library supports a modular CDP (Chrome DevTools Protocol) architecture. Since standard Selenium distributions often deprecate or remove older protocol versions, we maintain a dedicated repository for all versions at [osn-selenium-cdp](https://github.com/oddshellnick/osn-selenium-cdp).
+    *   **Manual Installation:** You can install specific CDP support by targeting the corresponding branch (e.g., `pip install git+https://github.com/oddshellnick/osn-selenium-cdp.git@v131`).
+    *   **Structure Requirement:** If you choose to add or create CDP version packages manually, they **must strictly follow the directory structure** used in the `osn-selenium-cdp` repository. This ensures that the internal `MetaPathFinder` hook can correctly intercept and redirect imports from `selenium.webdriver.common.devtools`. Deviating from this structure will result in `CDPPackageError` or `ImportError`.
 *   **Concurrency Constraints in `trio_threads`:** 
     The `trio_threads` implementation is built using a unified `trio.Lock`. This means that every driver function and every associated instance (including `ActionChains`, `WebElement`, `Alert`, etc.) can execute only one operation at a time. Do not attempt to parallelize multiple operations (coroutines) within a single browser instance, as they will be queued sequentially. The primary purpose of this asynchronous implementation is to enable the simultaneous management of **multiple browser instances** within a single event loop, rather than concurrent interactions with one browser.
 *   **CDP Domains and Background Tasks:** 
     When configuring the domains for network interception, it is highly recommended to provide a `target_background_task` in your `DevToolsSettings`. This is especially critical for websites that dynamically create numerous targets (such as iframes or workers). Without a proper background task to handle these events, the browser's execution flow might hang or fail to process requests for nested targets properly.
+*   **Experimental `trio_bidi` Architecture:** A new experimental architecture, `trio_bidi`, has been introduced. While it currently does not cover 100% of browser capabilities, it supports all core functionalities, including page navigation and element interactions, through native BiDi communication.
 
 ## Future Notes
 
@@ -236,4 +234,4 @@ Utilities for executing JS and managing browser fingerprints.
 *   **macOS Support:** Extending browser auto-detection and lifecycle management for macOS environments.
 *   **High-Level CDP Handlers:** Expanding the `dev_tools.domains` module to include simplified event-driven logic for `Network`, `Page`, and `Runtime` domains, similar to the current `Fetch` implementation.
 *   **Enhanced Human-Like Actions:** Adding more complex Bezier-based mouse movement patterns and advanced typing jitter to further decrease automation footprints.
-*   **Single-Instance Internal Concurrency Research:** While the current `trio_threads` implementation is optimized for managing multiple browser instances concurrently, we are researching ways to enable parallel command execution within a *single* browser instance. This long-term goal involves moving away from the global `trio.Lock` toward a more granular task-dispatching system (potentially using `trio.MemorySendChannel` or direct CDP interaction) to allow simultaneous operations without protocol desynchronization.
+*   **Full BiDi Coverage:** Implementing comprehensive Selenium feature coverage using BiDi mappings to eventually replace the need for synchronous thread pools in async mode.

osn_selenium-1.2.0/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-1.2.0/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-1.2.0/osn_selenium/_decorators.py

@@ -0,0 +1,57 @@
+import inspect
+import functools
+from osn_selenium.exceptions.base import ExceptionThrown
+from osn_selenium._exception_helpers import log_exception
+from typing import (
+	Any,
+	Callable,
+	ParamSpec,
+	TypeVar
+)
+from osn_selenium.exceptions.instance import NotExpectedTypeError
+
+
+__all__ = ["log_on_error"]
+
+_METHOD_INPUT = ParamSpec("_METHOD_INPUT")
+_METHOD_OUTPUT = TypeVar("_METHOD_OUTPUT")
+_METHOD = TypeVar("_METHOD", bound=Callable[..., Any])
+
+
+def log_on_error(func: _METHOD) -> _METHOD:
+	"""
+	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 (_METHOD): The asynchronous function to be wrapped.
+
+	Returns:
+		_METHOD: The wrapped asynchronous function.
+	"""
+	
+	@functools.wraps(func)
+	def sync_wrapper(*args: _METHOD_INPUT.args, **kwargs: _METHOD_INPUT.kwargs) -> _METHOD_OUTPUT:
+		try:
+			return func(*args, **kwargs)
+		except BaseException as exception:
+			log_exception(exception)
+			return ExceptionThrown(exception)
+	
+	@functools.wraps(func)
+	async def async_wrapper(*args: _METHOD_INPUT.args, **kwargs: _METHOD_INPUT.kwargs) -> _METHOD_OUTPUT:
+		try:
+			return await func(*args, **kwargs)
+		except BaseException as exception:
+			log_exception(exception)
+			return ExceptionThrown(exception)
+	
+	if inspect.iscoroutinefunction(func):
+		return async_wrapper
+	
+	if inspect.isfunction(func):
+		return sync_wrapper
+	
+	raise NotExpectedTypeError(expected_type=["coroutine function", "function"], received_instance=func)

osn_selenium-1.2.0/osn_selenium/_trio_threads_helpers.py

@@ -0,0 +1,157 @@
+import sys
+import trio
+import contextvars
+from contextlib import asynccontextmanager
+from typing import (
+	Any,
+	AsyncContextManager,
+	AsyncIterator,
+	Callable,
+	ContextManager,
+	Coroutine,
+	ParamSpec,
+	Tuple,
+	TypeVar
+)
+
+
+__all__ = ["sync_to_trio", "sync_to_trio_context"]
+
+_METHOD_INPUT = ParamSpec("_METHOD_INPUT")
+_METHOD_OUTPUT = TypeVar("_METHOD_OUTPUT")
+
+
+def sync_to_trio_context(
+		context_manager_factory: Callable[_METHOD_INPUT, ContextManager[_METHOD_OUTPUT]],
+		lock_object: trio.Lock,
+		capacity_limiter_object: trio.CapacityLimiter,
+		lock: bool,
+		exchange_context: bool,
+) -> 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]]): Factory function returning a context manager.
+		lock_object (trio.Lock): Trio lock for synchronization.
+		capacity_limiter_object (trio.CapacityLimiter): Trio capacity limiter.
+		lock (bool): Whether to use the internal lock for synchronization.
+		exchange_context (bool): Whether to synchronize context variables between threads.
+
+	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]:
+		"""
+		Internal async context manager wrapper.
+
+		Args:
+			*args (_METHOD_INPUT.args): Positional arguments for the factory.
+			**kwargs (_METHOD_INPUT.kwargs): Keyword arguments for the factory.
+
+		Returns:
+			AsyncIterator[_METHOD_OUTPUT]: An async iterator yielding the context resource.
+		"""
+		
+		sync_context_manager = await sync_to_trio(
+				sync_function=context_manager_factory,
+				lock_object=lock_object,
+				capacity_limiter_object=capacity_limiter_object,
+				lock=lock,
+				exchange_context=exchange_context,
+		)(*args, **kwargs)
+		
+		enter_ = sync_to_trio(
+				sync_function=sync_context_manager.__enter__,
+				lock_object=lock_object,
+				capacity_limiter_object=capacity_limiter_object,
+				lock=lock,
+				exchange_context=exchange_context,
+		)
+		exit_ = sync_to_trio(
+				sync_function=sync_context_manager.__exit__,
+				lock_object=lock_object,
+				capacity_limiter_object=capacity_limiter_object,
+				lock=lock,
+				exchange_context=exchange_context,
+		)
+		
+		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
+
+
+def sync_to_trio(
+		sync_function: Callable[_METHOD_INPUT, _METHOD_OUTPUT],
+		lock_object: trio.Lock,
+		capacity_limiter_object: trio.CapacityLimiter,
+		lock: bool,
+		exchange_context: bool,
+) -> 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.
+		lock_object (trio.Lock): Trio lock for synchronization.
+		capacity_limiter_object (trio.CapacityLimiter): Trio capacity limiter.
+		lock (bool): Whether to use the provided lock.
+		exchange_context (bool): Whether to synchronize context variables between threads.
+
+	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:
+		"""
+	Internal async wrapper for the synchronous function.
+
+	Args:
+		*args (_METHOD_INPUT.args): Positional arguments for the sync function.
+		**kwargs (_METHOD_INPUT.kwargs): Keyword arguments for the sync function.
+
+	Returns:
+		_METHOD_OUTPUT: The result of the synchronous function execution.
+	"""
+		
+		def function_with_kwargs(*args_) -> Tuple[_METHOD_OUTPUT, contextvars.Context]:
+			"""
+		Helper to pass keyword arguments to trio.to_thread.run_sync.
+
+		Args:
+			*args_: Positional arguments passed from the outer scope.
+
+		Returns:
+			Tuple[_METHOD_OUTPUT, contextvars.Context]: Result of original sync function and the thread context.
+		"""
+			
+			sync_result = sync_function(*args_, **kwargs)
+			context_vars = contextvars.copy_context()
+			
+			return sync_result, context_vars
+		
+		if lock:
+			async with lock_object:
+				result, child_context_vars = await trio.to_thread.run_sync(function_with_kwargs, *args, limiter=capacity_limiter_object)
+		else:
+			result, child_context_vars = await trio.to_thread.run_sync(function_with_kwargs, *args, limiter=capacity_limiter_object)
+		
+		if exchange_context:
+			for var, value in child_context_vars.items():
+				var.set(value)
+		
+		return result
+	
+	return wrapper

{osn_selenium-1.0.0 → osn_selenium-1.2.0}/osn_selenium/_typehints.py

@@ -14,6 +14,6 @@ __all__ = [
 ]
 
 DEVICES_TYPEHINT = Union[PointerInput, KeyInput, WheelInput]
-ARCHITECTURES_TYPEHINT = Literal["sync", "trio_threads"]
+ARCHITECTURES_TYPEHINT = Literal["sync", "trio_threads", "trio_bidi"]
 PATH_TYPEHINT = Union[str, bytes, pathlib.Path, os.PathLike]
 TYPES_FOR_FLATTENING_TYPEHINT = Union[str, Type]