Skip to main content

Python SDK

Official Python SDK for HeadshotMarketing — an async, fully typed client built on httpx that mounts the HeadshotMarketing domain module plus shared platform modules from burdenoff-sdk-libs.

Installation​

pip install headshotmarketing-sdk

# Development install
pip install -e ".[dev]"

Quick start​

import asyncio
from headshotmarketing_sdk import HeadshotmarketingSDK


async def main():
    # Defaults to the shared prod gateways. Override the endpoints (or set
    # HEADSHOTMARKETING_*_ENDPOINT / BURDENOFF_*_ENDPOINT env vars) for local dev.
    sdk = HeadshotmarketingSDK()

    # Sign in with email/password
    await sdk.auth.sign_in(email="[email protected]", password="secret")

    # HeadshotMarketing-domain operations are nested under sdk.headshotmarketing
    campaigns = await sdk.headshotmarketing.campaigns.list()
    leads = await sdk.headshotmarketing.leads.list()

    # Shared cross-product modules are mounted at the top level
    tags = await sdk.tags.list()

    await sdk.close()


asyncio.run(main())

Environment​

The SDK targets production by default. Set BURDENOFF_ENV or pass explicit endpoints:

from headshotmarketing_sdk import HeadshotmarketingSDK

# Production (default)
sdk = HeadshotmarketingSDK()

# Explicit alpha
sdk_alpha = HeadshotmarketingSDK(
    workspace_endpoint="https://alphagraphqlworkspaces.burdenoff.com/workspaces/graphql",
    global_endpoint="https://alphagraphql.burdenoff.com/global/graphql",
)

Nested namespace​

Per the platform mandate, every module surface is nested under its owning module:

await sdk.headshotmarketing.campaigns.list()
await sdk.headshotmarketing.leads.list()
await sdk.headshotmarketing.contacts.list()
await sdk.headshotmarketing.deals.list()
await sdk.headshotmarketing.pipelines.list()
await sdk.headshotmarketing.content.list()
await sdk.headshotmarketing.social.list()
await sdk.headshotmarketing.ads.list()
await sdk.headshotmarketing.seo.list()
await sdk.headshotmarketing.workflows.list()

Modules​

All methods are async. The following modules are mounted on the HeadshotmarketingSDK instance:

auth, billing, channels, conversations, devportal, export, files, groups, health, integrations, headshotmarketing, notifications, organizations, products, rbac, sandbox, scheduler, security, store, support, tags, tours, workspaces.

Configuration​

from headshotmarketing_sdk import HeadshotmarketingSDK

sdk = HeadshotmarketingSDK(
    workspace_endpoint="https://graphqlworkspaces.burdenoff.com/workspaces/graphql",
    global_endpoint="https://graphql.burdenoff.com/global/graphql",
    client_id="burdenoff_cli_headshotmarketing",
    oidc_issuer=None,                       # derived from global_endpoint
    api_key=None,
    access_token=None,
    refresh_token=None,
    workspace_token=None,
    timeout=30.0,
    auto_refresh=True,
)

Error handling​

from headshotmarketing_sdk import (
    HeadshotmarketingError,
    AuthenticationError,
    AuthorizationError,
    NetworkError,
    ValidationError,
    RateLimitError,
    DeviceCodeExpiredError,
    DeviceCodeDeniedError,
)

try:
    await sdk.auth.sign_in(email="[email protected]", password="wrong")
except AuthenticationError:
    print("Invalid credentials")
except NetworkError:
    print("Could not reach the API")
except HeadshotmarketingError as e:
    print(f"SDK error: {e}")

Development​

git clone https://github.com/algoshred/headshotmarketing-sdk-python.git
cd headshotmarketing-sdk-python
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

make format        # black + isort
make lint          # flake8
make type-check    # mypy (strict)
make test          # pytest
make sanity        # format-check + lint + type-check + test (cov>=80) + build
Last updated on