Metadata-Version: 2.4
Name: qubrics-core
Version: 2.0.0
Summary: Shared runtime helpers for the Qubrics Python SDK packages.
Project-URL: Repository, https://github.com/qubrics/qubrics-sdk
License-Expression: MIT
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: urllib3<3,>=2.3.0
Description-Content-Type: text/markdown

# qubrics-core

[![PyPI version](https://img.shields.io/pypi/v/qubrics-core)](https://pypi.org/project/qubrics-core/)
[![Python versions](https://img.shields.io/pypi/pyversions/qubrics-core)](https://pypi.org/project/qubrics-core/)
[![PyPI downloads](https://img.shields.io/pypi/dm/qubrics-core)](https://pypi.org/project/qubrics-core/)
[![Licence](https://img.shields.io/pypi/l/qubrics-core)](https://github.com/qubrics/qubrics-sdk/blob/main/LICENSE)

Shared runtime helpers for the Qubrics Python SDK packages.

## Documentation

- Qubrics docs: [qubrics.com/docs](https://qubrics.com/docs)
- Source repository: [qubrics/qubrics-sdk](https://github.com/qubrics/qubrics-sdk)

## Requirements

- Python 3.10 or newer.
- A surface package such as `qubrics-sending`, `qubrics-mailbox`, or `qubrics-management` for API operations.

## Installation

These commands target the Qubrics release of `qubrics-core`. Until it is published, install `sendmux-core` with its existing import names.

```sh
pip install qubrics-core
```

## Usage

Validate an API key prefix and prepare request headers before calling a surface package.

```python
import os

from qubrics.core import conditional_headers, idempotency_headers, validate_api_key

validate_api_key(os.environ["QUBRICS_MAILBOX_API_KEY"], surface="mailbox")

headers = {
    **idempotency_headers("idem_123"),
    **conditional_headers(if_none_match='W/"etag"'),
}
```

## Helpers

- `validate_api_key` checks `smx_root_*` prefixes for root clients, send-capable `smx_mbx_*` prefixes or owner-approved Sending-resource `smx_agent_*` tokens for Sending clients, and mailbox-compatible `smx_mbx_*` or `smx_agent_*` prefixes for Mailbox clients.
- `configure_auth` applies API-key bearer auth to generated client configuration objects. Surface factories also accept `access_token` as a bare token or callable; do not set both credential options.
- `idempotency_headers` and `conditional_headers` prepare request headers.
- `iter_cursor_pages` iterates cursor-paginated list responses.
- `RetryOptions` configures retry behaviour for generated clients. A single retry layer honours `retryable: false`, server retry delays and the total retry deadline.
- `QubricsApiError` normalises API errors and request IDs.

## Support

Open an issue in [qubrics/qubrics-sdk](https://github.com/qubrics/qubrics-sdk/issues) with the package name, version, and request ID from any API error.

## Licence

MIT. See the [licence file](https://github.com/qubrics/qubrics-sdk/blob/main/LICENSE).
