Utility Functions

Helper functions for working with nodriver

Overview

nodriver provides utility functions in the nodriver.core.util module and exports commonly used ones at the top level. These functions help with event loops, browser management, DOM traversal, and more.

Event Loop Functions

loop()

Create a new asyncio event loop.

def loop() -> asyncio.AbstractEventLoop

See the loop() API reference for details.

Example:

import nodriver as uc

async def main():
    browser = await uc.start()
    # Your code here
    browser.stop()

uc.loop().run_until_complete(main())

Browser Management

start()

Launch a browser instance.

async def start(
    config: Optional[Config] = None,
    *,
    user_data_dir: Optional[PathLike] = None,
    headless: Optional[bool] = False,
    browser_executable_path: Optional[PathLike] = None,
    browser_args: Optional[List[str]] = None,
    sandbox: Optional[bool] = True,
    lang: Optional[str] = None,
    host: Optional[str] = None,
    port: Optional[int] = None,
    expert: Optional[bool] = None,
    **kwargs: Optional[dict],
) -> Browser

See the start() API reference for details.

get_registered_instances()

Get all active browser instances.

def get_registered_instances() -> Set[Browser]

Returns: Set of all Browser instances that have been started.

Example:

import nodriver as uc
from nodriver.core import util

browser1 = await uc.start()
browser2 = await uc.start()

instances = util.get_registered_instances()
print(f"Active browsers: {len(instances)}")

for browser in instances:
    browser.stop()

deconstruct_browser()

Clean up browser instances and temporary profiles.

def deconstruct_browser(browser: Browser = None)

browser · Browser · default: "None"

Specific browser to clean up. If None, cleans up all registered instances.

Example:

import nodriver as uc
from nodriver.core import util

browser = await uc.start()
# Do work...

# Clean up specific browser
util.deconstruct_browser(browser)

# Or clean up all browsers
util.deconstruct_browser()

free_port()

Find an available port for browser debugging.

def free_port() -> int

Returns: Available port number.

Example:

from nodriver.core import util

port = util.free_port()
print(f"Using port: {port}")

browser = await uc.start(port=port)

DOM Traversal

filter_recurse()

Find the first element matching a predicate by recursively traversing the DOM tree.

def filter_recurse(
    doc: Union[cdp.dom.Node, Element], 
    predicate: Callable[[cdp.dom.Node, Element], bool]
) -> Union[cdp.dom.Node, Element]

doc · cdp.dom.Node | Element · required

Root node to start traversal from.

predicate · Callable · required

Function that takes a node and returns True to select it.

Returns: First node matching the predicate, or None.

Example:

from nodriver.core import util
from nodriver import cdp

# Get document tree
doc = await tab.send(cdp.dom.get_document(-1, True))

# Find first button element
button = util.filter_recurse(
    doc,
    lambda node: node.node_name == 'BUTTON'
)

filter_recurse_all()

Find all elements matching a predicate by recursively traversing the DOM tree.

def filter_recurse_all(
    doc: Union[cdp.dom.Node, Element], 
    predicate: Callable[[cdp.dom.Node, Element], bool]
) -> List[Union[cdp.dom.Node, Element]]

doc · cdp.dom.Node | Element · required

Root node to start traversal from.

predicate · Callable · required

Function that takes a node and returns True to include it.

Returns: List of all nodes matching the predicate.

Example:

from nodriver.core import util

# Find all link elements
links = util.filter_recurse_all(
    doc,
    lambda node: node.node_name == 'A'
)

print(f"Found {len(links)} links")

Frame Tree Functions

flatten_frame_tree()

Flatten a hierarchical frame tree into a flat list of frames.

def flatten_frame_tree(
    tree: Union[cdp.page.FrameResourceTree, cdp.page.FrameTree]
) -> Generator[cdp.page.Frame, None, None]

tree · cdp.page.FrameResourceTree | cdp.page.FrameTree · required

Frame tree to flatten.

Yields: Frame objects from the tree.

Example:

from nodriver.core import util
from nodriver import cdp

# Get frame tree
frame_tree = await tab.send(cdp.page.get_frame_tree())

# Flatten to list of frames
frames = list(util.flatten_frame_tree(frame_tree))

for frame in frames:
    print(f"Frame: {frame.url}")

flatten_frame_tree_resources()

Flatten frame tree and yield frame-resource pairs.

def flatten_frame_tree_resources(
    tree: cdp.page.FrameResourceTree
) -> Generator[Tuple[cdp.page.Frame, cdp.page.FrameResource], None, None]

Yields: Tuples of (frame, resource) for each resource in the tree.

Geometry Functions

circle()

Generate coordinates around a circle for smooth circular motion.

def circle(
    x: float, 
    y: float = None, 
    radius: int = 10, 
    num: int = 10, 
    dir: int = 0
) -> Generator[Tuple[float, float], None, None]

