pykalshi-client 1.0.1__tar.gz

pykalshi_client-1.0.1/.env_demo

@@ -0,0 +1,20 @@
+# --- System Control ---
+KALSHI_ENVIRONMENT=DEMO
+
+# --- API Credentials ---
+KALSHI_DEMO_API_KEY_ID=<INSERT_PUB_API_KEY>
+KALSHI_DEMO_PRIVATE_KEY_FILE=<INSERT_PRIV_API_KEY_FILE_PATH>
+
+# For PROD environment (uncomment when ready):
+KALSHI_PROD_API_KEY_ID=<INSERT_PUB_API_KEY>
+KALSHI_PROD_PRIVATE_KEY_FILE=<INSERT_PRIV_API_KEY_FILE_PATH>
+
+# --- Rate Limit Fallbacks ---
+# Initial limits used before /account/limits resolves, and fallbacks on fetch failure.
+# Defaults below match Kalshi's standard tier (20 read/sec, 10 write/sec).
+# Successful /account/limits calls override these with the user's actual tier.
+KALSHI_RATE_LIMIT_GLOBAL=20.0
+KALSHI_RATE_LIMIT_WRITE=10.0
+
+# --- Dev / Debug ---
+# KALARB_LOG_LEVEL=DEBUG

pykalshi_client-1.0.1/.github/workflows/asyncapi-validation.yml

@@ -0,0 +1,37 @@
+name: AsyncAPI Validation
+
+on:
+  push:
+    branches: [main]
+  schedule:
+    - cron: "0 14 * * *"
+  workflow_dispatch:
+
+jobs:
+  asyncapi-validation:
+    runs-on: ubuntu-latest
+    timeout-minutes: 3
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: false
+
+      - name: Install dependencies
+        run: uv sync --extra testing
+
+      - name: Validate WS channels against AsyncAPI spec
+        id: validate
+        continue-on-error: true
+        run: uv run pytest tests/test_asyncapi_validation.py -v -s
+
+      - name: Update badge
+        uses: Schneegans/dynamic-badges-action@v1.7.0
+        with:
+          auth: ${{ secrets.GIST_SECRET }}
+          gistID: 65579a629076066fcbf09520ca76301a
+          filename: asyncapi-status.json
+          label: AsyncAPI
+          message: ${{ steps.validate.outcome == 'success' && 'Up-to-date' || 'Behind' }}
+          color: ${{ steps.validate.outcome == 'success' && 'green' || 'yellow' }}

pykalshi_client-1.0.1/.github/workflows/ci.yml

