> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rangler.co/llms.txt
> Use this file to discover all available pages before exploring further.

# SDKs

> Rangler SDKs give your team one way to work with webhooks, event reads, and portal-managed resources.

Rangler SDKs cover webhook verification, event parsing, API reads, and portal management.

## Install Python

Use uv.

```bash theme={null}
uv add ranglerpy
```

Use pip.

```bash theme={null}
pip install ranglerpy
```

## Publish Python

`uv add ranglerpy` works after the `ranglerpy` distribution exists on PyPI.

Reserve the package name on PyPI before the first release. Use a PyPI API token for manual releases, or trusted publishing from GitHub Actions once release automation is ready.

Run this from the package repo.

```bash theme={null}
python scripts/update_version.py 0.1.1
python -m unittest discover -s tests -v
uv build --no-sources
UV_PUBLISH_TOKEN=pypi-your-project-token uv publish
```

For a dry run, publish to TestPyPI first.

```bash theme={null}
UV_PUBLISH_TOKEN=pypi-your-test-token uv publish \
  --publish-url https://test.pypi.org/legacy/ \
  --check-url https://test.pypi.org/simple/ranglerpy/
```

Verify install from a clean project.

```bash theme={null}
uv init rangler-install-check
cd rangler-install-check
uv add ranglerpy
uv run python -c "import ranglerpy; print(ranglerpy.__version__)"
```

## Current SDK

`ranglerpy` is first because Python is the shortest path for fintech backends, internal automation, research workflows, and compliance tooling.

It ships with these pieces.

* sync and async API clients
* `client.v1.*` resources for the current public API
* list responses with `data`
* dynamic response objects with dict and attribute access
* webhook signature verification
* webhook duplicate-delivery helpers
* event feed helpers for loading earlier events and checking missed deliveries
* portal API helpers for organizations, API keys, subscriptions, usage, and webhook endpoints

## Auth Model

Rangler has two auth modes.

* customer API resources use `api_key`
* portal management resources use `bearer_token`

Pass both credentials when one process uses both surfaces.

```python theme={null}
from ranglerpy import RanglerClient

client = RanglerClient(
    api_key="rgl_test_your_key_here",
    bearer_token="your_portal_bearer_token",
    environment="sandbox",
)
```

An API key alone is not enough for helpers that manage portal resources.

## Webhooks

Use `Webhook.construct_event` as the recommended receiver entry point.

```python theme={null}
from ranglerpy import Webhook

event = Webhook.construct_event(
    headers=headers,
    raw_body=raw_body,
    secret=webhook_secret,
)

print(event.id)
print(event.type)
print(event.display.title)
print(event.data.object.id)
```

`Webhook.construct_event` verifies the signature and timestamp and parses the event. It does not durably accept the event for your application. In production, insert `event.id` and the payload into a shared, database-backed inbox before returning `2xx`. The optional `InMemoryIdempotencyStore` is only for local examples and single-process tests.

Rangler webhook events use a consistent format with a resource inside `data.object`.

```json theme={null}
{
  "id": "evt_...",
  "object": "event",
  "api_version": "v1",
  "type": "filing.new",
  "display": {
    "title": "MAY & BAKER NIGERIA PLC published an AGM notice"
  },
  "data": {
    "object": {
      "id": "filing_...",
      "object": "filing"
    }
  }
}
```

`display` is for humans. `data.object` is for code. If an enriched signal is attached, read it from `event.data.signal`.

## Read earlier events

Use `client.v1.events` to load earlier events or check for missed deliveries across the market, an issuer, or a fund.

```python theme={null}
from ranglerpy import RanglerClient

client = RanglerClient(api_key="rgl_test_your_key_here", environment="sandbox")

for event in client.v1.events.auto_paging_iter(
    event_types=["filing.new", "dividend.declared"],
    limit=100,
):
    print(event.id, event.type, event.company_id)
```

## Metadata

Rangler does not currently expose customer writable metadata on public API resources.

When metadata is added, use it only for customer controlled key value data that helps your own system reconcile Rangler resources.

Do not use future metadata for secrets, credentials, access decisions, or values that should be visible in the Rangler product.

Example use cases.

* store your internal company identifier on a watchlist entry
* store your internal workflow identifier on a webhook subscription
* store a reference ID that lets your job connect Rangler events to your own records

See [Metadata](/metadata).

## Integration Choice

Use the SDK when you want webhook verification, typed event parsing, and API helpers.

Use direct HTTP when you need total control or want to inspect the API quickly.

Start with webhooks for product workflows. Use event reads for earlier records, missed-delivery checks, and initial data loading.

See [Webhooks and Event Feeds](/polling-vs-webhooks) and [Quickstart](/quickstart).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.