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.