britecore_sdk

Last updated: July 27, 2026 Document type: Living guide

A production-ready Python SDK for the BriteCore Insurance API.

Spec-aligned v2 wrappers, OAuth2/API key auth, lazy client initialization, normalized response handling, and PEP 561 type hints.

Status: Stable (v2.1.1+) | License: Apache-2.0 | Python: 3.11+

Quick Start

1. Install

Windows (PowerShell):

pip install britecore_sdk

Linux/macOS (bash):

pip install britecore_sdk

2. Configure

Set target_site and credentials via config files or environment variables. The SDK discovers config files automatically from several locations. For the canonical precedence table, see CONFIG_MANAGEMENT.md.

Note: Hostnames under example.com in this repository are placeholders. Replace with your real BriteCore API host values.

Recommended for most users: user-level config (~/.britecore/)

Works across all your projects without touching SDK package files:

# ~/.britecore/settings.toml
[default]
target_site = "production"

# ~/.britecore/.secrets.toml
[production]
base_url = "https://api.britecore.example.com"
api_key = "your_api_key_here"

For full API key/OAuth examples, project-local files, and env-var-only setup, use CONFIG_MANAGEMENT.md and GETTING_STARTED.md.

3. Use

from britecore_sdk.api.api_calls import get_api_client
from britecore_sdk.api.api_calls.v2 import policies

# Recommended: Use the lazy-initialized client (auto-loads config on first use)
client = get_api_client()

# Retrieve a policy
result = policies.retrieve_policy(policy_number="POL001")
print(result)

See examples/basic_api_usage.py for more detailed examples.

About API Client Initialization

The api_client proxy (from api.api_calls) initializes lazily on first use, avoiding import-time failures if config is missing. Use get_api_client() for explicit control over the shared lazy client. Use init_api_client() for advanced/manual initialization scenarios (for example explicit credentials or multi-site binding).

If you need to verify selected auth mode during initialization, enable SDK debug logging before client init. The client emits Auth mode selected during init_client: api_key or Auth mode selected during init_client: oauth at debug level.

Pattern A (app-owned logging, preferred for host apps):

import logging

logging.basicConfig(level=logging.INFO)
logging.getLogger("britecore_sdk").setLevel(logging.DEBUG)

Pattern B (SDK-managed handler, opt-in):

import logging
from britecore_sdk import configure_logging

configure_logging(level="INFO")
logging.getLogger("britecore_sdk").setLevel(logging.DEBUG)

You can also log directly through the package logger:

from britecore_sdk import logger

logger.info("SDK logger is configured")

Features

• ✅ Spec-aligned API coverage — wrapper/spec alignment checks against api_specs/current/britecore.json
• ✅ Async-ready — Cache-aware async wrappers for high-concurrency workflows
• ✅ Flexible auth — Automatic API key or OAuth2 token management
• ✅ Type hints — Full PEP 561 type information for IDE support
• ✅ Validators — Email, phone, address, and name validation utilities
• ✅ Models — Domain classes for Contact, Policy, and Quote payloads
• ✅ Config-first — Dynaconf-based environment and secrets management
• ✅ Production-ready — Stable API, comprehensive tests, security-focused
• ✅ Context manager — with BritecoreAPIClient("site").init_client() as client:
• ✅ Flat exceptions — from britecore_sdk import NotFoundError, AuthenticationError
• ✅ CLI commands — britecore-healthcheck, britecore-check-config, britecore-run-checks
• ✅ Debug dry-run — per-call dry_run=True or client default init_api_client(client_dry_run=True)
• ✅ Rate limiting — Optional token bucket with adaptive backoff on 429 responses
• ✅ Batch operations — workflow helpers for parallel quote/contact/policy/risk creation

Migration Notes

Batch result schema — id/data replaces legacy alias keys (v2.2+)

Importer consumers of create_full_quotes_batch and create_contacts_batch should migrate from the old per-item alias keys to the new canonical keys.