@@ -0,0 +1,220 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  schedule:
+    - cron: "0 14 * * *"
+  workflow_dispatch:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: false
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Ruff check
+        run: uv run ruff check src/ tests/
+
+  rest-unit-tests:
+    runs-on: ubuntu-latest
+    timeout-minutes: 3
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: false
+
+      - name: Install dependencies
+        run: uv sync --extra testing
+
+      - name: Run REST unit tests
+        run: uv run pytest tests/test_auth.py tests/test_rate_limiter.py tests/test_http_client.py tests/test_config.py tests/test_exceptions.py tests/test_models.py tests/test_observability.py -v --cov=pykalshi --cov-report=term-missing
+
+  ws-unit-tests:
+    runs-on: ubuntu-latest
+    timeout-minutes: 3
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: false
+
+      - name: Install dependencies
+        run: uv sync --extra testing
+
+      - name: Run WS unit tests
+        run: uv run pytest tests/test_ws_client.py -v
+
+  exchange-gate:
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
+    outputs:
+      active: ${{ steps.gate.outputs.active }}
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: false
+
+      - name: Install dependencies
+        run: uv sync --extra testing
+
+      - name: Write credentials
+        run: |
+          echo "$KALSHI_DEMO_PRIVATE_KEY_PEM" > /tmp/demo-key.pem
+          chmod 600 /tmp/demo-key.pem
+        env:
+          KALSHI_DEMO_PRIVATE_KEY_PEM: ${{ secrets.KALSHI_DEMO_PRIVATE_KEY_PEM }}
+
+      - name: Check exchange status
+        id: gate
+        run: |
+          uv run python -c "
+          import httpx, os, time, base64
+          from cryptography.hazmat.primitives import hashes, serialization
+          from cryptography.hazmat.primitives.asymmetric import padding
+
+          key_id = os.environ['KALSHI_DEMO_API_KEY_ID']
+          with open('/tmp/demo-key.pem', 'rb') as f:
+              key = serialization.load_pem_private_key(f.read(), password=None)
+          ts = str(int(time.time() * 1000))
+          path = '/trade-api/v2/exchange/status'
+          msg = (ts + 'GET' + path).encode()
+          sig = base64.b64encode(key.sign(msg, padding.PSS(mgf=padding.MGF1(hashes.SHA256()), salt_length=padding.PSS.DIGEST_LENGTH), hashes.SHA256())).decode()
+          headers = {'KALSHI-ACCESS-KEY': key_id, 'KALSHI-ACCESS-SIGNATURE': sig, 'KALSHI-ACCESS-TIMESTAMP': ts}
+          resp = httpx.get('https://demo-api.kalshi.co' + path, headers=headers)
+          data = resp.json()
+          active = data.get('exchange_active') or data.get('trading_active', False)
+          if not active:
+              print('::notice::Exchange is in maintenance - skipping')
+              print('active=false')
+          else:
+              print('Exchange is active')
+              print('active=true')
+          " | tee /tmp/gate-output.txt
+          if grep -q "active=true" /tmp/gate-output.txt; then
+            echo "active=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "active=false" >> "$GITHUB_OUTPUT"
+          fi
+        env:
+          KALSHI_DEMO_API_KEY_ID: ${{ secrets.KALSHI_DEMO_API_KEY_ID }}
+
+  rest-integration:
+    needs: [exchange-gate, rest-unit-tests]
+    if: needs.exchange-gate.outputs.active == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: false
+
+      - name: Install dependencies
+        run: uv sync --extra testing
+
+      - name: Write credentials
+        run: |
+          echo "$KALSHI_DEMO_PRIVATE_KEY_PEM" > /tmp/demo-key.pem
+          chmod 600 /tmp/demo-key.pem
+          cat > .env << EOF
+          KALSHI_DEMO_API_KEY_ID=$KALSHI_DEMO_API_KEY_ID
+          KALSHI_DEMO_PRIVATE_KEY_FILE=/tmp/demo-key.pem
+          EOF
+        env:
+          KALSHI_DEMO_API_KEY_ID: ${{ secrets.KALSHI_DEMO_API_KEY_ID }}
+          KALSHI_DEMO_PRIVATE_KEY_PEM: ${{ secrets.KALSHI_DEMO_PRIVATE_KEY_PEM }}
+
+      - name: Run REST integration tests
+        run: uv run pytest tests/test_integration.py -v
+
+  ws-integration:
+    if: github.event_name != 'pull_request'
+    needs: [ws-unit-tests]
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: false
+
+      - name: Install dependencies
+        run: uv sync --extra testing
+
+      - name: Write credentials
+        run: |
+          echo "$KALSHI_PROD_READ_ONLY_PRIVATE_KEY_PEM" > /tmp/prod-ro-key.pem
+          chmod 600 /tmp/prod-ro-key.pem
+          cat > .env << EOF
+          KALSHI_PROD_READ_ONLY_API_KEY_ID=$KALSHI_PROD_READ_ONLY_API_KEY_ID
+          KALSHI_PROD_READ_ONLY_PRIVATE_KEY_FILE=/tmp/prod-ro-key.pem
+          EOF
+        env:
+          KALSHI_PROD_READ_ONLY_API_KEY_ID: ${{ secrets.KALSHI_PROD_READ_ONLY_API_KEY_ID }}
+          KALSHI_PROD_READ_ONLY_PRIVATE_KEY_PEM: ${{ secrets.KALSHI_PROD_READ_ONLY_PRIVATE_KEY_PEM }}
+
+      - name: Run WebSocket integration tests
+        run: uv run pytest tests/test_ws_integration.py -v
+
+  coverage-report:
+    if: github.ref == 'refs/heads/main'
+    needs: [rest-unit-tests, ws-unit-tests]
+    runs-on: ubuntu-latest
+    timeout-minutes: 3
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/create-github-app-token@v2
+        id: app-token
+        with:
+          app-id: ${{ secrets.APP_ID }}
+          private-key: ${{ secrets.APP_PRIVATE_KEY }}
+
+      - uses: actions/checkout@v5
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: false
+
+      - name: Install dependencies
+        run: uv sync --extra testing
+
+      - name: Run unit tests with JSON report
+        run: |
+          uv run pytest tests/ \
+            --ignore=tests/test_integration.py \
+            --ignore=tests/test_ws_integration.py \
+            --ignore=tests/test_openapi_validation.py \
+            --ignore=tests/test_asyncapi_validation.py \
+            --json-report --json-report-file=test-results.json -q
+
+      - name: Generate coverage report
+        run: uv run python tools/generate_coverage_report.py
+
+      - name: Commit and push
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add docs/API_COVERAGE.md
+          git diff --cached --quiet || git commit -m "docs: update API coverage report"
+          git push

pykalshi_client-1.0.1/.github/workflows/openapi-validation.yml

