Quick start

Each example uses the current public API. Backend-specific dependencies are required only for the browser example.

Files and paths

FileManager creates missing parent directories for write operations and delegates path inspection to PathInfo.

from ddp_utils.file_manager import FileManager
from ddp_utils.path_info import PathInfo

state = FileManager("runtime/state.txt")
state.overwrite("ready")

path = PathInfo("runtime/state.txt")
print(state.read())
print(path.exists, path.resolved)

Console workflows

One coordinated console owns nested groups and live components. The terminal backend automatically degrades to stable plain output when cursor control is unavailable.

from ddp_utils.console import get_console

console = get_console()

with console.group("Import", on_finish="remove") as group:
    with group.create_spinner("Loading input"):
        records = ["A", "B", "C"]

    with group.create_progress(
        len(records),
        "Rows",
        auto_complete=False,
        on_finish="remove",
    ) as progress:
        for _record in records:
            progress.advance()

Timing work

The timer helpers use a monotonic duration source and return a formatted result from timer_stop.

from ddp_utils.timeutils import timer_start, timer_stop

started = timer_start()
total = sum(range(1000))
message = timer_stop(started, prefix="Elapsed")
print(total)
print(message)

Browser automation

Business code uses the same synchronous facade across supported automation technologies. Always close the facade through its context manager.

from ddp_utils.browser import BrowserConfig, BrowserFactory

config = BrowserConfig.from_mapping(
    {
        "technology": "playwright",
        "browser": "chrome",
        "headless": True,
    }
)

with BrowserFactory().open(config) as browser:
    browser.open(
        "data:text/html,%3Cmain%3E%3Ch1%3EReady%3C/h1%3E%3C/main%3E"
    )
    heading = browser.css("h1", timeout=3, required=True)
    print(heading.text)

Provider-specific objects remain available through explicit native escape hatches. Check browser.capability(...) before relying on a feature that is not common to every backend.