Migration Guide: SDK v1 → v2

This guide helps you upgrade from BriteCore SDK v1 to v2. While v2 maintains API compatibility, there are some important changes to be aware of.

Overview of Changes

The v2 upgrade focuses on:

Better type hints for IDE support and type checking
Lazy initialization of API clients
Improved exception handling with structured error messages
Async/await support for high-performance workflows
Structured logging for better observability

Before (v1) vs After (v2)

Client Initialization

Before (v1 - Eager):

from britecore_sdk.api.britecore_api_client import BritecoreAPIClient

# Client initializes immediately
client = BritecoreAPIClient("production")
client.init_client()
policy = client.do_request(path="/api/policies", ...)

After (v2 - Lazy & Preferred):

from britecore_sdk.api.api_calls import get_api_client

# Client initializes on first use (lazy)
client = get_api_client()
# OR explicit initialization:
from britecore_sdk.api.api_calls import init_api_client
client = init_api_client("production").init_client()

Endpoint Wrappers

Before (v1):

from britecore_sdk.api.api_calls.v1 import policies

# No type hints
result = policies.retrieve_policy(policy_number="POL-123")

After (v2 - Preferred, v1 still works):

from britecore_sdk.api.api_calls.v2 import policies

# Better type hints, improved docs
result = policies.retrieve_policy(policy_number="POL-123")

Exception Handling

Before (v1):

from britecore_sdk.exceptions import BritecoreError

try:
    policy = policies.retrieve_policy(policy_number="POL-123")
except BritecoreError.NotFoundError as e:
    print(f"Policy not found: {e}")

After (v2 - Flat imports preferred):

from britecore_sdk.exceptions import NotFoundError

try:
    policy = policies.retrieve_policy(policy_number="POL-123")
except NotFoundError as e:
    # Error now includes helpful hints
    print(f"Policy not found: {e}")
    if e.hint:
        print(f"Hint: {e.hint}")

Model Classes

Before (v1):

from britecore_sdk.classes import BritecoreContact

contact = BritecoreContact(name="John", ...)

After (v2):

from britecore_sdk.models import BritecoreContact

contact = BritecoreContact(name="John", ...)

Async Operations

Before (v1 - Not available):

# Not supported in v1

After (v2):

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

async def get_policies():
    client = get_async_api_client()
    policies = await aretrieve_policy(policy_number="POL-123")
    return policies

# Run async code
result = asyncio.run(get_policies())

Step-by-Step Migration

Step 1: Update Imports

Find and replace:

from britecore_sdk.api.api_calls.v1 import → from britecore_sdk.api.api_calls.v2 import
from britecore_sdk.classes import → from britecore_sdk.models import
from britecore_sdk.exceptions import BritecoreError → Use flat imports like from britecore_sdk.exceptions import NotFoundError

Step 2: Update Client Initialization

Old code:

from britecore_sdk.api.britecore_api_client import BritecoreAPIClient

client = BritecoreAPIClient("production")
client.init_client()

New code:

from britecore_sdk.api.api_calls import get_api_client

# Lazy - initializes on first use
client = get_api_client()

# OR explicit:
from britecore_sdk.api.api_calls import init_api_client
client = init_api_client("production").init_client()

Step 3: Update Exception Handling

Old code:

from britecore_sdk.exceptions import BritecoreError

try:
    result = endpoint_function()
except BritecoreError.NotFoundError as e:
    handle_not_found(e)

New code:

from britecore_sdk.exceptions import NotFoundError

try:
    result = endpoint_function()
except NotFoundError as e:
    handle_not_found(e)
    # New: error includes helpful hints
    if hasattr(e, 'hint'):
        log_hint(e.hint)

Step 4: Update Validator Usage

Old code:

from britecore_sdk.validators import AddressValidator

validator = AddressValidator()
validated = validator.validate({"address": "123 Main", ...})

New code (same, but better type hints):

from britecore_sdk.validators import AddressValidator

validator = AddressValidator()
validated = validator.validate({"address": "123 Main", ...})
# Type hints now work better in IDE

Step 5: Enable Logging (Optional)

v2 includes structured logging:

from britecore_sdk import configure_logging, LogCategory

# Enable SDK logging
logger = configure_logging(log_to_file=True)

# Logging now includes categories
from britecore_sdk.base_logger import log_with_category
log_with_category(logger, logging.DEBUG, "My message", LogCategory.AUTH)

Breaking Changes

1. Lazy Client Initialization

What changed: Clients now initialize on first use instead of immediately.

Migration: If you rely on immediate client initialization:

# Old - expects immediate error if config is missing
client = BritecoreAPIClient("production")
client.init_client()  # Errors here if config missing

# New - errors on first request
client = get_api_client()  # Returns immediately
policy = client.do_request(...)  # Errors here if config missing

