neutral_trade.metrics
Documentation for eth_defi.neutral_trade.metrics Python module.
Resumable Neutral Trade directory, backfill and live collection.
All modes share one page reader and transactional, single-owner DuckDB writer. API contracts: https://api.neutral.trade/openapi.json.
Module Attributes
Bounds untrusted integer strings while accommodating EVM uint256 amounts. |
Functions
|
Fetch one page in an isolated worker session without database access. |
|
Discover leads, refresh current metadata and resume bounded history. |
Classes
Own one private source archive and exclusive source writer lock. |
|
Observe completed work separately from incomplete maintenance. |
- MAX_RAW_AMOUNT_DIGITS = 128
Bounds untrusted integer strings while accommodating EVM uint256 amounts.
- class NeutralTradeDatabase
Bases:
objectOwn one private source archive and exclusive source writer lock.
Unconstrained tables avoid DuckDB ART-index corruption. Raw observations and progress are committed together, preserving all unmatched history. Workers never access this connection.
- Parameters
path – Explicit private source archive, not a public dataset.
Acquire ownership before opening the file-backed database.
The entry-point must already hold lifecycle/pipeline locks where needed.
- Parameters
path – File-backed source database.
- __init__(path)
Acquire ownership before opening the file-backed database.
The entry-point must already hold lifecycle/pipeline locks where needed.
- Parameters
path (pathlib.Path) – File-backed source database.
- Return type
None
- save_lead(vault, metrics=None)
Upsert current metadata without deleting disappeared leads.
WSOL retains only a minimal exclusion audit, with no detailed data. A metadata refresh preserves previous metrics until replaced.
- Parameters
vault (eth_defi.neutral_trade.api.NeutralTradeVault) – Available directory entry.
metrics (Optional[dict]) – Successful metrics envelope, or no refresh.
- Returns
None.
- Return type
None
- prepare_history(vault, endpoint, *, start_date, end_date, refresh=False)
Resume incomplete work or open a bounded incremental date range.
Completed histories refresh daily with a seven-day correction overlap; new leads and explicit refresh/range requests are immediately due.
- Parameters
vault (eth_defi.neutral_trade.api.NeutralTradeVault) – Eligible source identity.
endpoint (str) – Canonical history endpoint.
start_date (Optional[datetime.date]) – Explicit inclusive start, or full initial history.
end_date (datetime.date) – Fixed inclusive end of this invocation’s range.
refresh (bool) – Start a deliberate full-range refresh.
- Returns
Whether a page is due.
- Return type
- history_request(vault, endpoint)
Read the current persisted page position.
The range stays fixed across resumptions; its cursor is opaque.
- Parameters
vault (eth_defi.neutral_trade.api.NeutralTradeVault) – Source identity.
endpoint (str) – Canonical endpoint.
- Returns
Cursor, start date and end date.
- Return type
tuple[str | None, datetime.date | None, datetime.date]
- save_page(vault, endpoint, page)
Atomically store one validated page and its continuation cursor.
Full source JSON preserves exact values and provenance. Corrections replace the same event key; shortened responses never delete history.
- Parameters
vault (eth_defi.neutral_trade.api.NeutralTradeVault) – Source identity.
endpoint (str) – Canonical endpoint.
page (dict) – Original validated response envelope.
- Returns
True when this range reached its terminal cursor.
- Return type
- record_error(vault, endpoint, error)
Keep failed work due without changing cursor/coverage.
Only sanitised client diagnostics should be supplied by callers.
- Parameters
vault (eth_defi.neutral_trade.api.NeutralTradeVault) – Source identity.
endpoint (str) – Failed canonical endpoint.
error (str) – Safe diagnostic text.
- Returns
None.
- Return type
None
- iter_leads()
Yield retained source metadata, including unavailable decisions.
This is a private archive API; public exporters apply admission checks.
- Returns
Lead dictionaries with raw configuration and metrics.
- Return type
- fetch_history_page(api_key, vault, endpoint, position)
Fetch one page in an isolated worker session without database access.
Workers return parsed values; the owner commits pages as results arrive.
- Parameters
api_key (str) – Partner credential, never logged.
vault (eth_defi.neutral_trade.api.NeutralTradeVault) – Eligible source identity.
endpoint (str) – Canonical endpoint.
position (tuple) – Cursor and fixed date bounds from persisted state.
- Returns
Identity, endpoint, page or sanitised error.
- Return type
tuple[eth_defi.neutral_trade.api.NeutralTradeVault, str, dict | None, str | None]
- run_scan(db, api_key, *, max_workers=2, page_budget=100, time_budget=300, vault_ids=None, start_date=None, end_date=None, refresh=False)
Discover leads, refresh current metadata and resume bounded history.
Manual/full and scheduled/incremental modes use this same routine. Daily histories use independent eligibility; current metrics refresh every run.
- Parameters
db (eth_defi.neutral_trade.metrics.NeutralTradeDatabase) – Owner-thread private database under its source lock.
api_key (str) – Partner credential.
max_workers (int) – Threaded page-reader concurrency.
page_budget (int) – Maximum committed/attempted pages this invocation.
time_budget (float) – Time before stopping new page dispatches.
vault_ids (Optional[set[str]]) – Optional exact source IDs; exclusions still apply.
start_date (Optional[datetime.date]) – Optional inclusive historical start.
end_date (Optional[datetime.date]) – Optional fixed end, default today in UTC.
refresh (bool) – Reopen completed histories for a full refresh.
- Returns
Counts distinguishing failures, pending work and completion.
- Return type