probalytics 0.2.0__tar.gz → 0.2.2__tar.gz

{probalytics-0.2.0 → probalytics-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: probalytics
-Version: 0.2.0
+Version: 0.2.2
 Summary: Python client for Probalytics market, fill, and orderbook data
 Project-URL: Homepage, https://github.com/Probalytics/probalytics-python
 Project-URL: Repository, https://github.com/Probalytics/probalytics-python
@@ -19,7 +19,9 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
+Requires-Dist: clickhouse-cityhash>=1.0.2.6
 Requires-Dist: clickhouse-driver>=0.2.10
+Requires-Dist: lz4>=4.4.5
 Requires-Dist: polars>=1
 Requires-Dist: pydantic>=2
 Provides-Extra: pandas
@@ -177,6 +179,10 @@ fills = client.fills(
 Use a market selector or a bounded time range when querying fills. This keeps
 queries fast and avoids scanning more data than you need.
 
+`start_time` / `end_time` filter `timestamp` (the exchange time) on `fills` and
+`orderbook_snapshots`, and `created_at` on `markets` — a market created months
+ago still returns today's fills.
+
 Filter by participant or taker side:
 
 ```python
@@ -222,9 +228,16 @@ Each snapshot is a complete replacement book for one outcome. Rows include
 `indexed_at`, `hash`, `state`, `continuity`, and `path_index` in addition to the
 market identifiers, outcome, bids, asks, and source timestamp.
 
-Use `state="VERIFIED"` when you only need books reconstructed without gaps. Use
-`continuity` separately to distinguish rows connected to the preceding
-published state from fresh starting points.
+`state` is `VERIFIED` or `INTERMEDIATE`. `continuity` is `CONTIGUOUS` (the
+transition from the previous book was provable), `RESET` (it was not — the first
+state of a book is deliberately `RESET`), or `UNKNOWN` for rows predating
+continuity tracking. Several distinct states can share one millisecond; `hash`
+separates them and `path_index` orders them within a recovered path.
+
+Note that these columns were added to the warehouse in August 2026. Rows written
+before then read the column default rather than a measured value: `hash` is 0
+before 2026-08-02, `state` reads `VERIFIED` before 2026-08-21, and `continuity`
+reads `UNKNOWN` before 2026-08-22.
 
 ## Choose Polars or pandas
 
@@ -260,6 +273,8 @@ Use `query()` for read-only ClickHouse queries when the convenience methods do
 not cover your use case.
 
 ```python
+from datetime import datetime, timezone
+
 df = client.query(
     """
     SELECT platform, count() AS fills
@@ -268,15 +283,24 @@ df = client.query(
     GROUP BY platform
     ORDER BY fills DESC
     """,
-    parameters={"start_time": "2026-03-15T00:00:00Z"},
+    parameters={"start_time": datetime(2026, 3, 15, tzinfo=timezone.utc)},
 )
 ```
 
 Always pass user-provided values through `parameters` instead of formatting them
 directly into SQL strings.
 
+Unlike the convenience methods, `query()` passes parameters straight to
+ClickHouse — it does not parse date strings for you. Pass a `datetime`, or a
+string ClickHouse accepts such as `"2026-03-15 00:00:00"`. An ISO string with a
+trailing `Z` is rejected by the server.
+
 ## Supported Filters
 
+The convenience methods return at most `limit` rows, and **`limit` defaults to 1000**.
+Raise it explicitly when you want more than that — results are truncated
+silently, not flagged.
+
 `markets()` and `markets_frame()` support:
 
 - `start_time`
@@ -303,8 +327,8 @@ directly into SQL strings.
 
 `orderbook_snapshots()` supports:
 
-- `start_time`
-- `end_time`
+- `start_time` (**required**)
+- `end_time` (**required**)
 - `platform` or list of platforms
 - `market`
 - `market_id` or list of market IDs

{probalytics-0.2.0 → probalytics-0.2.2}/README.md

@@ -145,6 +145,10 @@ fills = client.fills(
 Use a market selector or a bounded time range when querying fills. This keeps
 queries fast and avoids scanning more data than you need.
 
+`start_time` / `end_time` filter `timestamp` (the exchange time) on `fills` and
+`orderbook_snapshots`, and `created_at` on `markets` — a market created months
+ago still returns today's fills.
+
 Filter by participant or taker side:
 
 ```python
@@ -190,9 +194,16 @@ Each snapshot is a complete replacement book for one outcome. Rows include
 `indexed_at`, `hash`, `state`, `continuity`, and `path_index` in addition to the
 market identifiers, outcome, bids, asks, and source timestamp.
 
-Use `state="VERIFIED"` when you only need books reconstructed without gaps. Use
-`continuity` separately to distinguish rows connected to the preceding
-published state from fresh starting points.
+`state` is `VERIFIED` or `INTERMEDIATE`. `continuity` is `CONTIGUOUS` (the
+transition from the previous book was provable), `RESET` (it was not — the first
+state of a book is deliberately `RESET`), or `UNKNOWN` for rows predating
+continuity tracking. Several distinct states can share one millisecond; `hash`
+separates them and `path_index` orders them within a recovered path.
+
+Note that these columns were added to the warehouse in August 2026. Rows written
+before then read the column default rather than a measured value: `hash` is 0
+before 2026-08-02, `state` reads `VERIFIED` before 2026-08-21, and `continuity`
+reads `UNKNOWN` before 2026-08-22.
 
 ## Choose Polars or pandas
 
@@ -228,6 +239,8 @@ Use `query()` for read-only ClickHouse queries when the convenience methods do
 not cover your use case.
 
 ```python
+from datetime import datetime, timezone
+
 df = client.query(
     """
     SELECT platform, count() AS fills
@@ -236,15 +249,24 @@ df = client.query(
     GROUP BY platform
     ORDER BY fills DESC
     """,
-    parameters={"start_time": "2026-03-15T00:00:00Z"},
+    parameters={"start_time": datetime(2026, 3, 15, tzinfo=timezone.utc)},
 )
 ```
 
 Always pass user-provided values through `parameters` instead of formatting them
 directly into SQL strings.
 
+Unlike the convenience methods, `query()` passes parameters straight to
+ClickHouse — it does not parse date strings for you. Pass a `datetime`, or a
+string ClickHouse accepts such as `"2026-03-15 00:00:00"`. An ISO string with a
+trailing `Z` is rejected by the server.
+
 ## Supported Filters
 
+The convenience methods return at most `limit` rows, and **`limit` defaults to 1000**.
+Raise it explicitly when you want more than that — results are truncated
+silently, not flagged.
+
 `markets()` and `markets_frame()` support:
 
 - `start_time`
@@ -271,8 +293,8 @@ directly into SQL strings.
 
 `orderbook_snapshots()` supports:
 
-- `start_time`
-- `end_time`
+- `start_time` (**required**)
+- `end_time` (**required**)
 - `platform` or list of platforms
 - `market`
 - `market_id` or list of market IDs

{probalytics-0.2.0 → probalytics-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "probalytics"
-version = "0.2.0"
+version = "0.2.2"
 description = "Python client for Probalytics market, fill, and orderbook data"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -34,7 +34,9 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
+    "clickhouse-cityhash>=1.0.2.6",
     "clickhouse-driver>=0.2.10",
+    "lz4>=4.4.5",
     "polars>=1",
     "pydantic>=2",
 ]

{probalytics-0.2.0 → probalytics-0.2.2}/src/probalytics/models.py

@@ -49,6 +49,7 @@ class OrderbookState(StrEnum):
 
 
 class OrderbookContinuity(StrEnum):
+    UNKNOWN = "UNKNOWN"
     CONTIGUOUS = "CONTIGUOUS"
     RESET = "RESET"
 

{probalytics-0.2.0 → probalytics-0.2.2}/tests/test_clickhouse_integration.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import os
 import time
+from datetime import datetime, timezone
 
 import pandas as pd
 import polars as pl
@@ -58,7 +59,6 @@ def client(clickhouse_config) -> ProbalyticsClient:
         password=PASSWORD,
         database=DATABASE,
         secure=False,
-        compression=False,
         frame="pandas",
     )
 
@@ -82,6 +82,21 @@ def test_sample_data_matches_production_shapes(client: ProbalyticsClient) -> Non
     }
 
 
