pykalshi 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

pykalshi/rate_limiter.py

@@ -0,0 +1,171 @@
+"""
+Rate limiter for proactive request throttling.
+
+Composable, optional, and easy to remove. Inject into KalshiClient
+to prevent 429s rather than just retrying after them.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from collections import deque
+from dataclasses import dataclass, field
+from typing import Protocol
+
+
+class RateLimiterProtocol(Protocol):
+    """Protocol for rate limiters. Implement this to create custom limiters."""
+
+    def acquire(self, weight: int = 1) -> float:
+        """Acquire permission to make a request.
+
+        Args:
+            weight: Cost of this request (default 1).
+
+        Returns:
+            Time waited in seconds (0 if no wait).
+        """
+        ...
+
+    def update_from_headers(self, remaining: int | None, reset_at: int | None) -> None:
+        """Update internal state from response headers.
+
+        Args:
+            remaining: Requests remaining in current window.
+            reset_at: Unix timestamp when window resets.
+        """
+        ...
+
+
+@dataclass
+class RateLimiter:
+    """Token bucket rate limiter with sliding window.
+
+    Thread-safe. Proactively throttles requests to stay under limits.
+
+    Usage:
+        limiter = RateLimiter(requests_per_second=10)
+        client = KalshiClient(..., rate_limiter=limiter)
+
+        # Or manual usage:
+        limiter.acquire()  # Blocks if needed
+        response = make_request()
+        limiter.update_from_headers(
+            remaining=int(response.headers.get('X-RateLimit-Remaining')),
+            reset_at=int(response.headers.get('X-RateLimit-Reset')),
+        )
+
+    Attributes:
+        requests_per_second: Target request rate.
+        burst: Maximum burst size (default: 2x requests_per_second).
+        min_spacing_ms: Minimum ms between requests (anti-burst).
+    """
+
+    requests_per_second: float = 10.0
+    burst: int | None = None
+    min_spacing_ms: float = 0.0
+
+    _timestamps: deque = field(default_factory=deque, repr=False)
+    _lock: threading.Lock = field(default_factory=threading.Lock, repr=False)
+    _last_request: float = field(default=0.0, repr=False)
+
+    # Server-reported state (updated from headers)
+    _server_remaining: int | None = field(default=None, repr=False)
+    _server_reset_at: int | None = field(default=None, repr=False)
+
+    def __post_init__(self) -> None:
+        if self.burst is None:
+            self.burst = max(1, int(self.requests_per_second * 2))
+        self._window_size = 1.0  # 1 second sliding window
+
+    def acquire(self, weight: int = 1) -> float:
+        """Block until request is allowed. Returns wait time in seconds."""
+        with self._lock:
+            now = time.monotonic()
+            waited = 0.0
+
+            # Enforce minimum spacing
+            if self.min_spacing_ms > 0:
+                elapsed = (now - self._last_request) * 1000
+                if elapsed < self.min_spacing_ms:
+                    sleep_time = (self.min_spacing_ms - elapsed) / 1000
+                    time.sleep(sleep_time)
+                    waited += sleep_time
+                    now = time.monotonic()
+
+            # Clean old timestamps outside window
+            cutoff = now - self._window_size
+            while self._timestamps and self._timestamps[0] < cutoff:
+                self._timestamps.popleft()
+
+            # If at capacity, wait for oldest to expire
+            while len(self._timestamps) >= self.requests_per_second:
+                oldest = self._timestamps[0]
+                sleep_time = oldest + self._window_size - now
+                if sleep_time > 0:
+                    time.sleep(sleep_time)
+                    waited += sleep_time
+                    now = time.monotonic()
+                # Re-clean after sleep
+                cutoff = now - self._window_size
+                while self._timestamps and self._timestamps[0] < cutoff:
+                    self._timestamps.popleft()
+
+            # Check server-reported limits (be conservative)
+            if self._server_remaining is not None and self._server_remaining <= 1:
+                if self._server_reset_at is not None:
+                    sleep_until = self._server_reset_at - time.time()
+                    if sleep_until > 0:
+                        time.sleep(sleep_until)
+                        waited += sleep_until
+                        now = time.monotonic()
+                        self._server_remaining = None
+
+            # Record this request
+            for _ in range(weight):
+                self._timestamps.append(now)
+            self._last_request = now
+
+            return waited
+
+    def update_from_headers(
+        self, remaining: int | None, reset_at: int | None
+    ) -> None:
+        """Update state from X-RateLimit-Remaining and X-RateLimit-Reset headers."""
+        with self._lock:
+            if remaining is not None:
+                self._server_remaining = remaining
+            if reset_at is not None:
+                self._server_reset_at = reset_at
+
+    @property
+    def current_rate(self) -> float:
+        """Current request rate (requests in last second)."""
+        with self._lock:
+            now = time.monotonic()
+            cutoff = now - self._window_size
+            while self._timestamps and self._timestamps[0] < cutoff:
+                self._timestamps.popleft()
+            return len(self._timestamps)
+
+    def reset(self) -> None:
+        """Clear all state. Useful for testing."""
+        with self._lock:
+            self._timestamps.clear()
+            self._last_request = 0.0
+            self._server_remaining = None
+            self._server_reset_at = None
+
+
+@dataclass
+class NoOpRateLimiter:
+    """Rate limiter that does nothing. For testing or opt-out."""
+
+    def acquire(self, weight: int = 1) -> float:
+        return 0.0
+
+    def update_from_headers(
+        self, remaining: int | None, reset_at: int | None
+    ) -> None:
+        pass

{pykalshi-0.1.0.dist-info → pykalshi-0.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pykalshi
-Version: 0.1.0
+Version: 0.2.0
 Summary: A typed Python client for the Kalshi prediction markets API with WebSocket streaming, automatic retries, and ergonomic interfaces
 Author-email: Arsh Koneru <arshkon@gmail.com>
 License: MIT
@@ -42,14 +42,14 @@ Requires-Dist: mypy>=1.0.0; extra == "dev"
 Requires-Dist: types-requests>=2.31.0; extra == "dev"
 Dynamic: license-file
 
-# kalshi-api
+# pykalshi
 
 A typed Python client for the [Kalshi](https://kalshi.com) prediction markets API with WebSocket streaming, automatic retries, and ergonomic interfaces.
 
 ## Installation
 
 ```bash
-pip install kalshi-api
+pip install pykalshi
 ```
 
 Create a `.env` file with your credentials from [kalshi.com](https://kalshi.com) → Account & Security → API Keys:
@@ -62,7 +62,7 @@ KALSHI_PRIVATE_KEY_PATH=/path/to/private-key.key
 ## Quick Start
 
 ```python
-from kalshi_api import KalshiClient, Action, Side
+from pykalshi import KalshiClient, Action, Side
 
 client = KalshiClient()
 user = client.get_user()
@@ -118,7 +118,7 @@ trades = market.get_trades()
 ### Orders
 
 ```python
-from kalshi_api import Action, Side, OrderType
+from pykalshi import Action, Side, OrderType
 
 # Limit order (default)
 order = user.place_order(market, Action.BUY, Side.YES, count=10, price=50)
@@ -134,7 +134,7 @@ order.cancel()
 Subscribe to live market data via WebSocket:
 
 ```python
-from kalshi_api import Feed
+from pykalshi import Feed
 
 async def main():
     async with Feed(client) as feed:
@@ -148,7 +148,7 @@ async def main():
 ### Error Handling
 
 ```python
-from kalshi_api import InsufficientFundsError, RateLimitError, KalshiAPIError
+from pykalshi import InsufficientFundsError, RateLimitError, KalshiAPIError
 
 try:
     user.place_order(...)
@@ -162,7 +162,7 @@ except KalshiAPIError as e:
 
 ## Comparison with Official SDK
 
-| Feature | kalshi-api | kalshi-python (official) |
+| Feature | pykalshi | kalshi-python (official) |
 |---------|------------|--------------------------|
 | WebSocket streaming | ✓ | — |
 | Automatic retry with backoff | ✓ | — |

pykalshi-0.2.0.dist-info/RECORD

@@ -0,0 +1,35 @@
+kalshi_api/__init__.py,sha256=H873JDfBga0KEi-G-EJOPBljMZiOTOcpw7x2Qaeru9w,3018
+kalshi_api/api_keys.py,sha256=HMn5bzKo5yX8edcKpJy20NbrR2z7vUa5PJk8TB0iBwU,1922
+kalshi_api/client.py,sha256=4IA-f8OSMFYvxf8tmKL06-2gb7GdDISHDLUPdCtF9ac,19362
+kalshi_api/enums.py,sha256=9YF4ooA1RTprI08-NzqVZoPXISAmHDWgv3j0971BRyI,1127
+kalshi_api/events.py,sha256=0eC9xlqBblwxJdmdiFwjuiL1XUbw6eqcK-vCjoUUgqA,2683
+kalshi_api/exceptions.py,sha256=ikv97ztZwYWKr4SZ0EUTtR50KZQFjbpuI5vMMpPxiW4,3143
+kalshi_api/exchange.py,sha256=39-Zx-VZ6ezkOeB4E9fP4yhTX-qoO4FRSkpcEGmhG60,1359
+kalshi_api/feed.py,sha256=zhPGaER7oBMAHZgpxdppvWDkC-NLn6W_ORnLCkCQh_8,19470
+kalshi_api/markets.py,sha256=ben3yUqpW2Jn1bp67lJ7gyRjUHtwPTZkKQxyH_ao3ZA,6901
+kalshi_api/models.py,sha256=hQdkJMK4sFYXiDEjjEwsEY4skBXEzN3IuJFpzojF8Lw,16038
+kalshi_api/orderbook.py,sha256=40UIqEz-pgM49YdFNTXAd63Rw2hCaEq-sQPPy9l3q_E,4830
+kalshi_api/orders.py,sha256=F4mk0PPS_cBzDRbg0x50GpQb-AqfJPES2Vw45Zes3Rc,3726
+kalshi_api/portfolio.py,sha256=JgkgGTSEytn3OrIRbdci-bvkBOtRmxBK69uFuyYwArI,19937
+kalshi_api/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kalshi_api/rate_limiter.py,sha256=UJPjl-YUtLdVwQcaoq97ZH1oeS-IhqtV8K5G6WpUyDg,5901
+pykalshi/__init__.py,sha256=H873JDfBga0KEi-G-EJOPBljMZiOTOcpw7x2Qaeru9w,3018
+pykalshi/api_keys.py,sha256=HMn5bzKo5yX8edcKpJy20NbrR2z7vUa5PJk8TB0iBwU,1922
+pykalshi/client.py,sha256=4IA-f8OSMFYvxf8tmKL06-2gb7GdDISHDLUPdCtF9ac,19362
+pykalshi/enums.py,sha256=9YF4ooA1RTprI08-NzqVZoPXISAmHDWgv3j0971BRyI,1127
+pykalshi/events.py,sha256=0eC9xlqBblwxJdmdiFwjuiL1XUbw6eqcK-vCjoUUgqA,2683
+pykalshi/exceptions.py,sha256=ikv97ztZwYWKr4SZ0EUTtR50KZQFjbpuI5vMMpPxiW4,3143
+pykalshi/exchange.py,sha256=39-Zx-VZ6ezkOeB4E9fP4yhTX-qoO4FRSkpcEGmhG60,1359
+pykalshi/feed.py,sha256=zhPGaER7oBMAHZgpxdppvWDkC-NLn6W_ORnLCkCQh_8,19470
+pykalshi/markets.py,sha256=ben3yUqpW2Jn1bp67lJ7gyRjUHtwPTZkKQxyH_ao3ZA,6901
+pykalshi/models.py,sha256=hQdkJMK4sFYXiDEjjEwsEY4skBXEzN3IuJFpzojF8Lw,16038
+pykalshi/orderbook.py,sha256=40UIqEz-pgM49YdFNTXAd63Rw2hCaEq-sQPPy9l3q_E,4830
+pykalshi/orders.py,sha256=F4mk0PPS_cBzDRbg0x50GpQb-AqfJPES2Vw45Zes3Rc,3726
+pykalshi/portfolio.py,sha256=JgkgGTSEytn3OrIRbdci-bvkBOtRmxBK69uFuyYwArI,19937
+pykalshi/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pykalshi/rate_limiter.py,sha256=UJPjl-YUtLdVwQcaoq97ZH1oeS-IhqtV8K5G6WpUyDg,5901
+pykalshi-0.2.0.dist-info/licenses/LICENSE,sha256=dUhuoK-TCRQMpuLEAdfme-qPSJI0TlcH9jlNxeg9_EQ,1056
+pykalshi-0.2.0.dist-info/METADATA,sha256=SVfODyFs1tnfAldVPLhHLe9Jlcx8lxZahQjM4bwU3B0,5589
+pykalshi-0.2.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+pykalshi-0.2.0.dist-info/top_level.txt,sha256=d5Rnt2Wuf3HxyeG6hwGi8-g9G6_KLETpyJ5zExXO1M4,9
+pykalshi-0.2.0.dist-info/RECORD,,

pykalshi-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pykalshi

pykalshi-0.1.0.dist-info/RECORD

@@ -1,20 +0,0 @@
-kalshi_api/__init__.py,sha256=H873JDfBga0KEi-G-EJOPBljMZiOTOcpw7x2Qaeru9w,3018
-kalshi_api/api_keys.py,sha256=HMn5bzKo5yX8edcKpJy20NbrR2z7vUa5PJk8TB0iBwU,1922
-kalshi_api/client.py,sha256=4IA-f8OSMFYvxf8tmKL06-2gb7GdDISHDLUPdCtF9ac,19362
-kalshi_api/enums.py,sha256=9YF4ooA1RTprI08-NzqVZoPXISAmHDWgv3j0971BRyI,1127
-kalshi_api/events.py,sha256=0eC9xlqBblwxJdmdiFwjuiL1XUbw6eqcK-vCjoUUgqA,2683
-kalshi_api/exceptions.py,sha256=ikv97ztZwYWKr4SZ0EUTtR50KZQFjbpuI5vMMpPxiW4,3143
-kalshi_api/exchange.py,sha256=39-Zx-VZ6ezkOeB4E9fP4yhTX-qoO4FRSkpcEGmhG60,1359
-kalshi_api/feed.py,sha256=zhPGaER7oBMAHZgpxdppvWDkC-NLn6W_ORnLCkCQh_8,19470
-kalshi_api/markets.py,sha256=ben3yUqpW2Jn1bp67lJ7gyRjUHtwPTZkKQxyH_ao3ZA,6901
-kalshi_api/models.py,sha256=hQdkJMK4sFYXiDEjjEwsEY4skBXEzN3IuJFpzojF8Lw,16038
-kalshi_api/orderbook.py,sha256=40UIqEz-pgM49YdFNTXAd63Rw2hCaEq-sQPPy9l3q_E,4830
-kalshi_api/orders.py,sha256=F4mk0PPS_cBzDRbg0x50GpQb-AqfJPES2Vw45Zes3Rc,3726
-kalshi_api/portfolio.py,sha256=JgkgGTSEytn3OrIRbdci-bvkBOtRmxBK69uFuyYwArI,19937
-kalshi_api/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kalshi_api/rate_limiter.py,sha256=UJPjl-YUtLdVwQcaoq97ZH1oeS-IhqtV8K5G6WpUyDg,5901
-pykalshi-0.1.0.dist-info/licenses/LICENSE,sha256=dUhuoK-TCRQMpuLEAdfme-qPSJI0TlcH9jlNxeg9_EQ,1056
-pykalshi-0.1.0.dist-info/METADATA,sha256=qYNSSrd3cUElCZt-FuL0MoSifw7NdKoQlx6lpjcfYRo,5603
-pykalshi-0.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-pykalshi-0.1.0.dist-info/top_level.txt,sha256=j1cmqf7vUVoke4KfEg_he913wTsgN5nT0Ky5P3P7Dik,11
-pykalshi-0.1.0.dist-info/RECORD,,

pykalshi-0.1.0.dist-info/top_level.txt

@@ -1 +0,0 @@
-kalshi_api