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.

osn-selenium v1.2.0-beta.0

osn-selenium v1.2.0-beta.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-beta.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-beta.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.

osn-selenium v1.1.0

osn-selenium v1.1.0 - Modular CDP Architecture & Expanded Documentation

Release v1.1.0 marks a significant architectural shift for the library, moving towards a modular approach for Chrome DevTools Protocol (CDP) handling. This update dramatically reduces the core library's footprint by decoupling version-specific CDP logic and introduces a sophisticated lazy-loading mechanism. Additionally, this release launches a comprehensive Wiki, standardizes packaging with pyproject.toml, and refines asynchronous logging controls.

Key Improvements in v1.1.0:

1. Modular CDP Architecture & Lazy Loading:
   The massive internal library of CDP domains (v140-v144) has been decoupled from the core package.

   • Dynamic Imports: The library now utilizes a custom MetaPathFinder to lazy-load CDP versions only when requested.
   • External Packages: Version-specific logic is now handled via external packages (e.g., osn-selenium-cdp). If a required version is missing, the new CDPPackageError provides the exact command to install it.
   • Custom Paths: WebDrivers now accept cdp_versioned_packages_paths, allowing users to map specific protocol versions to local directories for custom or experimental CDP support.

2. Comprehensive Wiki Documentation:
   We have published a complete Wiki covering every aspect of the framework.

   • Guides: Detailed explanations on Core Architecture, Anti-Fingerprinting, Human-Like Interactions, and Trio-based concurrency.
   • Reference: Deep dives into Flags Management, Instance wrappers, and DevTools orchestration.

3. Modern Packaging with pyproject.toml:
   The build system has been migrated from setup.py to pyproject.toml. This ensures better compatibility with modern Python tooling, stricter dependency management, and a cleaner project structure.

4. Enhanced Logging Flow Control:
   The DevTools logging system now includes a send_wait parameter in CDPLoggerSettings and FingerprintLoggerSettings.

   • True: The driver will await the log transmission (safer for debugging).
   • False: Logs are sent via send_nowait (default, better performance for high-throughput scenarios).

5. Refactored Asynchronous Core:

   • Renamed base_mixin.py to trio_threads_mixin.py to better reflect its role in bridging synchronous Selenium calls to the Trio event loop.
   • Improved lifecycle management in background_task_decorator to handle Trio cancellation scopes more gracefully during target detachment.

Putting It All Together:
osn-selenium v1.1.0 transforms the library from a monolithic package into a lightweight, extensible framework. By externalizing the rapidly changing CDP definitions, the core remains stable while allowing support for any Chrome version via plugins. Combined with the new official Wiki and modern build standards, this release lays the groundwork for long-term maintainability and easier adoption.

osn-selenium v1.1.0-beta.1

osn-selenium v1.1.0-beta.1 - Refined Mixins and API Optimization

This beta release focuses on streamlining the internal architecture, improving the developer experience through more consistent API calls, and enhancing our documentation resources. We've refined how ActionChains are composed and optimized the switch_to logic to better align with standard expectations.

Key Improvements in v1.1.0-beta.1:

1. Synchronous switch_to Method: The switch_to method in the trio_threads implementation has been changed from asynchronous to synchronous. This adjustment simplifies the syntax for switching contexts (such as windows or frames) while maintaining full compatibility with the underlying Trio thread management.
2. Expanded ActionChains Support: We have integrated additional essential mixins—MoveMixin, ScrollMixin, and KeyboardMixin—into both synchronous and Trio-based ActionChains. This ensures that standard interaction patterns are fully supported alongside our human-like movement features.
3. Core Architecture Refactoring:
   • Renamed base_mixin.py to trio_threads_mixin.py to more accurately describe its role within the library.
   • Centralized internal Pydantic models (DictModel and ExtraDictModel) into a new _base_models.py file, reducing clutter and improving dependency management across the project.
4. Documentation Update: The README.md now includes a direct link to our official Wiki, providing users with easier access to detailed guides and technical documentation.
5. Internal Enhancements: Performed a minor refactor of various modules and updated the file_detector_context implementation to ensure more reliable file handling in asynchronous environments.

