ApexSessionPool

Documentation for eth_defi.apex.session.ApexSessionPool Python class.

class ApexSessionPool

Bases: object

Worker-local HTTP sessions with shared bounded request policy.

Initialise the worker-local session registry and shared limiter.

Use create_apex_session_pool() for normal construction. Clock and sleeper injection keep deadline behaviour deterministic in tests.

Parameters

• api_url – Public ApeX API base URL.

• requests_per_second – Shared finite positive request rate.

• pool_maxsize – Per-worker connection pool size.

• timeout_policy – Request deadline and response-bound policy.

• retries – Retry count after the initial attempt.

• clock – Monotonic clock callable.

• sleeper – Delay callable.

• wall_clock – Unix timestamp clock used only for HTTP-date Retry-After.

Methods summary

__init__(*, api_url, requests_per_second, ...)	Initialise the worker-local session registry and shared limiter.
close()	Close every worker-local session created by this pool.
close_worker_sessions()	Close sessions created outside the calling thread.
fetch_json(path, *, params, ...)	Fetch and validate one bounded JSON response.
get_session()	Return the calling worker's private HTTP session.
history_worker_scope()	Track one active history worker through cleanup.
scan_scope()	Reserve this pool for one complete scan.

__init__(*, api_url, requests_per_second, pool_maxsize, timeout_policy, retries, clock=<built-in function monotonic>, sleeper=<built-in function sleep>, wall_clock=<built-in function time>)

Initialise the worker-local session registry and shared limiter.

Use create_apex_session_pool() for normal construction. Clock and sleeper injection keep deadline behaviour deterministic in tests.

Parameters

• api_url (str) – Public ApeX API base URL.

• requests_per_second (float) – Shared finite positive request rate.

• pool_maxsize (int) – Per-worker connection pool size.

• timeout_policy (eth_defi.apex.session.ApexTimeoutPolicy) – Request deadline and response-bound policy.

• retries (int) – Retry count after the initial attempt.

• clock (Callable[[], float]) – Monotonic clock callable.

• sleeper (Callable[[float], None]) – Delay callable.

• wall_clock (Callable[[], float]) – Unix timestamp clock used only for HTTP-date Retry-After.

Return type

None

get_session()

Return the calling worker’s private HTTP session.

Sessions are created once per live thread and registered for bounded cleanup by the owning scan or command.

Returns

Worker-local configured requests session.

Return type

requests.sessions.Session

close_worker_sessions()

Close sessions created outside the calling thread.

A new joblib thread pool is created for each scan cycle. Closing its worker-local sessions after the fetch phase prevents dead worker threads and their connection pools from accumulating during loop mode. The calling thread’s ranking session remains available for reuse.

Returns

None.

Return type

None

history_worker_scope()

Track one active history worker through cleanup.

Joblib may surface one worker exception before sibling threads have returned. The owning scan waits for all scopes to exit before closing any worker-local session.

Returns

Context manager yielding while one history worker is active.

Return type

collections.abc.Iterator[None]

scan_scope()

Reserve this pool for one complete scan.

A pool may serve many sequential loop cycles, but concurrent scans would make one caller unable to distinguish another caller’s sessions during worker cleanup. Fail fast instead of closing active sessions owned by a different scan.

Returns

Context manager yielding while this pool has exclusive scan ownership.

Return type

collections.abc.Iterator[None]

fetch_json(path, *, params, operation_deadline, validator)

Fetch and validate one bounded JSON response.

Retry sleeps, limiter queueing and timeout arguments consume the supplied operation budget. Endpoint-specific validation happens inside the retry loop so malformed HTTP-200 envelopes are retried consistently.

Parameters

• path (str) – API path relative to api_url.

• params (Optional[dict[str, str | int]]) – Query parameters.

• operation_deadline (float) – time.monotonic() budget boundary shared by the enclosing ranking or vault-history operation.

• validator (Callable[[object], eth_defi.apex.session.ParsedResponse]) – Endpoint parser returning the typed response.

Returns

Parsed endpoint response.

Raises

ApexAPIError – All bounded attempts failed.

Return type

eth_defi.apex.session.ParsedResponse

close()

Close every worker-local session created by this pool.

Closing an active scan would race with in-flight network work, so the operation fails fast until the scan scope has ended.

Returns

None.

Return type

None