britecore_sdk

Last updated: September 23, 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.5.1+) | License: Apache-2.0 | Python: 3.11+

Documentation ownership: britecore_sdk is the canonical source for SDK installation, auth, configuration, API usage, examples, and troubleshooting. The britecore_docs repo is the ecosystem map for repo boundaries, architecture, and cross-project workflows.

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", client=client)
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).

Deprecation direction: implicit wrapper-client fallback remains supported for compatibility, but new integrations should prefer explicit client= passing or scoped use_api_client(...) usage. See DEPRECATION.md for the planned v3.0.0 removal timeline.

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, Quote, Claim, Vehicle, Driver, Coverage, Payment Method, and Line Definition 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-quick-check, britecore-config-wizard, britecore-check-config, britecore-healthcheck
• ✅ Data normalization CLI — britecore-normalize-json for script-first workflows
• ✅ 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
• ✅ Write safety policies — write_policy=allow|warn|block for read-only enforcement
• ✅ Request auditing — Optional AuditMiddleware for structured write-event logs

Migration Notes

2.6.x -> v3.0.0 Direction

v3.0.0 is a cleanup and standardization release, not a redesign of the SDK's core site/auth configuration model.

• 2.5.x starts runtime deprecation signaling on legacy patterns.
• 2.6.x is the intended migration-validation window before major-version removals.
• v3.0.0 removes previously deprecated runtime surfaces (implicit wrapper client fallback, global lifecycle helper pattern, and legacy batch alias keys).

Site/auth configuration concepts remain stable across this transition. Existing approaches centered on base_url plus API key or OAuth credentials remain supported.

See DEPRECATION.md for timeline details and docs/MIGRATION_2_4_to_2_5.md for migration examples from prior versions.

Lightweight Data Layer for Scripts

For one-off scripts that only need data shaping (no API transport), use britecore_sdk.data_layer.

from britecore_sdk.data_layer import normalize_contact_payload

payload = normalize_contact_payload(
    name="acme llc",
    address={
        "address_line1": "123 Main St",
        "address_city": "Madison",
        "address_state": "WI",
        "address_zip": "53703",
    },
    phone_numbers=[{"phone": "(920) 555-1234", "type": "mobile"}],
    emails=[{"email": "TEAM@ACME.COM", "type": "work"}],
)

Available helpers: normalize_name, normalize_address, normalize_phones, normalize_emails, normalize_contact_payload, normalize_policy_payload, normalize_quote_payload, normalize_payment_method_payload, normalize_vehicle_payload, normalize_coverage_payload, normalize_driver_payload, and normalize_line_definition_payload.

For a local-only walkthrough of model construction and payload shaping, see examples/model_payload_workflow.py.

CLI option for file-based workflows:

britecore-normalize-json --kind contact --input .\contact.raw.json --output .\contact.normalized.json --pretty
britecore-normalize-json --schema --kind policy --pretty

Write Safety and Auditing

The SDK now supports config-first write controls for admin API keys:

• write_policy="allow" - no guard (backward-compatible default)
• write_policy="warn" - emit a warning before write-like operations
• write_policy="block" - raise ReadOnlyViolation before sending write-like operations

You can set these globally per site in settings:

# ~/.britecore/settings.toml
[default]
write_policy = "warn"
write_allowlist = []
write_denylist = []
enable_audit_middleware = true
audit_only_writes = true
audit_log_level = "info"

These are policy/behavior keys (not credentials), so keep them in settings.toml.

You can also override behavior in code at initialization time:

from britecore_sdk.api.britecore_api_client import BritecoreAPIClient

client = BritecoreAPIClient("production").init_client(
    write_policy="block",
    enable_audit_middleware=True,
    audit_only_writes=True,
)

Write/audit controls are centralized in middleware and apply to all wrapper calls.

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

This repo is the authoritative SDK documentation set. Use it for installation, auth, configuration, endpoint usage, examples, and troubleshooting. For ecosystem-level guidance and repo boundaries, see the britecore_docs hub.

Docs QA before PRs

Before opening a docs-heavy PR, run the one-command docs QA script:

python scripts/docs_qa.py

Equivalent manual commands (if you want to run each step separately):

python -m sphinx -W --keep-going -b html ./docs ./docs/_build/html-strict
python -m sphinx -b linkcheck ./docs ./docs/_build/linkcheck

For common failures and fixes, see docs/DOCUMENTATION_BUILD_TROUBLESHOOTING.md.

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, BritecoreClaim, BritecorePaymentMethod, BritecoreVehicle, BritecoreCoverage, BritecoreDriver, and BritecoreLineDefinition
• 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 import get_async_api_client, init_async_api_client
from britecore_sdk.api.api_calls.v2 import async_policies

async def main():
    init_async_api_client("production")
    client = get_async_api_client()
    policy = await async_policies.aretrieve_policy(policy_number="POL001", client=client)
    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 for CI-created GitHub releases, 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 SemVer tag (for example v2.0.5 or v2.0.5-rc.1) to trigger .github/workflows/release.yml.
6. release.yml validates that the tag format is valid and that the tag version matches project.version in pyproject.toml before running tests/build/release steps.
7. After .github/workflows/release.yml completes and publishes the GitHub Release, .github/workflows/publish.yml runs automatically and publishes to PyPI. (Manual UI-created releases do not auto-publish; use workflow_dispatch for intentional manual publishing, select a release tag as the workflow ref, and provide the same value in the release-tag input.)

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)