Putting It All Together:
Version 1.1.0-beta.1 is a refinement step that polishes the foundations of osn-selenium. By making switch_to synchronous and expanding the capability of ActionChains, we are making the library more intuitive to use. These changes, paired with cleaner internal code organization, set the stage for a stable v1.1.0 release.

osn-selenium v1.1.0-beta.0

osn-selenium v1.1.0-beta.0 - Modular CDP Architecture

We are excited to announce the release of osn-selenium v1.1.0-beta.0. This version marks a major architectural shift in how the library handles the Chrome DevTools Protocol (CDP). By moving towards a modular versioning system, we ensure long-term compatibility with various browser versions while keeping the core library lightweight and maintainable.

Key Improvements in v1.1.0-beta.0:

1. Modular CDP Versioning System: We have transitioned from a monolithic CDP implementation to a modular one. Core CDP executors are now handled through a custom MetaPathFinder import hook. This allows the library to support external, version-specific CDP packages (hosted at osn-selenium-cdp) without bloating the main installation.
2. Dynamic CDP Access: Added a new get() method to CDPExecutor classes (both Sync and Trio-based). This allows developers to dynamically load and access any specific CDP package version. It includes lazy loading and built-in validation to ensure the required version-specific package is installed.
3. Enhanced Target Logging: Updated the DevTools target logging functions with a new send_wait parameter. This provides better control over log delivery; when enabled, the system will wait for logs to be successfully sent through the channel, reducing the risk of dropped log entries during high-traffic sessions.
4. Smart Dependency Management: Introduced CDPPackageError, which provides helpful instructions and direct pip commands if a user attempts to access a CDP version that isn't currently installed in their environment.
5. Optimized Performance: Significant cleanup of the codebase was performed, including the removal of hundreds of redundant abstract classes and optimized imports, resulting in a faster initialization time.

Putting It All Together:
This release transforms osn-selenium into a more flexible and robust framework. By decoupling the CDP protocol versions from the core library, we've solved the common issue of protocol deprecation in standard Selenium. Combined with the improved logging reliability, this version provides a professional-grade foundation for complex browser automation and fingerprinting tasks.

osn-selenium v1.0.1-beta.1

osn-selenium v1.0.1-beta.1 - Core Infrastructure Update and Logging Enhancements

This beta release marks a significant step in modernizing the library's internal structure and refining the developer experience. We’ve transitioned to the latest Python packaging standards, improved the reliability of background task management within the DevTools module, and optimized how logging data is filtered and processed.

Key Improvements in v1.0.1-beta.1:

1. Modernized Build System: We have replaced the legacy setup.py and MANIFEST.in files with a unified pyproject.toml configuration. This aligns the project with modern PEP 517 standards, making the installation and build process more robust and maintainable.
2. Refined DevTools Logging Logic: The logging pipeline for CDP and Fingerprint events has been optimized. Filters are now applied more efficiently before entries are sent to the logging channels, reducing unnecessary overhead and ensuring that only relevant data is recorded based on your configuration.
3. Enhanced Background Task Management: Introduced Trio CancelScope support for DevTools targets. This update provides better control over the lifecycle of background tasks, ensuring they are properly cancelled and cleaned up when a target is shut down, preventing potential resource leaks.
4. CI/CD Workflow Improvements: The GitHub Actions publishing workflow has been overhauled. It now automatically synchronizes the release version directly from pyproject.toml and includes dedicated logic for seamless deployments to both TestPyPI and the main PyPI repository.
5. Code Documentation & Type Hinting Refactor: We’ve performed a cleanup of docstrings across the codebase, removing redundant attribute lists in favor of cleaner, more readable documentation. Additionally, type hints have been expanded (including Union types and improved ParamSpec usage) to provide better IDE support and static analysis.
6. Internal API Cleanup: Several internal properties were renamed for consistency (e.g., transitioning from private _driver_impl to public driver accessors in bridges), making the internal architecture more intuitive for contributors.