Old pattern (legacy aliases — still emitted by default):

results = create_full_quotes_batch(quotes)
for item in results["items"]:
    quote_id   = item["quote_id"]    # legacy alias
    quote_data = item["quote_data"]  # legacy alias

New pattern (canonical keys — preferred):

results = create_full_quotes_batch(quotes)
for item in results["items"]:
    quote_id   = item["id"]    # canonical
    quote_data = item["data"]  # canonical
    error_type = item["error_type"]  # new — machine-readable error category

Per-item schema (all keys always present):

Legacy alias keys (quote_id/quote_data, contact_id/contact_data) are included by default for backward compatibility. Opt out once your importer is migrated:

results = create_full_quotes_batch(quotes, include_legacy_keys=False)

The legacy alias keys will be removed in a future major version. Migrate to id/data now to avoid breaking changes.

See docs/BATCH_QUOTE_CREATION.md for the full parameter reference and workflow examples.

Documentation

Installation & Configuration

Requirements

• Python >=3.11

Install

Windows (PowerShell):

# Base install (API client + wrappers)
pip install britecore_sdk

# With optional extras
pip install britecore_sdk[all]         # All extras
pip install britecore_sdk[dev]         # Development (tests, linting, type checking)

Linux/macOS (bash):

# Base install (API client + wrappers)
pip install britecore_sdk

# With optional extras
pip install britecore_sdk[all]         # All extras
pip install britecore_sdk[dev]         # Development (tests, linting, type checking)

Configuration

The SDK loads settings from multiple locations in priority order — later sources override earlier ones. BRITECORE_SDK_* environment variables always win over any file. See the canonical precedence table in CONFIG_MANAGEMENT.md.

Use one of these setup paths:

• User-level config (recommended): ~/.britecore/settings.toml + ~/.britecore/.secrets.toml
• Project-local config: ./britecore.toml + ./.britecore_secrets.toml
• Explicit credentials in code: init_api_client(base_url=..., api_key=...)
• Environment variables: BRITECORE_SDK_* values override all file-based settings

Note: Hostnames under example.com in this repository are placeholders. In standard file/env mode, target_site is required. In explicit mode (init_api_client(base_url=..., ...)), target_site is optional and defaults to "explicit".

See GETTING_STARTED.md and CONFIG_MANAGEMENT.md for full configuration examples.

Validate configured sites before first API calls:

# As an installed command (after pip install) — works in bash and PowerShell:
britecore-check-config

# Or via python -m:
python -m britecore_sdk.utils.check_site_configs

Check whether the checked-in local API spec is current and whether upstream has a newer version:

python -m britecore_sdk.utils.check_api_spec_sync

Run an end-user readiness check (config + auth + safe API ping):

# As an installed command:
britecore-healthcheck --site production

# Or via python -m:
python -m britecore_sdk.utils.healthcheck --site production

Validation rule: each site needs base_url and either a full OAuth pair (client_id + client_secret) or an api_key.

What This Package Provides

API Wrappers

• Endpoint modules: broad v2 domain coverage plus supported v1 wrapper modules where the upstream API still uses v1 paths (see API.md for current module inventory)
• Async wrappers: Cache-aware async versions of key endpoint workflows

Utilities

• Models: BritecoreContact, BritecorePolicy, BritecoreQuote with type hints
• Validators: Email, phone, address, and name validation
• Auth: Automatic OAuth2 or API key selection based on config
• Config: Dynaconf-based environment/secrets management
• Logging: Structured logging with standard Python logging module

Optional Extras

Using Async Wrappers

The v2 package exports async-aware wrappers (e.g., aget_quote, aget_contact, aretrieve_policy) with built-in caching for read operations.

import asyncio
from britecore_sdk.api.api_calls.v2 import async_policies

async def main():
    policy = await async_policies.aretrieve_policy(policy_number="POL001")
    print(policy)

asyncio.run(main())

Native async transport (optional)