@@ -0,0 +1,37 @@
+name: OpenAPI Validation
+
+on:
+  push:
+    branches: [main]
+  schedule:
+    - cron: "0 14 * * *"
+  workflow_dispatch:
+
+jobs:
+  openapi-validation:
+    runs-on: ubuntu-latest
+    timeout-minutes: 3
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: false
+
+      - name: Install dependencies
+        run: uv sync --extra testing
+
+      - name: Validate REST API against OpenAPI spec
+        id: validate
+        continue-on-error: true
+        run: uv run pytest tests/test_openapi_validation.py -v -s
+
+      - name: Update badge
+        uses: Schneegans/dynamic-badges-action@v1.7.0
+        with:
+          auth: ${{ secrets.GIST_SECRET }}
+          gistID: 65579a629076066fcbf09520ca76301a
+          filename: openapi-status.json
+          label: OpenAPI
+          message: ${{ steps.validate.outcome == 'success' && 'Up-to-date' || 'Behind' }}
+          color: ${{ steps.validate.outcome == 'success' && 'green' || 'yellow' }}

pykalshi_client-1.0.1/.github/workflows/pr-title-lint.yml

@@ -0,0 +1,31 @@
+name: PR Title Lint
+
+on:
+  pull_request_target:
+    types: [opened, edited, synchronize]
+
+permissions:
+  pull-requests: read
+
+jobs:
+  pr-title-lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 1
+    steps:
+      - uses: amannn/action-semantic-pull-request@v5
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          types: |
+            feat
+            fix
+            refactor
+            perf
+            docs
+            ci
+            test
+            chore
+            style
+          requireScope: false
+          subjectPattern: ^.+$
+          subjectPatternError: "PR title must have a description after the type prefix."

pykalshi_client-1.0.1/.github/workflows/publish.yml

@@ -0,0 +1,19 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

pykalshi_client-1.0.1/.github/workflows/version-bump.yml

