Metadata-Version: 2.5
Name: vexity
Version: 0.1.0
Summary: Official Python client for the Vexity options-analytics API: ETag-aware reads, incremental windows and the live socket.
Author-email: Vexity <vexity@jzn-management.com>
License: MIT License
        
        Copyright (c) 2026 Vexity
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
        The MIT licence covers the code of this package only. Use of the Vexity API and
        of the data it returns is governed by the Vexity Terms and Conditions
        (https://vexity.net/terms) and the Redistribution Policy (https://vexity.net/redistribution).
License-File: LICENSE
Keywords: api-client,gamma-exposure,options,vexity
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: msgpack>=1.0
Requires-Dist: websockets>=13
Requires-Dist: zstandard>=0.23; python_version < '3.14'
Description-Content-Type: text/markdown

# vexity

Official Python client for the [Vexity](https://vexity.net) options-analytics API.

```python
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-Match` and 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, and `Vexity(store=EtagStore(directory=...))` keeps it across runs.
- `Window` reads a live window once in full (following `next_cursor`), then asks `from=<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 neither `from` nor `to` is a single frame, not a window. A tail is about 1 % of a full re-read; when `resolution_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 than `max_wait_s` raises `RateLimited` instead of hanging.
- Raises typed errors (`AuthError`, `PlanError`, `Forbidden`, `NotFound`, `RateLimited`, `BadRequest`, `ServerError`, `TransportError`), each carrying the server's `reason`, `detail` and `request_id`.
- Live sockets use zstd framing, take `every_ms` as the server's rung, answer a `gap` by waiting for the next snapshot, and redial on the generated backoff; a `Reconnected` event 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](https://vexity.net/terms) and the [Redistribution Policy](https://vexity.net/redistribution), 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.
