AB SDK

Python SDK for the ABConnect API ecosystem.

Quickstart · What's New · 8_01 migration · Release runbook

API Surfaces

Installation

For an application using the SDK (Python 3.11+):

python -m pip install annex-abconnect

For SDK development, clone this repository and install its tools:

uv sync

This creates or updates the local .venv, installs the package in editable mode, and includes the default dev dependency group.

Additional groups:

# Docs toolchain
uv sync --group docs

# Install everything declared for local development
uv sync --all-groups

Quick Start

from ab import ABConnectAPI

api = ABConnectAPI(env="staging")

# Get a company
company = api.companies.get_by_id("14004OH")
print(company.name)

# Get current user contact
me = api.contacts.get_current_user()
print(me.full_name)

# List lookup data
countries = api.lookup.get_countries()
roles = api.users.get_roles()

Discovering the surface

Endpoint groups are typed attributes, so editors autocomplete them as you type api. (and so do IPython/Jupyter at runtime). To list them programmatically — the Python equivalent of running ab with no arguments:

api.groups()        # ['address', 'autoprice', 'catalog', 'commodities', ...]
repr(api)           # "<ABConnectAPI env='staging' groups=23>"

Configuration

Set environment variables with ABCONNECT_ prefix:

export ABCONNECT_USERNAME=myuser
export ABCONNECT_PASSWORD=mypass
export ABCONNECT_CLIENT_ID=myapp
export ABCONNECT_CLIENT_SECRET=my-secret
export ABCONNECT_ENVIRONMENT=staging

Or use .env.staging / .env.production files.

ABCONNECT_USERNAME and ABCONNECT_PASSWORD are required for the default file-backed service-account mode. Django request sessions and explicit token_storage= integrations can construct the client with only ABCONNECT_CLIENT_ID and ABCONNECT_CLIENT_SECRET, then call api.login(username, password) to prime the selected token storage.

Endpoint Groups

Agent Assignment Helpers

Change origin or delivery agents by friendly company code:

from ab import ABConnectAPI

api = ABConnectAPI(env="staging")

# Change origin agent (pick-and-pack) using a company code
result = api.jobs.agent.oa(12345, "3P-5153")

# Change delivery agent with price recalculation
result = api.jobs.agent.da(12345, "9999AZ", recalculate_price=True)

# Generic change with explicit service type
from ab.api.models.enums import ServiceType
result = api.jobs.agent.change(12345, "9999AZ", service_type=ServiceType.PICK)

# UUIDs work too — resolver detects them and skips cache lookup
result = api.jobs.agent.oa(12345, "ed282b80-54fe-4f42-bf1b-69103ce1f76c")

Running Examples

The SDK ships with runnable examples for every endpoint group. Use the ex console script or python -m examples:

# List all available example modules
ex --list

# Run all examples for a module
ex contacts

# Run a single entry (dot syntax)
ex contacts.get_details

# Prefix matching and aliases work too
ex co.get_d          # matches companies.get_details
ex addr.val          # matches address.validate

Examples run from the source checkout; they are not included in the installed package. Each example calls the configured API and displays the result. Captures are sanitized and written to tests/captures/; committed fixtures are updated through the certification workbench's review and approval flow.

Documentation

Build Sphinx docs:

uv run --group docs make -C docs html

Testing

# Unit + fixture validation tests (no network)
uv run pytest tests/ --ignore=tests/integration -v

# Live integration tests (requires staging credentials)
uv run pytest tests/integration/ -m live -v

Linting

uv run ruff check .

UAT Guide

Step-by-step validation for the SDK after any change.

1. Run the full test suite

cd src && pytest --tb=line -q

Expected: All tests pass or skip. Zero failures. Output shows a summary like:

535 passed, 88 skipped, 3 xfailed

Any FAILED line means a regression — investigate before proceeding.

2. Run quality gate regression

pytest tests/test_gate_regression.py -v

Expected: Single test passes. This verifies no endpoint lost gates compared to the committed baseline.

3. Update the gate baseline

python scripts/update_gate_baseline.py

Expected: Script prints the new gate counts and writes tests/gate_baseline.json. If new endpoints were added, you'll see the count increase. Verify no gates were lost from existing endpoints.

4. Regenerate FIXTURES.md

python scripts/generate_progress.py --fixtures

Expected: FIXTURES.md is regenerated with the current endpoint status. New endpoints appear in the table. Verify their gate columns match expectations.

5. Run mock coverage check

pytest tests/test_mock_coverage.py -v

Expected: Passes. This verifies every example-registered endpoint has a matching mock fixture or documented skip reason.

Troubleshooting

Gate regression failure (test_gate_regression.py fails): A gate that previously passed now fails. Check git diff tests/gate_baseline.json to see which endpoint lost a gate. Common causes: model field removed, response_model annotation dropped, or route definition changed. Fix the root cause, then re-run step 3 to update the baseline.

Fixture missing (test skips with "Fixture needed"): Run the corresponding example to capture the fixture from staging:

ex <module>.<entry>    # e.g., ex timeline.get_timeline

If staging credentials are unavailable, the test will remain skipped until a live capture is performed.

Model mismatch (extra fields warning in test output): The API returned fields not declared in the Pydantic model. Run the example to capture a fresh fixture, inspect the new fields, and add them to the model with Optional[...] types and Field(description=...).

FIXTURES.md drift (table doesn't match current state): Regenerate with python scripts/generate_progress.py --fixtures and verify the diff. Commit the updated file.

Mock Tracking

See MOCKS.md for fixture provenance — which are live-captured vs fabricated.