cohost-client 0.1.0

Python client library for the Cohost External API

cohost-client

Python client library for the Cohost External API.

Installation

pip install cohost-client

Quick Start

from cohost_client import configure_client
from cohost_client.generated.api import customers, listings, bookings

# Configure once at startup
configure_client(api_key="your-api-key")

# List customers
result = customers.list_customers(page=1, page_size=20)
for customer in result.items:
    print(customer.email)

# Log in a customer and use their token
login_result = customers.customer_login(email="[e-mail]", password="secret")
configure_client(bearer_token=login_result.access_token)

# Get listings
listing = listings.get_listing_detail(listing_id=123)
print(listing.name)

Authentication

Two auth schemes are supported:

• API Key (X-API-Key): for all /api/v1/external/* endpoints — set via configure_client(api_key=...) or set_api_key(...).
• JWT Bearer: for customer-facing endpoints — set via configure_client(bearer_token=...) or set_bearer_token(...).

Self-Update

The generated API code is built from the live OpenAPI spec. To regenerate when the backend changes:

# Check if the spec has changed (exits 1 if outdated)
cohost-update --check

# Fetch latest spec and regenerate all code
cohost-update

Or using Make:

make generate

Development

Prerequisites

• Python 3.10+ (use pyenv to manage versions)
• make

First-time setup

# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

# Install the package and all dev dependencies
make install

Do not use pip install --target ./vendor. The project uses a standard virtual environment — the vendor/ directory is ignored by git.

Common tasks

# Run the full code generation pipeline (fetch spec → clean → models → api)
make generate

# Run tests against your checkout (after `make install` — uses local `cohost_client/`)
make test

# Run tests against a built wheel only (no local package on PYTHONPATH)
make test-installed

# Optional: live tests against staging — put secrets in `.env` (gitignored)
cp .env.example .env
# Edit `.env` and set COHOST_API_KEY (and optionally COHOST_TEST_* for login)
pytest -m live

# Or export in the shell instead of `.env`
# export COHOST_API_KEY="your-staging-api-key"
# export COHOST_TEST_EMAIL="[e-mail]"
# export COHOST_TEST_PASSWORD="your-password"

# Check if the remote spec has changed without regenerating (exits 1 if outdated)
make update-check

# Build the distribution packages (sdist + wheel)
make build

How It Works

See docs/plan.md for full architecture details.

The library is structured as:

• cohost_client/client.py — HTTP layer (auth, error handling)
• cohost_client/generated/models/ — Pydantic v2 models (auto-generated)
• cohost_client/generated/api/ — Typed API functions grouped by tag (auto-generated)
• cohost_client/cli.py — cohost-update CLI for self-update