x · float · required

Center X coordinate.

y · float · default: "None"

Center Y coordinate. If None, uses x value.

radius · int · default: "10"

Circle radius in pixels.

num · int · default: "10"

Number of points to generate (higher = smoother but slower).

dir · int · default: "0"

Direction: 0 for clockwise, 1 for counter-clockwise.

Yields: (x, y) coordinate tuples around the circle.

Example:

import nodriver as uc
from nodriver.core import util

async def main():
    browser = await uc.start()
    tab = await browser.get('https://example.com')
    
    # Move window in a circle
    window_id, bounds = await tab.get_window()
    center_x, center_y = bounds.left, bounds.top
    
    for x, y in util.circle(center_x, center_y, radius=100, num=50):
        await tab.set_window_size(int(x), int(y))
    
    browser.stop()

uc.loop().run_until_complete(main())

CDP Helper Functions

cdp_get_module()

Get a CDP module by domain name.

def cdp_get_module(domain: Union[str, types.ModuleType]) -> types.ModuleType

domain · str | ModuleType · required

Domain name (e.g., ‘page’, ‘network’) or module object.

Returns: CDP domain module.

Example:

from nodriver.core import util

# Get page domain
page_module = util.cdp_get_module('page')

# Use it
command = page_module.navigate(url='https://example.com')

Comparison Functions

compare_target_info()

Compare two TargetInfo objects and return differences.

def compare_target_info(
    info1: cdp.target.TargetInfo, 
    info2: cdp.target.TargetInfo
) -> List[Tuple[str, Any, Any]]

Returns: List of tuples (field_name, old_value, new_value) for changed fields.

Example:

from nodriver.core import util

changes = util.compare_target_info(old_target, new_target)
for field, old_val, new_val in changes:
    print(f"{field}: {old_val} -> {new_val}")

Advanced Functions

create_from_undetected_chromedriver()

Create a nodriver Browser from an undetected_chromedriver instance.

async def create_from_undetected_chromedriver(
    driver: "undetected_chromedriver.Chrome"
) -> Browser

driver · undetected_chromedriver.Chrome · required

Running undetected_chromedriver instance.

Returns: nodriver Browser instance connected to the same browser.

Example:

import undetected_chromedriver as uc_driver
from nodriver.core import util

# Create undetected_chromedriver instance
driver = uc_driver.Chrome()

# Convert to nodriver
browser = await util.create_from_undetected_chromedriver(driver)

# Now use nodriver API
tab = browser.main_tab
await tab.get('https://example.com')

html_from_tree()

Extract HTML from a DOM tree.

async def html_from_tree(
    tree: Union[cdp.dom.Node, Element], 
    target: Tab
) -> str

tree · cdp.dom.Node | Element · required

DOM tree or element.

target · Tab · required

Tab instance for sending CDP commands.

Returns: HTML string.

remove_from_tree()

Remove a node from a DOM tree.

def remove_from_tree(
    tree: cdp.dom.Node, 
    node: cdp.dom.Node
) -> cdp.dom.Node

Returns: Modified tree with node removed.

Examples

Clean up all browsers on exit

import nodriver as uc
from nodriver.core import util
import atexit

# Register cleanup
atexit.register(util.deconstruct_browser)

async def main():
    browser = await uc.start()
    tab = await browser.get('https://example.com')
    # Cleanup happens automatically on exit

uc.loop().run_until_complete(main())

Find elements with custom logic

import nodriver as uc
from nodriver.core import util
from nodriver import cdp

async def main():
    browser = await uc.start()
    tab = await browser.get('https://example.com')
    
    # Get document
    doc = await tab.send(cdp.dom.get_document(-1, True))
    
    # Find all elements with specific attribute
    elements = util.filter_recurse_all(
        doc,
        lambda node: (
            hasattr(node, 'attributes') and 
            node.attributes and
            'data-test' in node.attributes
        )
    )
    
    print(f"Found {len(elements)} test elements")
    browser.stop()

uc.loop().run_until_complete(main())

Circular window animation

import nodriver as uc
from nodriver.core import util

async def animate_window(tab, center_x, center_y):
    """Move window in circular pattern"""
    for x, y in util.circle(
        center_x, 
        center_y, 
        radius=150, 
        num=100,
        dir=0
    ):
        await tab.set_window_size(int(x), int(y))

async def main():
    browser = await uc.start()
    tab = await browser.get('https://example.com')
    
    # Get starting position
    window_id, bounds = await tab.get_window()
    
    # Animate
    await animate_window(tab, bounds.left, bounds.top)
    
    browser.stop()

uc.loop().run_until_complete(main())

See also

• start() - Launch a browser
• Browser class - Browser instance management
• Element class - DOM element interaction