tabroom 0.1.0

Python client for tabroom.com API

Tabroom Python Client

A type-safe Python client library for the Tabroom.com API. Built with Pydantic for data validation and HTTPX for reliable HTTP requests.

Features

• Type-safe: All API responses are validated with Pydantic models
• Organized: Resources grouped by domain (user, tournaments, tabulation, etc.)
• Easy to use: Fluent API with method chaining for nested resources
• Well-documented: Comprehensive docstrings and examples
• Error handling: Custom exceptions for different error types
• Context manager support: Automatic connection cleanup

Installation

# Using uv (recommended)
uv pip install -e .

# Or using pip
pip install -e .

Quick Start

from tabroom import TabroomClient

# Initialize the client
client = TabroomClient(
    username="[e-mail]",
    password="your_password"
)

# Get your profile
profile = client.user.get_profile()
print(f"Logged in as: {profile.first} {profile.last}")

# Search for tournaments
tournaments = client.public.search_tournaments("future", "TOC")
print(f"Found {len(tournaments)} tournaments")

# Don't forget to close the connection
client.close()

# Or use as context manager (auto-closes)
with TabroomClient(username="user", password="pass") as client:
    profile = client.user.get_profile()

API Resources

The client organizes API endpoints into logical resource groups:

User (client.user)

• get_profile() - Get your user profile
• get_profile_by_id(person_id) - Get another user's profile

Public (client.public)

• search_tournaments(time, search_string, circuit_id=None) - Search tournaments
• get_upcoming_tournaments(circuit=None) - List upcoming tournaments
• get_ads() - Get front page advertisements
• get_tournament_by_id(tourn_id) - Get tournament by ID
• get_tournament_by_webname(webname) - Get tournament by webname

Tab (client.tab)

Tournament tabulation operations with nested resources:

# Tournament-level operations
client.tab.tournament(tourn_id).get_dashboard()
client.tab.tournament(tourn_id).get_attendance()
client.tab.tournament(tourn_id).mark_attendance(data)
client.tab.tournament(tourn_id).get_category_checkin(category_id)

# Round-level operations
client.tab.tournament(tourn_id).round(round_id).get_dashboard()
client.tab.tournament(tourn_id).round(round_id).get_attendance()
client.tab.tournament(tourn_id).round(round_id).mark_attendance(data)

# Timeslot-level operations
client.tab.tournament(tourn_id).timeslot(timeslot_id).get_dashboard()
client.tab.tournament(tourn_id).timeslot(timeslot_id).get_attendance()

Access (client.access)

Permission management with hierarchical access control:

# Tournament-level access
client.access.tournament(tourn_id).grant(person_id, permissions)
client.access.tournament(tourn_id).revoke(person_id)

# Event-level access
client.access.tournament(tourn_id).event(event_id).grant(person_id, permissions)
client.access.tournament(tourn_id).event(event_id).revoke(person_id)

# Category-level access
client.access.tournament(tourn_id).category(category_id).grant(person_id, permissions)
client.access.tournament(tourn_id).category(category_id).revoke(person_id)

Caselist (client.caselist)

• get_students(person_id) - Get students for a person
• get_rounds(person_id) - Get rounds for a person
• get_chapters(person_id) - Get chapters for a person
• create_link(data) - Create a caselist link

NSDA (client.nsda)

• get_history(nsda_id) - Get NSDA membership history

Share (client.share)

• send_share_file(data) - Send document to docchain

Payment (client.payment)

• process_paypal(data) - Process PayPal payment
• process_authorize(data) - Process Authorize.net payment

System (client.system)

• get_status() - Check API status
• post_status(data) - Check API status via POST

Error Handling

The client provides specific exception types for different errors:

from tabroom import (
    TabroomError,           # Base exception
    TabroomAuthError,       # 401/403 errors
    TabroomNotFoundError,   # 404 errors
    TabroomValidationError, # 422 errors
    TabroomServerError,     # 5xx errors
    TabroomAPIError,        # Other API errors
)

try:
    profile = client.user.get_profile()
except TabroomAuthError:
    print("Authentication failed - check credentials")
except TabroomNotFoundError:
    print("Resource not found")
except TabroomError as e:
    print(f"API error: {e.message}")

Data Models

All API responses are parsed into Pydantic models for type safety:

• Person - User profile data
• Session - Login session information
• Invite - Tournament invitation/details
• Event - Tournament event
• Round - Tournament round
• Search - Search result
• Student - Student information
• Chapter - Chapter/school chapter
• Ad - Advertisement
• And more...

Examples

See the examples/ directory for comprehensive usage examples:

• basic_usage.py - Getting started
• tournament_management.py - Tabulation operations
• access_control.py - Permission management
• caselist_nsda.py - Caselist and NSDA integration
• error_handling.py - Error handling patterns

Development

# Install with dev dependencies
uv pip install -e ".[dev]"

# Run type checking
mypy tabroom

# Run tests
pytest

Project Structure

tabroom-python/
\x00\x00 tabroom/
   \x00\x00 __init__.py          # Main TabroomClient
   \x00\x00 client.py            # Base HTTP client
   \x00\x00 auth.py              # Authentication
   \x00\x00 exceptions.py        # Custom exceptions
   \x00\x00 models/              # Pydantic models
      \x00\x00 common.py
      \x00\x00 auth.py
      \x00\x00 user.py
      \x00\x00 tournament.py
      \x00\x00 school.py
      \x00\x00 caselist.py
      \x00\x00 share.py
   \x00\x00 resources/           # API resource groups
       \x00\x00 user.py
       \x00\x00 public.py
       \x00\x00 tab.py
       \x00\x00 access.py
       \x00\x00 caselist.py
       \x00\x00 nsda.py
       \x00\x00 share.py
       \x00\x00 payment.py
       \x00\x00 system.py
\x00\x00 examples/                # Usage examples
\x00\x00 tests/                   # Test suite

API Documentation

This client is based on the Tabroom API v1. For detailed API documentation, visit the Tabroom API docs.

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.