Putting It All Together:
This update focuses on "under-the-hood" stability and preparation for future features. By modernizing our packaging and refining how asynchronous tasks and logs are handled, v1.0.1-beta.1 provides a more reliable foundation for high-performance browser automation. Developers can now also find clearer instructions in the README for installing specific beta versions via pip or git.

osn-selenium v1.0.1-beta.0

setup.py replaced with pyproject.toml

osn-selenium v1.0.0

osn-selenium v1.0.0 - The Framework Evolution: Async, Anti-Detect, and Unified Architecture

We are proud to announce the major release of osn-selenium v1.0.0. This update represents a complete rewrite and restructuring of the library, transitioning it from a utility wrapper into a sophisticated browser automation framework. v1.0.0 introduces a modular mixin-based architecture, full support for asynchronous operations via Trio, robust data validation using Pydantic, and a powerful new suite of anti-fingerprinting tools. This release provides the tooling necessary to build undetectable, reliable, and scalable browser automation solutions.

Key Improvements in v1.0.0:

1. Dual Operation Modes (Synchronous & Trio-Async):
   The library has been split into two distinct operational namespaces to handle different use cases:
   • Synchronous (osn_selenium.webdrivers.sync): Standard blocking execution similar to vanilla Selenium, optimized for linear scripts.
   • Asynchronous (osn_selenium.webdrivers.trio_threads): Fully async implementation using trio. This allows for the concurrent management of multiple browser instances within a single event loop, decoupled from the blocking nature of standard WebDriver calls.
2. Advanced Fingerprint Spoofing:
   A new defensive fingerprint module has been introduced to help scripts evade anti-bot detection systems.
   • Injection Scripts: Automatically injects JavaScript to hook into browser APIs (Canvas, WebGL, AudioContext, Fonts, Screen properties) before the page loads.
   • Noise Generation: Supports configurable noise (static or random) to alter fingerprint signatures slightly, making unique identification difficult.
   • Registry System: Allows for fine-grained control over which APIs are spoofed via FingerprintSettings.
3. Modular Mixin & Executor Architecture:
   The monolithic WebDriver classes have been refactored into granular mixins (e.g., CoreActionsMixin, BlinkNetworkMixin, CoreDevToolsMixin).
   • Unified Implementation: The core logic for CDP commands and JS execution now resides in unified classes, which are then adapted by specific Sync and Trio executors.
   • Executor Pattern: This pattern ensures that logic is not duplicated between modes while maintaining strict type safety and execution context awareness.
4. Deep Chrome DevTools Protocol (CDP) Integration:
   Access to CDP features is now strictly typed and vastly expanded beyond simple network interception.
   • Full Domain Coverage: Typed executors have been added for almost every available CDP domain, including Accessibility, Animation, Audits, CacheStorage, CSS, Database, DeviceOrientation, HeadlessExperimental, IndexedDB, LayerTree, Performance, Memory, ServiceWorker, and WebAudio.
   • Direct Access: Domains are accessible via properties (e.g., driver.cdp.network, driver.cdp.page), returning typed dictionaries rather than raw JSON.
   • BiDi Support: Improved integration with WebDriver BiDi connections for event listening.
5. Revamped Browser Flags System:
   Configuration of browser arguments and options has been extracted into a dedicated osn_selenium.flags package.
   • Hierarchical Structure: Flags follow a strict inheritance chain (Browser -> Blink -> Chrome -> Yandex/Edge).
   • Validation: The BrowserFlagsManager leverages TypedDict and validators to automatically check value types (boolean, path, integer) before applying flags, preventing startup crashes.
6. Expanded Platform Support (Linux):
   The browsers_handler module has been upgraded to support Linux environments. The library scans standard Linux directories and .desktop files to locate installed binaries and uses subprocess logic to dynamically fetch browser versions.
7. Channel-Based Logging System:
   The logging system has been rewritten to handle the high throughput of CDP events without blocking the application.
   • Decoupled Writing: In async mode, logs are passed through trio channels, separating the event listener (producer) from the file writer (consumer).
   • Target-Specific Logs: Logs are now separated by "Target" (Tab/Page). Each open tab gets its own log file, facilitating easier debugging of multi-tab workflows.
   • Fingerprint Isolation: Distinct loggers exist for generic CDP events and specific Fingerprint detection events.
