vexity
Official Python client for the Vexity options-analytics API.
import vexity
client = vexity.Vexity() # reads VEXITY_API_KEY
levels = client.levels("SPX", scope="full") # the JSON body, as a dict
window = client.window("series", "SPX", names="spot,net_gex_oi", scope="latest", step="1m", span="2h")
update = window.poll() # the first call reads the window; later calls read only the tail and merge it
with client.live() as live: # zstd socket, redials by the server's own client policy
live.subscribe("levels", "SPX", scope="full", every_ms=5000)
for event in live:
print(event)
What it does for you, with no flags:
- Sends
If-None-Matchand stores answers. A 304 saves the body, not the request, and happens only on reads that move slowly (contracts, surface, series envelopes, a window between chain cycles): live levels, frame and grid bodies change every second, so poll them rarely or use the socket. A closed window (immutable) is served from the store with no request, andVexity(store=EtagStore(directory=...))keeps it across runs. Windowreads a live window once in full (followingnext_cursor), then asksfrom=<the step boundary at or before the newest held timestamp>(the newest timestamp itself on an aligned series, so the first returned bucket is a whole one) and merges by the documented rule: drop the held points at or after the answer's first timestamp, append the answer. A step of a session day is read in full each poll. A frame read with neitherfromnortois a single frame, not a window. A tail is about 1 % of a full re-read; whenresolution_ms,projection_id,compute_version, the view or the lanes change, the window is read again in full.- Waits
Retry-After(seconds or HTTP date) and paces itself when the key's budget reaches zero; a wait longer thanmax_wait_sraisesRateLimitedinstead of hanging. - Raises typed errors (
AuthError,PlanError,Forbidden,NotFound,RateLimited,BadRequest,ServerError,TransportError), each carrying the server'sreason,detailandrequest_id. - Live sockets use zstd framing, take
every_msas the server's rung, answer agapby waiting for the next snapshot, and redial on the generated backoff; aReconnectedevent says to read REST once for the span it was down.
Instant reads and sockets ride compact protobuf by default, at compact layout 2 (compact=plugin&compact_layout=2&layout_id=<id>; on sockets the compact.layout.2 feature), the layout that carries every member, the freshness pairs (book_stale, basis_stale, ...) included. A decoded body equals its JSON twin; a member the JSON omits because it does not apply reads None. Windows (Window) follow the same default. Vexity(compact=False), or compact=False on one call, reads JSON instead.
What the pin does and does not promise: layout 2 is the newest layout this release of vexity was generated from (the pin moves with the release, not with the server). The server checks the layout id this release sends and answers 409 when a required member changed, and the SDK checks the layout the server served (the ETag's -cpb2) and the layout a socket negotiated; each failure raises LayoutMismatch and tells you to upgrade vexity or pass compact=False. Layout 2 can still grow in place with optional members: a member this release does not know is skipped with an UnknownMembersWarning naming it, so upgrade when you see one, or read JSON. The warning is raised once per member and process. A server release that adds a member keeps the previous layout id accepted (the register job refuses a release that drops it), so an older SDK keeps working and only warns.
The live socket takes the key in its URL, as the API requires, so keep the websockets logger above DEBUG. The key is read from VEXITY_API_KEY or api_key=; it is masked in repr and never logged.
User-Agent
Requests and the socket send vexity-py/<version>. Pass Vexity(app="myapp/1.2") to append your own name (vexity-py/0.1.0 myapp/1.2) so Vexity can reach heavy users.
Licence and use of the data
The code of this package is MIT licensed. Use of the Vexity API and of the data it returns is governed by the Vexity Terms and Conditions and the Redistribution Policy, not by the MIT licence. In particular the data may be cached transiently, not accumulated into datasets of your own. EtagStore(directory=...) is an opt-in revalidation cache: it keeps closed answers only until their max-age lapses so a re-run does not fetch them again, and it is not an archive. Entries are deleted when their max-age lapses, so a read after that downloads the body again instead of revalidating. Questions: vexity@jzn-management.com.
Metadata
Release files for vexity 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| vexity-0.1.0.tar.gz | 36.4 kB | Without provenance | Details for vexity-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| vexity-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for vexity-0.1.0-py3-none-any.whl |
Total release size: 80.0 kB
Release files / vexity-0.1.0.tar.gz
| Download URL | vexity-0.1.0.tar.gz |
|---|---|
| Size | 36.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
86052adfa27b4cd2e02341b7f9575f29de873dd7f56056bb5aa7ed3588a0290a
|
|
BLAKE2b-256 checksum How to use checksums |
b7bcaf3342a34213ed1a0e8dcf51106c92e9d703688115e7a2456d2ab5d17ded
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.0
|
Release files / vexity-0.1.0-py3-none-any.whl
| Download URL | vexity-0.1.0-py3-none-any.whl |
|---|---|
| Size | 43.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c77607a4c661b400547f07e3da8d2ae4639645401ff5cd952199e24d09b2aee7
|
|
BLAKE2b-256 checksum How to use checksums |
bbce90688d3d991c4fb847586c778201133ed474ed833fab4a13e9d222a1e37e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.0
|
Security for vexity 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.