teachworks-sdk 0.2.1

Python SDK for the Teachworks API.

Teachworks SDK

A Python SDK for the Teachworks API. This package provides a typed, validated, and well-organized interface to Teachworks, built around a resilient TeachworksSession that manages authentication, rate limits, pagination, and error handling.

Installation

pip install teachworks-sdk

Quick Start

from teachworks_sdk import TeachworksSession

with TeachworksSession(api_key="your-api-key") as session:
    # List all locations
    locations = session.locations.list()
    for location in locations:
        print(location.id, location.name)

    # Fetch all students across pages
    students = session.students.list(all_pages=True)

    # Retrieve a single record
    employee = session.employees.retrieve(123)

Features

• 23 API resources - Customers, students, employees, lessons, invoices, payments, and more
• Automatic pagination - Fetch all pages with all_pages=True
• Rate limiting - Built-in request throttling and retry with exponential backoff
• Typed responses - Pydantic models with full type hints
• Relationship resolution - Lazy-load related resources
• Session caching - Identity map prevents duplicate fetches
• Comprehensive logging - DEBUG, INFO, WARNING, and ERROR logging with flexible configuration

Documentation

Document	Description
Usage Guide	Configuration, error handling, caching, filtering patterns
Logging Guide	Comprehensive logging configuration and troubleshooting
API Reference	Complete list of resources and methods
Types Reference	All model types and their properties

Basic Examples

Error Handling

from teachworks_sdk import TeachworksSession, TeachworksAPIError

try:
    location = session.locations.retrieve(999999)
except TeachworksAPIError as exc:
    print(exc.status_code, exc.message)

Typed Filtering

from teachworks_sdk import TeachworksSession, Types
from datetime import date

lessons = session.lessons.list(
    query=Types.LessonListParams(
        employee_id=42,
        from_date=date(2024, 1, 1)
    )
)

Relationship Resolution

participant = session.lesson_participants.retrieve(42)
student = participant.resolve(session).student()

Logging

import logging

# Enable SDK logging with your app's configuration
logging.basicConfig(level=logging.INFO)

# Or enable DEBUG logging for SDK only
logging.getLogger("teachworks").setLevel(logging.DEBUG)

# See the Logging Guide for advanced configuration

Development

python -m venv .venv
source .venv/bin/activate
pip install -e .

License

MIT