Fix: Use init_api_client() for eager initialization:

client = init_api_client("production").init_client()  # Still eager

2. Exception Hierarchy

What changed: Exception names are now available at top level.

Migration: Update import statements:

# Old
from britecore_sdk.exceptions import BritecoreError
except BritecoreError.NotFoundError:

# New (still works, but preferred is)
from britecore_sdk.exceptions import NotFoundError
except NotFoundError:

3. Module Removal: britecore_sdk.classes

What changed: The britecore_sdk.classes module has been removed.

Migration:

# Old (no longer works)
from britecore_sdk.classes import BritecoreContact

# New
from britecore_sdk.models import BritecoreContact

Compatibility Notes

v1 Endpoints Still Supported

For backward compatibility, v1 endpoint wrappers are still available:

# Still works in v2
from britecore_sdk.api.api_calls.v1 import policies
result = policies.retrieve_policy(policy_number="POL-123")

However: v2 endpoints have better type hints and documentation, so migration is recommended.

Configuration

Configuration format hasn’t changed. Existing settings.toml files work as-is:

[production]
base_url = "https://api.example.com"
api_key = "your_key_here"

Testing Migration

Before (v1 Tests):

from britecore_sdk.api.britecore_api_client import BritecoreAPIClient
from unittest.mock import Mock

mock_client = Mock(spec=BritecoreAPIClient)
mock_client.do_request.return_value = {"data": {...}}

After (v2 Tests - Using New Fixtures):

# Use the new test fixtures library
from tests.fixtures import mock_api_client, mock_policy_response

def test_something(mock_api_client, mock_policy_response):
    # Fixtures handle setup
    pass

Troubleshooting Migration Issues

Issue: “ImportError: cannot import name ‘X’ from britecore_sdk.classes”

Solution: Use the new module paths:

# Instead of: from britecore_sdk.classes import BritecoreContact
from britecore_sdk.models import BritecoreContact

Issue: “Client not initialized” on first request

Solution: You may have caught initialization errors. Check your error handling.

Issue: Type hints not working in IDE

Solution: Make sure you’re using v2 endpoints:

# Use v2 for better type hints
from britecore_sdk.api.api_calls.v2 import policies  # Better
# Not: from britecore_sdk.api.api_calls.v1 import policies

Performance Improvements in v2

Lazy initialization: Clients don’t initialize until first use
Better rate limiting: Improved exponential backoff and adaptive strategies
Async support: Use async/await for non-blocking operations
Request caching: Optional response caching for repeated queries
Structured logging: Filter logs by category for better performance monitoring

Timeline for Deprecations

v2.0-2.x: v1 endpoints available for backward compatibility
v3.0: v1 endpoints will be removed
v3.0: britecore_sdk.classes will be removed

Start migrating to v2 imports now to prepare for v3.

Migration Checklist

[ ] Update all imports from v1 to v2
[ ] Update britecore_sdk.classes imports to britecore_sdk.models
[ ] Update exception imports to use flat names
[ ] Update client initialization if using BritecoreAPIClient directly
[ ] Review error handling to use new exception hints
[ ] Enable logging if needed
[ ] Run existing tests with new code
[ ] Add new tests using test fixtures library
[ ] Test async operations if applicable

Getting Help

If you encounter migration issues:

Check TROUBLESHOOTING.md for common issues
Review COMMON_PATTERNS.md for migration examples
Check your local settings with britecore-quick-check --full
Review error messages - v2 errors include helpful hints
Enable debug logging: configure_logging("DEBUG")

Migration Guide: SDK v1 → v2

Overview of Changes

Before (v1) vs After (v2)

Client Initialization

Before (v1 - Eager):

After (v2 - Lazy & Preferred):

Endpoint Wrappers

Before (v1):

After (v2 - Preferred, v1 still works):

Exception Handling

Before (v1):

After (v2 - Flat imports preferred):

Model Classes

Before (v1):

After (v2):

Async Operations

Before (v1 - Not available):

After (v2):

Step-by-Step Migration

Step 1: Update Imports

Step 2: Update Client Initialization

Step 3: Update Exception Handling

Step 4: Update Validator Usage

Step 5: Enable Logging (Optional)

Breaking Changes

1. Lazy Client Initialization

2. Exception Hierarchy

3. Module Removal: britecore_sdk.classes

Compatibility Notes

v1 Endpoints Still Supported

Configuration

Testing Migration

Before (v1 Tests):

After (v2 Tests - Using New Fixtures):

Troubleshooting Migration Issues

Issue: “ImportError: cannot import name ‘X’ from britecore_sdk.classes”

Issue: “Client not initialized” on first request

Issue: Type hints not working in IDE

Performance Improvements in v2

Timeline for Deprecations

Migration Checklist

Getting Help

See Also