apex.session

Documentation for eth_defi.apex.session Python module.

Bounded HTTP session pool for the ApeX public API.

Every worker receives a private requests.Session, while all workers share one budget-aware process limiter. Monotonic budgets clamp queueing, timeouts and retries, but the requests socket timeout remains inactivity-based.

Functions

create_apex_session_pool([...])

Create a bounded worker-local ApeX HTTP session pool.

Classes

ApexSessionPool	Worker-local HTTP sessions with shared bounded request policy.
ApexTimeoutPolicy	Finite timeout and response-bound configuration.

Exceptions

ApexAPIError	Base exception for an invalid or failed ApeX API operation.
ApexDeadlineExceededError	Raised when an HTTP operation detects exhausted monotonic budget.
ApexResponseTooLargeError	Raised when a JSON response exceeds its configured byte limit.

exception ApexAPIError

Bases: RuntimeError

Base exception for an invalid or failed ApeX API operation.

__init__(*args, **kwargs)

__new__(**kwargs)

add_note(note, /)

Add a note to the exception

with_traceback(tb, /)

Set self.__traceback__ to tb and return self.

exception ApexDeadlineExceededError

Bases: eth_defi.apex.session.ApexAPIError

Raised when an HTTP operation detects exhausted monotonic budget.

__init__(*args, **kwargs)

__new__(**kwargs)

add_note(note, /)

Add a note to the exception

with_traceback(tb, /)

Set self.__traceback__ to tb and return self.

exception ApexResponseTooLargeError

Bases: eth_defi.apex.session.ApexAPIError

Raised when a JSON response exceeds its configured byte limit.

__init__(*args, **kwargs)

__new__(**kwargs)

add_note(note, /)

Add a note to the exception

with_traceback(tb, /)

Set self.__traceback__ to tb and return self.

class ApexTimeoutPolicy

Bases: object

Finite timeout and response-bound configuration.

connect_timeout: float

TCP connection timeout in seconds.

read_timeout: float

Socket inactivity timeout in seconds.

request_deadline: float

Monotonic budget for one request attempt in seconds.

max_retry_delay: float

Longest retry delay in seconds.

max_response_bytes: int

Largest accepted JSON response.

__init__(connect_timeout=10.0, read_timeout=30.0, request_deadline=60.0, max_retry_delay=10.0, max_response_bytes=16777216)

Parameters

• connect_timeout (float) –

• read_timeout (float) –

• request_deadline (float) –

• max_retry_delay (float) –

• max_response_bytes (int) –

Return type

None

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.

__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

create_apex_session_pool(requests_per_second=5.0, pool_maxsize=8, timeout_policy=None, *, api_url='https://omni.apex.exchange/api/v3', retries=3)

Create a bounded worker-local ApeX HTTP session pool.

Parameters

• requests_per_second (float) – Shared maximum request rate.

• pool_maxsize (int) – Connection pool size for each worker-local session.

• timeout_policy (Optional[eth_defi.apex.session.ApexTimeoutPolicy]) – Finite network, deadline and response-size policy.

• api_url (str) – Public API base URL override, primarily for tests.

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

Returns

Configured session pool.

Return type

eth_defi.apex.session.ApexSessionPool