8. Enhanced Human-Like Interactions:
   The HumanLikeActionChains have been refined and standardized.
   • Natural Movement: Mouse movements utilize improved Bezier curve algorithms to simulate human curvature and speed variations.
   • Smart Input: Text input includes variable delays, and scrolling logic handles viewport offsets more naturally to avoid mechanical behavior.
9. Strict Concurrency Controls:
   To ensure thread safety when using Selenium in an async environment, v1.0.0 enforces strict concurrency limits.
   • Capacity Limiters: The TrioThreadWebDriver shares a trio.CapacityLimiter across all derived instances.
   • Global Locking: A global trio.Lock ensures that operations on a specific browser session remain atomic, preventing the async event loop from flooding the synchronous driver with parallel commands.
10. Robust Process Management:
    The library now includes sophisticated logic for managing the browser process lifecycle. This includes active checks for "zombie" processes after crashes and netstat logic (on Windows) to discover and attach to pre-running browser sessions.
11. Unified Instance Architecture (osn_selenium.instances):
    Standard Selenium objects (like WebElement, ShadowRoot, Alert, Storage) have been encapsulated within a robust wrapper system.
    • Consistent API: Whether running in Synchronous or Asynchronous mode, the API surface remains identical. You interact with a WebElement wrapper that automatically handles the underlying execution strategy (direct calls vs. threaded dispatch).
    • Automatic Conversion: The library automatically converts legacy Selenium objects into these unified wrappers during runtime (e.g., when finding elements or switching frames), ensuring you never have to manually wrap or unwrap objects.
    • Extended Functionality: These wrappers extend standard Selenium capabilities with helper methods, such as screenshot_as_png directly on elements or simplified ShadowRoot interactions.

Putting It All Together:
osn-selenium v1.0.0 transforms the library into a comprehensive framework for browser automation. By decoupling execution logic, we enable seamless support for both linear synchronous scripts and high-concurrency asynchronous applications. With the addition of Linux support, native Yandex integration, and the defensive Fingerprinting module, developers now have a standardized, robust, and type-safe API to build undetectable and resilient automation tools.

osn-selenium v1.0.0-beta.9

osn-selenium v1.0.0-beta.9 - Performance Optimization and Core Refactoring

This beta release focuses on significant internal architecture improvements, aimed at reducing library overhead, accelerating startup times, and streamlining dependencies. We have moved away from heavy data-processing libraries in favor of a leaner, more specialized stack while optimizing how Chrome DevTools Protocol (CDP) domains are initialized.

Key Improvements in v1.0.0-beta.9:

1. Lazy Initialization of CDP Executors: Previously, the CDPExecutor initialized all available domain executors (e.g., Network, Page, DOM) immediately upon instantiation. In v1.0.0-beta.9, we have implemented a lazy loading pattern. Domain executors are now only imported and initialized the first time they are accessed via their respective properties. This significantly reduces the initial memory footprint and speeds up the creation of new driver instances.
2. Removal of Pandas Dependency: To keep the library lightweight, we have completely removed the dependency on Pandas. All internal process tracking and network connection filtering—previously handled via DataFrames—now utilize native Python structures and a new, specialized ExecutablesTableRow model.
3. Migration to psutil for Process Management: With the removal of Pandas, we have refined our use of psutil. The logic for discovering existing browser sessions and managing executable tables has been rewritten to be more robust and performant, ensuring better cross-platform reliability for session recovery.
4. Major Package Restructuring: The monolithic _functions.py file has been decomposed into modular components:
   • _args_helpers.py: Logic for recursive wrapping/unwrapping of Selenium elements.
   • _bridges.py: Bridge functions for JS and CDP execution.
   • _executable_tables/: Dedicated module for process management logic.

Putting It All Together:
v1.0.0-beta.9 makes osn-selenium faster to start and easier to install by trimming unnecessary dependencies and optimizing internal executor logic. These changes provide a cleaner foundation for the upcoming modular API and enhanced concurrency features.

osn-selenium v1.0.0-beta.10

Requirements update