Metadata-Version: 2.4
Name: redblack-python-sdk
Version: 0.1.0
Summary: Typed Python SDK for the RedBlack trading and portfolio rebalancing API
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: httpx<1,>=0.27
Requires-Dist: pydantic<3,>=2.6
Requires-Dist: python-dotenv<2,>=1.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: PyYAML<7,>=6; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: pyright>=1.1; extra == "dev"
Requires-Dist: ruff>=0.3; extra == "dev"

# RedBlack Python SDK

Typed Python client for the RedBlack trading, portfolio-rebalancing, and
order-management API.

> **Alpha:** the SDK is implemented from the offline RedBlack `2026.3.0`
> contract. Live UAT validation has not yet been run. See
> [`docs/UAT_VALIDATION.md`](docs/UAT_VALIDATION.md).

## Requirements

- Python 3.11 or newer
- A RedBlack environment, API key, application client ID, and either:
  - a RedBlack API username, password, and client secret; or
  - an externally managed access token

## Install for development

```sh
python3 -m pip install -e '.[dev]'
```

## Quick start

```python
from redblack import Environment, PasswordCredentials, RedBlackClient

credentials = PasswordCredentials(
    client_secret="read-from-a-secret-store",
    username="read-from-a-secret-store",
    password="read-from-a-secret-store",
)

with RedBlackClient(
    environment=Environment.UAT,
    api_version="2026.3.0",
    api_key="read-from-a-secret-store",
    client_id="read-from-a-secret-store",
    credentials=credentials,
) as client:
    page = client.accounts.list(top=100, order_by="id asc")
    for account in page.items:
        print(account)
```

The normal constructor never reads environment variables or files. Applications
that intentionally want configuration lookup can use
`RedBlackClient.from_env()` or `RedBlackClient.from_dotenv()`.

## Safety defaults

- UAT or production must be selected explicitly.
- TLS verification is on and ambient proxy/CA variables are ignored by default.
- Access tokens are cached in memory and concurrent refresh is single-flight.
- Automatic retries apply to safe reads only.
- `POST`, `PATCH`, and `DELETE` are never replayed automatically.
- Task updates/deletes require the exact ETag returned by task retrieval.
- Deleting all cash actions requires a separate explicit confirmation.
- Export storage downloads never receive RedBlack credentials.
- Unknown response fields and enum values are preserved.

## API shape

Endpoints are grouped under:

```text
client.accounts
client.households
client.restrictions
client.equivalents
client.cash_actions
client.securities
client.orders
client.review_sets
client.users
client.tasks
```

Collection methods support RedBlack's OData options through Python arguments:
`filter`, `order_by`, `top`, `skip`, and `count`.

List Trade Blotter or Trade Reconciliation orders with the new Orders resource:

```python
from redblack.models import OrderFilterType

page = client.orders.list(top=100, count=True)  # Active Trade Blotter orders
for order in client.orders.iter_all(
    filter_type=OrderFilterType.IN_RECONCILIATION,
    order_by="id asc",
    max_items=1_000,
):
    print(order.id, order.quantity)
```

The SDK now defaults to `Accept-Version: 2026.3.0`; older API versions are not
supported by typed methods. Orders in review sets remain accessible through
`client.review_sets.list_pending_orders()`.

Friendly request and response types such as `Account`, `Task`, `TaskUpdate`,
and `CashActionCreate` are exported from `redblack.models`. Dictionary inputs
are also validated before an HTTP request is sent.

## Development commands

```sh
ruff format --check .
ruff check .
pyright
pytest
python3 tools/generate_sdk_models.py --check
python3 api-docs/tools/build_openapi_docs.py --check
python3 tools/check_operation_coverage.py
python3 -m build --no-isolation
```

The normal test suite uses mock transports and must not call RedBlack.

## Documentation

- [`docs/REDBLACK_PRIMER.md`](docs/REDBLACK_PRIMER.md) — start here if you are
  new to RedBlack, rebalancing, or trading workflows
- [`docs/USAGE.md`](docs/USAGE.md)
- [`docs/API_COVERAGE.md`](docs/API_COVERAGE.md)
- [`docs/COMPATIBILITY.md`](docs/COMPATIBILITY.md)
- [`docs/UAT_VALIDATION.md`](docs/UAT_VALIDATION.md)