By default the async client wraps the sync urllib3 transport in a thread pool. For true non-blocking I/O install the optional async-http extra and select the httpx transport:

pip install britecore_sdk[async-http]

from britecore_sdk.api import AsyncBritecoreAPIClient

async_client = AsyncBritecoreAPIClient(target_site="prod", async_transport="httpx")

See docs/ASYNC_CACHING.md for cache configuration, transport options, and invalidation.

Development

Install for Development

Windows (PowerShell):

pip install -e ".[dev]"

Linux/macOS (bash):

pip install -e ".[dev]"

Run Tests

Windows (PowerShell):

# All tests
pytest tests/ -v

# By category
pytest tests/unit -m unit -v
pytest tests/integration -m integration -v

# Core client changes
pytest tests/unit/test_api_client.py tests/unit/test_core_client_coverage.py -v

Linux/macOS (bash):

# All tests
pytest tests/ -v

# By category
pytest tests/unit -m unit -v
pytest tests/integration -m integration -v

# Core client changes
pytest tests/unit/test_api_client.py tests/unit/test_core_client_coverage.py -v

Linting & Type Checking

Windows (PowerShell):

ruff check src/
black --check src/
mypy src/britecore_sdk/api/britecore_api_client.py

Linux/macOS (bash):

ruff check src/
black --check src/
mypy src/britecore_sdk/api/britecore_api_client.py

Release Publishing (GitHub Actions)

• TestPyPI dry-run workflow: .github/workflows/publish-testpypi.yml (manual trigger only via workflow_dispatch)
• Production PyPI workflow: .github/workflows/publish.yml (automatic after .github/workflows/release.yml completes successfully, and also manually runnable via workflow_dispatch)

Both workflows use OIDC trusted publishing and include build + publish + install smoke tests. Depending on your GitHub environment protection rules, the publish job may still pause for environment approval even when the workflow itself was triggered automatically.

1. Create GitHub environments: testpypi and pypi.
2. In TestPyPI, add a Trusted Publisher entry for:
   • Repository: sshimek42/britecore_sdk
   • Workflow: .github/workflows/publish-testpypi.yml
   • Environment: testpypi
3. In PyPI, add a Trusted Publisher entry for:
   • Repository: sshimek42/britecore_sdk
   • Workflow: .github/workflows/publish.yml
   • Environment: pypi
4. Run Publish to TestPyPI from the Actions tab before cutting a production release.
5. Push a version tag (for example v2.0.5) to trigger .github/workflows/release.yml, which builds artifacts and creates the GitHub Release automatically.
6. After .github/workflows/release.yml completes successfully, .github/workflows/publish.yml runs automatically and publishes to PyPI. You can also run Publish to PyPI manually from the Actions tab when needed.

Contributing

See CONTRIBUTING.md for:

• Workflow and branch conventions
• Endpoint wrapper patterns
• Code quality expectations
• Repository-specific guidance in AGENTS.md

Architecture

• BritecoreAPIClient — Core HTTP transport and response processing
• Context manager — with client: pattern closes the connection pool on exit
• Fluent init — client = BritecoreAPIClient("site").init_client() (one-liner)
• Endpoint modules — Build request JSON → call do_request() → return process_result()
• Auth modes — Automatic: API key (when client_id/client_secret blank) or OAuth2 (when both provided)
• Config — Dynaconf-based layered config: SDK defaults → ~/.britecore/ → ./britecore.toml → BRITECORE_SDK_SETTINGS_FILE → env vars
• Lazy initialization — API client initializes on first use to avoid import-time failures (see "About API Client Initialization" above)
• Flat exceptions — Import NotFoundError, AuthenticationError etc. directly from britecore_sdk

See ARCHITECTURE.md for detailed design.

Support & Links

• Issues & feedback: GitHub Issues
• Security concerns: See SECURITY.md
• Roadmap & stability: See STABILITY.md
• External API docs: api.britecore.com (supplemental reference)