codeforcespy

A fast, type-safe Python wrapper for the Codeforces API with sync and async support.

Features

• Sync & Async - Full support for both blocking and non-blocking clients
• Type Safe - 100% typed, no Any, passes strict pyright
• Fast - Built on httpx and msgspec for high performance
• Complete - Covers all public Codeforces API endpoints

Installation

pip install codeforcespy

Quick Start

Async Client (Recommended)

import asyncio
import codeforcespy.processors

async def main():
    client = codeforcespy.processors.AsyncMethod()
    
    try:
        # Get user info
        users = await client.get_user(handles="tourist")
        print(f"{users[0].handle}: {users[0].rating}")
        
        # Get recent contests
        contests = await client.get_contest_list()
        print(f"Found {len(contests)} contests")
    finally:
        await client.close()

asyncio.run(main())

Sync Client

import codeforcespy.processors

client = codeforcespy.processors.SyncMethod()

try:
    users = client.get_user(handles="tourist")
    print(f"{users[0].handle}: {users[0].rating}")
finally:
    client.close()

API Methods

User

Contest

Problemset

Blog & Recent

Authentication

For authenticated endpoints (friends, private data):

client = codeforcespy.processors.AsyncMethod(
    enable_auth=True,
    auth_key="YOUR_API_KEY",
    secret="YOUR_API_SECRET",
)

Get your API key at codeforces.com/settings/api.

Error Handling

import codeforcespy.errors
import codeforcespy.processors

client = codeforcespy.processors.SyncMethod()

try:
    users = client.get_user(handles="nonexistent_user_12345")
except codeforcespy.errors.APIError as e:
    print(f"API error: {e.message}")
except codeforcespy.errors.CodeforcesPyError as e:
    print(f"Library error: {e.message}")

Examples

See the examples/ directory for complete working examples:

• sync_example.py - Synchronous client usage
• async_example.py - Asynchronous client with concurrent requests

License

GPL-3.0 License - see LICENSE for details.