AB SDK
Python SDK for the ABConnect API ecosystem.
Quickstart · What's New · 8_01 migration · Release runbook
API Surfaces
| Surface | Base URL | Auth |
|---|---|---|
| ACPortal | portal.{env}.abconnect.co/api/api/ |
Bearer JWT |
| Catalog | catalog-api.{env}.abconnect.co/api/ |
Bearer JWT |
| ABC | api.{env}.abconnect.co/api/ |
Bearer JWT + accessKey |
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
| Group | Methods | API Surface |
|---|---|---|
api.companies |
get_by_id, get_details, get_fulldetails, search, list, create, update_fulldetails, available_by_current_user | ACPortal |
api.contacts |
get, get_did, get_details, get_primary_details, get_current_user, search, create, update_details | ACPortal |
api.jobs |
get, search, search_by_details, get_price, get_calendar_items, get_update_page_config, create, save, update | ACPortal + ABC |
api.documents |
list, get, upload, update | ACPortal |
api.address |
validate, get_property_type | ACPortal |
api.lookup |
get_contact_types, get_countries, get_job_statuses, get_items | ACPortal |
api.users |
list, get_roles, create, update | ACPortal |
api.catalog |
list, get, create, update, delete, merge, bulk_upsert | Catalog (staging schema) |
api.lots |
list, get, create, update, delete, merge, item_data, client item data | Catalog (staging schema) |
api.sellers |
list, get, create, update, delete | Catalog (staging schema) |
api.platforms |
list, get, create, update, delete | Catalog (staging schema) |
api.jobs.agent |
oa, da, change | ACPortal |
api.jobs.timeline |
schedule, received, pack_start, pack_finish, storage_begin, storage_end, carrier_schedule, carrier_pickup, carrier_delivery, delete, delete_all | ACPortal |
api.autoprice |
quick_quote, quote_request | ABC |
api.web2lead |
get, post | ABC |
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.
Metadata
Release files for annex-abconnect 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| annex_abconnect-0.3.0.tar.gz | 342.9 kB | Without provenance | Details for annex_abconnect-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| annex_abconnect-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for annex_abconnect-0.3.0-py3-none-any.whl |
Total release size: 747.8 kB
Release files / annex_abconnect-0.3.0.tar.gz
| Download URL | annex_abconnect-0.3.0.tar.gz |
|---|---|
| Size | 342.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a25ceb19ba20f717e6f4506eb4b367d584eb815e964b3f63466218e3d0a34b20
|
|
BLAKE2b-256 checksum How to use checksums |
7df22345156d03ab4e208c456d3e1f31fdfda235555091b7165397ab25f1e0c1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / annex_abconnect-0.3.0-py3-none-any.whl
| Download URL | annex_abconnect-0.3.0-py3-none-any.whl |
|---|---|
| Size | 405.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b44e2ecd93eaff71be39dd145953dbb4bb739633dcd58b38a4b1e389c92a9fb0
|
|
BLAKE2b-256 checksum How to use checksums |
a86ba4d2606bed1593adb91fd1d3f0f961ac976764dcab0821a0a03015537a9b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Security for annex-abconnect 0.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.