Codeforces API package documentation

Warning

This is a WIP work.

Codeforces is a website that hosts competitive programming contests. This project acts as a bridge between its API and your code, giving you the tools to retrieve data from it.

The primary objective of this package is to give the programmer the facility of usage that this API needs. Also the integration with the language was a main concern when developing it, so you can expect typed methods and data efficient data classes (using python’s __slots__ property)

Basic Usage

The usage is pretty straightforward:

Example of user.info API method.

from aiohttp import ClientSession
from cforces import Client
import asyncio


async def main() -> None:
    async with ClientSession() as session:  # Enter an async context (for aiohttp.ClientSession to spawn)
        client: Client = Client(
            session
        )  # Instantiate a Client object and pass the aiohttp session to it.
        print(await client.user_info(["x93bd0"]))  # Call user.info API method


if __name__ == "__main__":
    asyncio.run(main())

You just need to instantiate a Client object (the one making the API requests). and then you can start using it within an async with expression.

The Client object has built-in methods for every Codeforces API endpoint, but in snake_case instead of Codeforces’s pascalCase and replacing every dot with an underscore. For example, the api method blogEntry.comments is the equivalent of blog_entry_comments() inside the object.

Authentication

The Codeforces API allows user authentication via the usage of an api key and secret pair. Those credentials are obtained in the settings panel of your Codeforces account, in the “API” section. As an alternative, you can directly access it from this link.

This pair is used in the client for authenticating itself. It is supplied using the method auth():

Example of user.friends API method with an authenticated user.

from aiohttp import ClientSession
from cforces import Client
import asyncio


YOUR_API_KEY: str = "abcdefghijklmnopqrstuvwxz1234567890abcde"
YOUR_API_SECRET: str = "abcdefghijklmnopqrstuvwxz1234567890abcde"


async def main() -> None:
    async with ClientSession() as session:  # Enter an async context (for aiohttp.ClientSession to spawn)
        client: Client = Client(
            session
        )  # Instantiate a Client object and pass the aiohttp session to it.

        client.auth(
            YOUR_API_KEY, YOUR_API_SECRET
        )  # Authenticate the client with an api key & secret pair

        print(await client.user_friends())  # Call user.friends API method


if __name__ == "__main__":
    asyncio.run(main())