osn-selenium v1.2.0

osn-selenium v1.2.0 - The BiDi Bridge & Architecture Expansion

This release marks a significant milestone in the library's evolution with the introduction of the experimental trio_bidi architecture. This new mode moves away from thread-based wrapping and implements a native asynchronous driver that communicates directly with the browser via the WebDriver BiDi protocol over WebSockets. Additionally, this update brings substantial refactoring to the DevTools manager, improves lifecycle management across all architectures, and enhances the robustness of Trio thread synchronization.

Key Improvements in v1.2.0:

1. New Experimental Architecture: trio_bidi
   A completely new driver architecture has been introduced. Unlike trio_threads, which runs synchronous Selenium commands in a thread pool, trio_bidi establishes a direct BiDi session.

   • Native Async: Operations are handled via trio tasks and WebSockets without blocking threads.
   • BiDi Bridge: Implements a mapping layer that converts standard W3C WebDriver commands into BiDi protocol commands and maps the responses back to W3C format.
   • Connection Pool: Features a robust BiDiConnectionPool to manage WebSocket messages and task dispatching.
   • Note: This architecture is currently experimental and may not cover 100% of the W3C spec yet.

2. Refactored DevTools Lifecycle Management
   The DevTools manager and its associated lifecycles have been overhauled for better stability.

   • AsyncExitStack: Adopted contextlib.AsyncExitStack for more reliable resource cleanup (connections, nurseries) during shutdown.
   • Robust Error Handling: Improved handling of connection interruptions (WebSocketEndExceptions, TrioEndExceptions) to prevent "zombie" processes or hanging tasks.
   • Moved Utilities: General utility decorators and exception helpers have been moved from osn_selenium.dev_tools to the root osn_selenium package for broader usage.

3. Enhanced Trio Threads Synchronization
   The core logic for wrapping synchronous calls in asynchronous environments has been upgraded.

   • Context Variable Exchange: The sync_to_trio helper now supports exchanging context variables between the main Trio loop and the worker threads, ensuring execution context is preserved.
   • Unified Locking: Logic for trio.Lock and CapacityLimiter has been centralized in the new _trio_threads_helpers.py module.

4. Standardized WebDriver Lifecycle
   The start and stop sequences for WebDrivers have been standardized across sync, trio_threads, and trio_bidi.

   • Stop vs. Close: stop_webdriver is now the standard method for terminating sessions, ensuring consistency in how drivers are torn down.
   • Context Managers: Updated __enter__ and __aenter__ implementations to ensure start_webdriver and stop_webdriver are called correctly, making usage within with and async with blocks more reliable.

5. Exception Hierarchy Refinement

   • BiDi Exceptions: Introduced specific exceptions for the new architecture, such as BiDiBridgeError, CommandNotMappedToBiDiError, and BiDiExecutionError.
   • Exception Wrappers: The ExceptionThrown wrapper is now available in osn_selenium.exceptions.base to help manage exceptions returned from background tasks without crashing the event loop immediately.

Putting It All Together:
v1.2.0 is a foundational release that lays the groundwork for a truly asynchronous future for osn-selenium. While users can continue to rely on the stable trio_threads implementation, the new trio_bidi architecture offers a glimpse into higher-performance, non-blocking browser automation. Coupled with stricter lifecycle management and cleaner internal organization, this update improves the library's stability and extensibility.