redblack-python-sdk 0.1.0__tar.gz

redblack_python_sdk-0.1.0/.env.example

@@ -0,0 +1,13 @@
+# Select an environment explicitly: uat or production.
+REDBLACK_ENVIRONMENT=uat
+REDBLACK_API_VERSION=2026.3.0
+REDBLACK_API_KEY=replace-with-secret
+REDBLACK_CLIENT_ID=replace-with-secret
+
+# Choose exactly one authentication mode.
+REDBLACK_ACCESS_TOKEN=replace-with-access-token
+
+# Password-grant alternative:
+# REDBLACK_CLIENT_SECRET=replace-with-secret
+# REDBLACK_USERNAME=replace-with-api-user
+# REDBLACK_PASSWORD=replace-with-secret

redblack_python_sdk-0.1.0/AGENTS.md

@@ -0,0 +1,225 @@
+# Repository Guidance
+
+## Purpose
+
+This repository builds a Python SDK for the RedBlack API, a trading,
+portfolio-rebalancing, and order-management platform.
+
+This file applies to the entire repository unless a more specific
+`AGENTS.md` exists in a subdirectory.
+
+## Current Phase
+
+The offline SDK alpha for API release `2026.3.0` is implemented and has passed
+the repository's mocked contract, typing, generation, and package checks. Live
+UAT validation and public-release governance remain pending.
+
+Typed compatibility with `2026.2.0` is intentionally not retained, as directed
+by the repository owner. Its source and cleaned documentation remain archived.
+
+- SDK implementation was explicitly authorized by the repository owner.
+- Do not edit files in `api-docs/*/json_raw/`.
+- Keep derived documentation scoped to its API release.
+- Never silently combine facts from different API releases.
+- Do not claim live RedBlack behavior has been verified; UAT has not been run.
+
+## Repository Layout
+
+- `api-docs/<release>/json_raw/` contains immutable captured source
+  documentation.
+- `api-docs/<release>/cleaned/` contains normalized, agent-oriented
+  documentation derived from the raw sources.
+- `api-docs/RedBlack API.yaml` is the immutable supplied OpenAPI source for
+  release `2026.3.0`, including `GET /orders`. It uses standard paths and
+  component references. Do not edit this captured source.
+- `api-docs/2026.3.0/cleaned/` contains its normalized endpoint contract,
+  provenance and known issues. No narrative guides were supplied for this release.
+- `api-docs/tools/build_openapi_docs.py` rebuilds these docs with PyYAML from
+  the development dependencies.
+- `api-docs/2026.2.0/json_raw/openapi.json` is the archived endpoint source
+  for release `2026.2.0` only.
+- `api-docs/2026.2.0/json_raw/00_*.json` through `12_*.json` are the narrative
+  sources for setup, authentication, requests, responses, OData, rate
+  limiting, versioning, and exports.
+- `api-docs/tools/build_cleaned_docs.py` deterministically rebuilds a release's
+  cleaned documentation using only the Python standard library.
+- `src/redblack/` contains the synchronous SDK, generated models, transport,
+  authentication, resource groups, and workflow helpers.
+- `tools/generate_sdk_models.py` deterministically rebuilds the committed
+  model and operation layer from the cleaned contract.
+- `tests/` contains offline contract, unit, integration, static-typing, and
+  separately marked opt-in UAT smoke tests.
+- `docs/` contains the beginner RedBlack/rebalancing primer, SDK usage,
+  compatibility, operation-coverage, and UAT handoff documentation.
+
+## Documentation Authority
+
+Use the cleaned documentation as the primary working interface. Treat the raw
+files as the authoritative source and use them to verify provenance, resolve
+ambiguity, or audit the translation.
+
+For endpoint-specific work, start with `cleaned/reference/` and the targeted
+files under `cleaned/machine/operations/`. Use `cleaned/machine/openapi.json`
+for the complete normalized contract. For authentication, operational
+behavior, security guidance, versioning, rate limits, and workflows, start
+with `cleaned/guides/` and review `cleaned/KNOWN_ISSUES.md`.
+
+If sources disagree:
+
+1. Do not silently choose or invent behavior.
+2. Preserve the conflicting source facts.
+3. Record the discrepancy in the cleaned documentation as an unresolved issue
+   with references to both source locations.
+4. Do not encode uncertain behavior into future SDK code without a documented
+   decision.
+
+## Raw Format Notes
+
+The narrative files are ProseMirror-style document ASTs under `.body`, not
+plain Markdown. Preserve headings, lists, tables, links, callouts, code tabs,
+code blocks, images, and inline emphasis during translation.
+
+The archived `2026.2.0` API reference does not use a conventional generated OpenAPI
+layout:
+
+- Operations are under `.tags.<tag>.verbs[]`, not `.paths`.
+- Schemas are largely inline rather than in `.components.schemas`.
+- Reusable model identity is often represented by `x-ref-key`.
+- Enum member names may be stored in `x-enum-varnames`.
+- Nullable types may be arrays such as `["string", "null"]`.
+- Decimal values use `format: "decimal"`.
+
+Do not assume a standard OpenAPI generator can consume this file without a
+normalization step.
+
+## Cleaned Documentation Requirements
+
+Use UTF-8 Markdown with stable, predictable filenames and a top-level index.
+The cleaned set must let an agent find, without reparsing the raw JSON:
+
+- API version and environment URLs.
+- Authentication flow and required credentials.
+- Common headers, OData parameters, pagination, rate limits, errors, and
+  asynchronous job workflows.
+- Every tag and operation.
+- HTTP method, path, `operationId`, summary, and description.
+- Authentication and required headers.
+- Path, query, header, and body parameters, including required, default, and
+  example information.
+- Request and response media types.
+- Response status codes, headers, schemas, and examples.
+- Model fields, types, nullability, formats, constraints, enums, and
+  `x-ref-key` identities.
+- Source provenance and known source anomalies.
+
+Preserve exact wire names and casing, including `Accept-Version`, `Client-ID`,
+`X-Api-Key`, `Authorization`, `$top`, `$skip`, `$filter`, `$orderby`, and
+`$count`.
+
+Fix navigation links for the local cleaned-doc layout where possible. Record
+broken, stale, or ambiguous source links rather than discarding them.
+
+Never place real API keys, client secrets, usernames, passwords, or access
+tokens in documentation, fixtures, examples, logs, or commits.
+
+## Documentation Generation and Validation
+
+Rebuild or check the current `2026.3.0` documentation with:
+
+```sh
+python3 api-docs/tools/build_openapi_docs.py
+python3 api-docs/tools/build_openapi_docs.py --check
+```
+
+It must report 44 operations across 10 tags. Local references are expanded
+with component names retained as `x-ref-key` identities; original components
+and the YAML capture remain intact. Reference siblings and source anomalies
+are documented in the release's `cleaned/KNOWN_ISSUES.md`. Do not copy older
+narrative guides into this release or present them as newly verified behavior.
+
+Rebuild the cleaned `2026.2.0` documentation with:
+
+```sh
+python3 api-docs/tools/build_cleaned_docs.py 2026.2.0
+```
+
+The generator validates source and normalized counts, operation subtree
+fidelity, schema occurrence coverage, and generated relative Markdown links.
+It must report 13 guides and 43 operations.
+
+Additional JSON-level checks:
+
+```sh
+find api-docs/2026.2.0/json_raw -type f -name '*.json' \
+  -exec jq empty {} +
+jq -e '.info.version == "2026.2.0"' \
+  api-docs/2026.2.0/json_raw/openapi.json
+jq '[.tags[].verbs[]] | length' \
+  api-docs/2026.2.0/json_raw/openapi.json
+jq '[.paths[] | to_entries[] |
+  select(.key == "get" or .key == "post" or .key == "patch" or
+  .key == "delete")] | length' \
+  api-docs/2026.2.0/cleaned/machine/openapi.json
+```
+
+The final two commands must each report `43` for release `2026.2.0`.
+
+Before completing a documentation translation, verify that all 13 narrative
+documents and all 43 operations are represented. Check internal Markdown
+links and ensure no raw source file changed.
+
+## SDK Generation and Validation
+
+Install the package and development tools with:
+
+```sh
+python3 -m pip install -e '.[dev]'
+```
+
+Regenerate or check the committed wire layer with:
+
+```sh
+python3 tools/generate_sdk_models.py
+python3 tools/generate_sdk_models.py --check
+python3 tools/check_operation_coverage.py
+```
+
+Do not hand-edit `src/redblack/models/generated.py` or files under
+`src/redblack/_generated/`.
+
+Run the normal quality gates with:
+
+```sh
+ruff format --check .
+ruff check .
+pyright
+pytest
+python3 -m build --no-isolation
+```
+
+The normal suite blocks accidental socket connections and uses HTTPX mock
+transports. Tests marked `live` are a separate UAT activity and must remain
+skipped unless explicitly enabled with approved credentials. Never use
+production as a substitute for UAT.
+
+## SDK Conventions
+
+- Use a PEP 517/PEP 621 `pyproject.toml`.
+- Keep the `src/` package layout and mirror public modules under `tests/`.
+- Declare supported Python versions explicitly.
+- Type all public interfaces.
+- Preserve API wire names through explicit serialization aliases while using
+  idiomatic Python names publicly.
+- Keep transport, authentication, models, pagination, and endpoint resources
+  separable and testable.
+- Mock HTTP interactions in unit tests and cover success, error, pagination,
+  retry and rate-limit, and serialization behavior.
+- Do not make live RedBlack requests in the normal test suite.
+- Add exact install, format, lint, type-check, and test commands here only
+  after the corresponding tooling is configured.
+
+## Change Discipline
+
+Keep changes scoped to the requested release and task. Preserve unrelated
+files and user work. Derived documentation should be deterministic so later
+API releases can be normalized using the same structure and rules.

redblack_python_sdk-0.1.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to this project will be documented here.
+
+## 0.1.0 — Unreleased
+
+- Initial typed SDK implementation for the RedBlack `2026.2.0` contract.
+- Synchronous client, managed/static authentication, retries, pagination,
+  export workflows, review-set workflows, ETag concurrency, and all 43
+  documented operations.
+- Offline mocked validation; live UAT validation remains pending.

redblack_python_sdk-0.1.0/MANIFEST.in

@@ -0,0 +1,10 @@
+include .env.example
+include AGENTS.md
+include CHANGELOG.md
+recursive-include api-docs/2026.2.0/cleaned *.json *.md
+recursive-include api-docs/2026.2.0/json_raw *.json
+recursive-include api-docs/tools *.py
+recursive-include docs *.md
+recursive-include examples *.py
+recursive-include tests *.py
+recursive-include tools *.py

redblack_python_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+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)

redblack_python_sdk-0.1.0/README.md

@@ -0,0 +1,126 @@
+# 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)