@@ -0,0 +1,145 @@
+name: Version Bump & Release
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+
+concurrency:
+  group: version-bump
+  cancel-in-progress: false
+
+jobs:
+  version-bump:
+    runs-on: ubuntu-latest
+    timeout-minutes: 3
+    outputs:
+      new_version: ${{ steps.bump.outputs.new_version }}
+      bumped: ${{ steps.bump.outputs.bumped }}
+    steps:
+      - name: Generate app token
+        id: app-token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ secrets.APP_ID }}
+          private-key: ${{ secrets.APP_PRIVATE_KEY }}
+
+      - uses: actions/checkout@v5
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+
+      - name: Determine bump type and compute new version
+        id: bump
+        env:
+          COMMIT_MSG: ${{ github.event.head_commit.message }}
+        run: |
+          msg="$COMMIT_MSG"
+
+          # Extract conventional commit type from first line (strip leading whitespace)
+          type=$(echo "$msg" | head -1 | sed -n 's/^[[:space:]]*\([a-z]*\).*/\1/p')
+
+          # Skip version bump for non-functional changes
+          case "$type" in
+            docs|ci|test|chore|style)
+              echo "bumped=false" >> "$GITHUB_OUTPUT"
+              echo "Skipping version bump for commit type: $type"
+              exit 0
+              ;;
+            feat|fix|refactor|perf)
+              ;; # continue to bump
+            *)
+              echo "bumped=false" >> "$GITHUB_OUTPUT"
+              echo "Skipping version bump for unrecognized type: $type"
+              exit 0
+              ;;
+          esac
+
+          # Determine bump level
+          if echo "$msg" | grep -qP 'BREAKING CHANGE:' || echo "$msg" | head -1 | grep -qP '^\s*[a-z]+(\(.*\))?!:'; then
+            bump="major"
+          elif [ "$type" = "feat" ]; then
+            bump="minor"
+          else
+            bump="patch"
+          fi
+
+          # Read current version
+          current=$(grep -oP '(?<=__version__ = ")[^"]+' src/pykalshi/_version.py)
+          IFS='.' read -r major minor patch <<< "$current"
+
+          # Compute new version
+          case "$bump" in
+            major) new="$((major+1)).0.0" ;;
+            minor) new="${major}.$((minor+1)).0" ;;
+            patch) new="${major}.${minor}.$((patch+1))" ;;
+          esac
+
+          echo "new_version=${new}" >> "$GITHUB_OUTPUT"
+          echo "bumped=true" >> "$GITHUB_OUTPUT"
+          echo "Bumping $current -> $new ($bump from $type)"
+
+      - name: Update version file
+        if: steps.bump.outputs.bumped == 'true'
+        run: |
+          echo "__version__ = \"${{ steps.bump.outputs.new_version }}\"" > src/pykalshi/_version.py
+
+      - name: Commit and push version bump
+        if: steps.bump.outputs.bumped == 'true'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add src/pykalshi/_version.py
+          git commit -m "chore: bump version to ${{ steps.bump.outputs.new_version }}"
+          git pull --rebase
+          git push
+
+  release:
+    needs: version-bump
+    if: needs.version-bump.outputs.bumped == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 3
+    permissions:
+      contents: write
+    steps:
+      - name: Generate app token
+        id: app-token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ secrets.APP_ID }}
+          private-key: ${{ secrets.APP_PRIVATE_KEY }}
+
+      - uses: actions/checkout@v5
+        with:
+          ref: main
+          token: ${{ steps.app-token.outputs.token }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Build package
+        run: uv build
+
+      - name: Create and push tag
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          tag="v${{ needs.version-bump.outputs.new_version }}"
+          if git rev-parse "$tag" >/dev/null 2>&1; then
+            echo "Tag $tag already exists, skipping"
+            exit 1
+          fi
+          git tag "$tag"
+          git push origin "$tag"
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: v${{ needs.version-bump.outputs.new_version }}
+          name: v${{ needs.version-bump.outputs.new_version }}
+          generate_release_notes: true
+          files: dist/*

pykalshi_client-1.0.1/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+*.egg
+.eggs/
+*.whl
+dist/
+build/
+.coverage
+.pytest_cache/
+test-results.json
+.mypy_cache/
+.ruff_cache/
+.env
+uv.lock

pykalshi_client-1.0.1/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.5.0 — Initial Open-Source Release
+
+- Async HTTP client (KalshiHttpClient) — 50+ endpoints across 23 API domains
+- Async WebSocket client (KalshiWebSocketClient) — 11+ subscription channels
+- 144 typed Pydantic v2 models (auto-generated from OpenAPI/AsyncAPI specs)
+- RSA-PSS authentication
+- Read/write rate limiting with token bucket
+- Exponential backoff retry for 429s and network errors
+- Optional OpenTelemetry instrumentation
+- Protocol-based typed contracts for testing
+- Mock transport factory + pytest fixtures

pykalshi_client-1.0.1/CONTRIBUTING.md

@@ -0,0 +1,78 @@
+# Contributing
+
+Contributions are welcome! Whether it's a bug report, feature request, or pull request, we appreciate your help making this library better.
+
+## Opening Issues
+
+Please open an issue before starting work on large changes. This lets us discuss the approach and avoid duplicate effort.
+
+## Branch Workflow
+
+- All changes go through a pull request against `main` — no direct pushes
+- PRs are **squash merged** (repo enforced), so the PR title becomes the commit message
+- Required checks must pass before merging: `lint`, `rest-unit-tests`, `ws-unit-tests`
+
+## PR Title Format
+
+PR titles **must** follow [Conventional Commits](https://www.conventionalcommits.org/) format:
+
+```
+type(optional-scope): description
+```
+
+The PR title drives automatic version bumping on merge:
+
+| Type | Version Bump | Example |
+|---|---|---|
+| `feat` | **minor** (0.1.x → 0.2.0) | `feat: add batch order amendment` |
+| `fix` | **patch** (0.1.1 → 0.1.2) | `fix: handle nullable fields in responses` |
+| `refactor` | **patch** | `refactor: extract rate limiter into separate module` |
+| `perf` | **patch** | `perf: use orjson for message parsing` |
+| `docs` | no bump | `docs: update API coverage tables` |
+| `ci` | no bump | `ci: add OpenAPI validation workflow` |
+| `test` | no bump | `test: add resubscribe_channel integration test` |
+| `chore` | no bump | `chore: update dependencies` |
+| `style` | no bump | `style: fix ruff formatting` |
+
+## Breaking Changes
+
+Breaking changes trigger a **major** version bump. Signal them in one of two ways:
+
+1. Add `!` after the type in the PR title:
+   ```
+   feat!: remove deprecated get_live_data_legacy
+   ```
+
+2. Include `BREAKING CHANGE:` in the PR description body:
+   ```
+   BREAKING CHANGE: get_live_data_legacy has been removed. Use get_live_data instead.
+   ```
+
+## Running Tests Locally
+
+```bash
+# Unit tests
+uv run pytest tests/test_http_client.py tests/test_auth.py tests/test_rate_limiter.py -v
+uv run pytest tests/test_ws_client.py -v
+
+# Lint
+uv run ruff check src/ tests/
+
+# Integration tests (requires credentials in .env)
+uv run pytest tests/test_integration.py -v        # REST — DEMO API
+uv run pytest tests/test_ws_integration.py -v      # WebSocket — PROD API (read-only)
+
+# Spec validation
+uv run pytest tests/test_openapi_validation.py -v
+uv run pytest tests/test_asyncapi_validation.py -v
+```
+
+## Code Generation
+
+Models in `src/pykalshi/models/` are **auto-generated** from the Kalshi OpenAPI and AsyncAPI specs. Do not edit them manually. Instead:
+
+```bash
+uv run python tools/generate_models.py       # HTTP models
+uv run python tools/generate_ws_models.py    # WebSocket models
+uv run python tools/sync_docstrings.py       # API function docstrings
+```