Skip to content

README.md

Latest commit

 

History

History
142 lines (103 loc) · 3.81 KB

README.md

File metadata and controls

142 lines (103 loc) · 3.81 KB

codeforcespy

PyPI Python 3.13+ License: GPL-3.0 Type Safe

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

codeforcespy

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

Method Description
get_user(handles) Get user profile(s) by handle
get_user_rating(handle) Get rating history
get_user_status(handle, count) Get recent submissions
get_user_friends(only_online) Get friends list (auth required)
get_user_blog_entries(handle) Get user's blog posts
get_user_rated_list(...) Get rated users list

Contest

Method Description
get_contest_list(of_gym) List all contests
get_contest_standings(...) Get contest standings
get_contest_status(contest_id) Get contest submissions
get_contest_hacks(contest_id) Get contest hacks
get_contest_rating_changes(contest_id) Get rating changes

Problemset

Method Description
get_problemset_problems(tags) Get problems by tags
get_problemset_recent_status(count) Get recent submissions

Blog & Recent

Method Description
get_blog_entry_view(blog_entry_id) Get blog post
get_blog_entry_comments(blog_entry_id) Get blog comments
get_recent_actions(max_count) Get recent platform activity

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.