How rocky-d/wqb works
Project type and purpose
• This is a Python client library (a thin wrapper) for the WorldQuant BRAIN API.
• It provides a permanent, auto-refreshing HTTP session plus convenience methods for search, locate, filter, simulate, check, and submit endpoints.
• It is neither a full-stack web app nor a microservice; it is an SDK that integrates into user scripts or applications.
File structure
• Top-level:
• .github, CI/CD config (publish workflow)
• pyproject.toml, requirements-dev.txt (build & dev tooling)
• img (logo)
• Package root: wqb/
• auto_auth_session.py – extends requests.Session to handle automatic login & token refresh
• wqb_session.py – main class WQBSession, methods wrapping each API call (search, locate, simulate, etc.)
• wqb_urls.py – central URL constants for each REST endpoint
• datetime_range.py, filter_range.py – helpers to build query parameters (date & numeric filters)
• __init__.py – exposes public API, logger factory
Extract architectural insights from README
• Uses requests for synchronous calls; uses asyncio & coroutines for concurrent operations
• Logging is configurable – Console vs. File, log levels
• Permanent session with automatic authentication (“anti-expiration”)
• Exposes both limited (single-page) and streaming (generator/iterable) interfaces
Main components
• User Application (client script or notebook)
• wqb Python Library
a. Public API Layer (functions & classes exposed via __init__.py)
b. WQBSession – orchestrates all interactions
c. AutoAuthSession – subclass of requests.Session for token management
d. URL Module (wqb_urls) – REST endpoint definitions
e. Parameter Builders (FilterRange, DateTimeRange)
f. Logger Factory (wqb_logger)
• Third-Party Libraries
• requests (HTTP)
• asyncio (concurrent coroutines)
• logging (configurable log sinks)
• External Service
• WorldQuant BRAIN REST API
Relationships and data flow
1. User code calls wqb.wqb_logger() and/or instantiates WQBSession(credentials, logger).
2. WQBSession (via AutoAuthSession) authenticates to BRAIN API once and stores the token.
3. User code invokes session methods (search_*, locate_*, filter_*, simulate, check, submit).
4. For each call:
– WQBSession uses wqb_urls to build the endpoint URL
– Parameter builders serialize filters into query strings or JSON bodies
– requests.Session (AutoAuthSession) sends HTTP requests (sync) or aiohttp/async wrappers (async)
– Responses returned as requests.Response or Iterable[Response] to the user
5. Concurrent methods (concurrent_simulate, concurrent_check) spawn asyncio tasks, gather responses.
6. Logging hooks capture request/response metadata, optionally persisted to console/file.
Architectural patterns & design principles
• Adapter/Facade: WQBSession wraps the low-level REST API into a uniform Python interface.
• Extension: AutoAuthSession extends requests.Session to transparently handle token refresh.
• Separation of Concerns: URL definitions, parameter building, session management, logging are modularized.
• Asynchronous Concurrency: expose both sync (generator) and async (coroutines) interfaces.