v1.2.1

Fix circular imports and add comprehensive tests

v1.2.0: Import Compliance, Error Hierarchy, Examples

What's New

Breaking Changes

None - fully backward compatible.

New Features

• Custom Error Hierarchy: Added CodeforcesPyError base exception and APIError for API failures
• Examples Directory: Added sync_example.py and async_example.py with working code

Improvements

• Import Compliance: All imports now use import X style (no from X import Y)
• README Rewrite: Clean, concise documentation with correct API usage
• License Fix: Corrected license classifier to GPL-3.0

Technical

• All code passes pyright with 0 errors, 0 warnings, 0 informations
• All code passes ruff check with no issues

1.1.0

Full Changelog: 1.0...1.1.0

Release 1.0

CodeForcesPy

Faster | Better | Type-Safe

Overview

codeforcespy is a high-performance, type-safe Python library that simplifies interacting with the Codeforces API. It provides both synchronous and asynchronous client handlers to suit different application needs, ensuring that your code remains efficient, reliable, and fully typechecked.

Built entirely based on the official Codeforces API documentation, Codeforcespy adheres to industry best practices, offering a consistent API surface regardless of your chosen client mode.

Table of Contents

• Features
• Installation
• Quick Start
  • Asynchronous Usage
    Synchronous Usage](#synchronous-usage)
• Customization and Advanced Usage
• Contributing
• License

Features

• **Dual Client Handlers:
  Choose between a synchronous handler (SyncMethod) or an asynchronous handler (AsyncMethod) based on your application requirements.

• Type-Safe:
  Leverages static type checking to ensure reliable and maintainable code.

• Authentication Support:
  Easily enable authentication by passing the'' parameter to the client constructor to access user-specific endpoints.

• Modular and Extensible:
  Customize types using the provided'' module for a tailored experience.

• Optimized Serialization:
  Utilizes msgspec for fast data validation and serialization.

• Code Quality:
  Enforced by Ruff for consistent formatting and adherence to best practices.

Installation

As a User

Install codeforcespy via pip:

pip install codeforcespy

As a Developer

For development, install with the extra dependencies:

pip install codeforcespy[dev]

Quick Start

Asynchronous Usage

Below is a basic example demonstrating how to retrieve user information asynchronously:

import asyncio
import pycodeforces

async def main():
    # Initialize the asynchronous client
    api = pycodeforces.AsyncMethod()
    
    # Retrieve user information for multiple handles separated by semicolons
    users = await api.get_user(handles="DmitriyH;Fefer_Ivan")
    
    # Process and print the avatar for each user
    for user in users:
        print(user.avatar)

    # Close the client connection
    await api.close()

asyncio.run(main())

Synchronous Usage

The synchronous client offers similar functionality:

import pycodeforces

def main():
    # Initialize the synchronous client
    api = pycodeforces.SyncMethod()
    
    # Retrieve user information for multiple handles separated by semicolons
    users = api.get_user(handles="DmitriyH;Fefer_Ivan")
    
    # Process and print the avatar for each user
    for user in users:
        print(user.avatar)
    
    # Close the client connection
    api.close()

if __name__ == "__main__":
    main()

Customization and Advanced Usage

• **Authentication:
  To enable authentication for endpoints that require it, simply pass'' along with your API key and secret during client initialization.

• **Type Customization:
  If you need to customize or extend the data models, refer to the'' module, which contains the abstract classes and objects used throughout the library.

• **Consistent API Surface:
  Both client types provide the same set of methods, ensuring that you can switch between asynchronous and synchronous programming with minimal changes.

Contributing

Contributions are welcome! If you’d like to contribute:

• Please review the issues to see where you can help.
• Ensure that your changes maintain strict type-checking and adhere to the established coding guidelines.
• Submit a pull request against the production branch.

License

This project is licensed under the MIT License. See the License file for details.

---

Thank you for checking out Codeforcespy. If you find it useful, please give it a star!

Full Changelog: https://github.com/xsyncio/codeforcespy/commits/1.0