ddp_utils.browser.facade.human

import ddp_utils.browser.facade.human

Optional human-paced actions built only from the neutral browser facade.

class ddp_utils.browser.facade.human.BrowserHuman(browser: Browser, profile: HumanProfile | None = None)

Bases: object

Provide simple human-paced actions without changing backend semantics.

Parameters

Name	Type	Description
browser	Browser	Owning browser facade.
profile	HumanProfile | None	Optional timing profile.

Note

This layer improves interaction pacing; it does not claim to defeat bot detection or replace the browser identity contract.

Examples

Type and submit through backend-neutral elements:

browser.human.type(field, "John Smith", clear=True)
browser.human.click(submit)

Bind a validated timing profile to one browser.

Parameters

Name	Type	Description
browser	Browser	Owning browser facade.
profile	HumanProfile | None	Optional profile; defaults are used when omitted.

Examples

Browser creates a default service once:

human = BrowserHuman(browser)

property profile: HumanProfile

Return the immutable active profile.

Returns

Current human timing profile.

Examples

Inspect configured mouse interpolation:

print(browser.human.profile.mouse_steps)

pause(minimum: float | None = None, maximum: float | None = None) → float

Sleep for a bounded pseudo-random action interval.

Parameters

Name	Type	Description
minimum	float | None	Optional lower bound.
maximum	float | None	Optional upper bound.

Returns

Type	Description
float	Actual delay in seconds.

Raises

Exception	Description
BrowserConfigurationError	Bounds are negative or reversed.

Examples

Pause at a business-safe point:

browser.human.pause(0.2, 0.5)

type(element: BrowserElement, value: Any, *, clear: bool = False, required: bool = True) → ActionResult['BrowserElement']

Focus and type with independently varied per-character delays.

Parameters

Name	Type	Description
element	BrowserElement	Editable facade element.
value	Any	Value converted to text.
clear	bool	Clear the current value first.
required	bool	Raise when the element action fails.

Returns

Type	Description
ActionResult[’BrowserElement’]	Verified element action result.

Examples

Replace a name naturally:

browser.human.type(field, "Smith", clear=True)

click(element: BrowserElement, *, required: bool = True) → ActionResult['BrowserElement']

Hover, pause, and click one element.

Parameters

Name	Type	Description
element	BrowserElement	Clickable facade element.
required	bool	Raise when the element action fails.

Returns

Type	Description
ActionResult[’BrowserElement’]	Click action result.

Examples

Click a submit button with visible pacing:

browser.human.click(submit)

check(element: BrowserElement, checked: bool = True, *, required: bool = True) → ActionResult['BrowserElement']

Set checkbox or radio state with human pacing.

Parameters

Name	Type	Description
element	BrowserElement	Checkbox or radio facade element.
checked	bool	Desired selected state.
required	bool	Raise when the state cannot be set.

Returns

Type	Description
ActionResult[’BrowserElement’]	Verified selection action result.

Examples

Select a consent checkbox:

browser.human.check(consent)

select(element: BrowserElement, *, value: str | None = None, label: str | None = None, index: int | None = None, required: bool = True) → ActionResult['BrowserElement']

Select a native option after a bounded pause.

Parameters

Name	Type	Description
element	BrowserElement	Native select facade element.
value	str | None	Option value.
label	str | None	Visible label.
index	int | None	Zero-based index.
required	bool	Raise when selection fails.

Returns

Type	Description
ActionResult[’BrowserElement’]	Verified select action result.

Examples

Choose a court by label:

browser.human.select(court, label="Fulton")

scroll(delta_y: int, *, delta_x: int = 0, steps: int | None = None) → None

Scroll in interpolated wheel steps.

Parameters

Name	Type	Description
delta_y	int	Total vertical delta.
delta_x	int	Total horizontal delta.
steps	int | None	Optional step count.

Raises

Exception	Description
BrowserConfigurationError	If the number of scroll steps is less than 1.

Examples

Scroll down gradually:

browser.human.scroll(900)

move(x: float, y: float, *, steps: int | None = None) → None

Move the pointer through interpolated backend-native steps.

Parameters

Name	Type	Description
x	float	Target viewport x-coordinate.
y	float	Target viewport y-coordinate.
steps	int | None	Optional step count.

Examples

Move toward a menu:

browser.human.move(320, 180)

choose(values: Sequence[Any]) → Any

Choose one value through the profile’s reproducible random source.

Parameters

Name	Type	Description
values	Sequence[Any]	Non-empty sequence.

Returns

Type	Description
Any	Selected value.

Raises

Exception	Description
BrowserConfigurationError	Sequence is empty.

Examples

Pick one equivalent UI path:

selector = browser.human.choose(["button", "a.submit"])

class ddp_utils.browser.facade.human.HumanProfile(min_key_delay: float = 0.035, max_key_delay: float = 0.11, min_action_delay: float = 0.05, max_action_delay: float = 0.24, mouse_steps: int = 12, scroll_steps: int = 8, seed: int | None = None)

Bases: object

Configure bounded timing variation for human-paced actions.

Parameters

Name	Type	Description
min_key_delay	float	Minimum delay between typed characters in seconds.
max_key_delay	float	Maximum delay between typed characters in seconds.
min_action_delay	float	Minimum pause around actions in seconds.
max_action_delay	float	Maximum pause around actions in seconds.
mouse_steps	int	Default interpolated mouse movement steps.
scroll_steps	int	Default scroll animation steps.
seed	int | None	Optional deterministic random seed for reproducible tests.

Examples

Use deterministic timing in an integration test:

profile = HumanProfile(seed=59, min_key_delay=0.02)

validate() → None

Validate timing and interpolation bounds.

Raises

Exception	Description
BrowserConfigurationError	A bound is negative, reversed, or zero.

Examples

Validate a project-provided profile:

HumanProfile().validate()