+@pytest.mark.parametrize(
+    "start_time",
+    [datetime(2026, 3, 15, tzinfo=timezone.utc), "2026-03-15 00:00:00"],
+)
+def test_query_accepts_documented_time_parameters(
+    client: ProbalyticsClient, start_time: datetime | str
+) -> None:
+    result = client.query(
+        "SELECT count() AS rows FROM fills WHERE timestamp >= %(start_time)s",
+        parameters={"start_time": start_time},
+    )
+
+    assert result["rows"].iloc[0] == len(FILL_ROWS)
+
+
 def test_markets_filters_accept_arrays_against_clickhouse(client: ProbalyticsClient) -> None:
     markets = client.markets(
         market_id=[MARKET_A, MARKET_B],

{probalytics-0.2.0 → probalytics-0.2.2}/tests/test_models.py

@@ -72,7 +72,8 @@ def test_public_enums_only_include_current_values() -> None:
         MarketType("UNKNOWN")
 
 
-def test_orderbook_snapshot_models_current_quality_fields() -> None:
+@pytest.mark.parametrize("continuity", ["RESET", "CONTIGUOUS", "UNKNOWN"])
+def test_orderbook_snapshot_models_current_quality_fields(continuity: str) -> None:
     snapshot = OrderbookSnapshot.model_validate(
         {
             "market_id": "550e8400-e29b-41d4-a716-446655440000",
@@ -90,13 +91,13 @@ def test_orderbook_snapshot_models_current_quality_fields() -> None:
             "indexed_at": "2026-03-15T00:00:00.001Z",
             "hash": 101,
             "state": "VERIFIED",
-            "continuity": "RESET",
+            "continuity": continuity,
             "path_index": 0,
         }
     )
 
     assert snapshot.state == "VERIFIED"
-    assert snapshot.continuity == "RESET"
+    assert snapshot.continuity == continuity
     assert snapshot.hash == 101
     assert snapshot.path_index == 0