Metadata-Version: 2.2
Name: codeforcespy
Version: 1.0
Summary: A high-performance and type-safe Python library for seamless interaction with the Codeforces API. Supports both asynchronous and synchronous client handlers, enabling developers to choose the best approach for their needs.
Home-page: https://github.com/xscynio/codeforcespy
Author: Xsyncio
Project-URL: Bug Tracker, https://github.com/xscynio/codeforcespy/issues
Project-URL: Documentation, https://github.com/xscynio/codeforcespy
Project-URL: Source, https://github.com/xscynio/codeforcespy
Keywords: python,codeforces,api,wrapper,async,sync,type-safe
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx
Requires-Dist: msgspec
Provides-Extra: dev
Requires-Dist: ruff; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# codeforcespy

**Faster | Better | Type-Safe**

[![Passing Package](https://github.com/xscynio/codeforcespy/actions/workflows/python-publish.yml/badge.svg)](https://github.com/xscynio/codeforcespy/actions/workflows/python-publish.yml)  
[![Type Checking](https://img.shields.io/badge/python-Strict-checking?style=plastic&logo=python&label=Type-Checking&labelColor=yellow)](https://www.python.org/)

![codeforcespy Logo](https://github.com/xscynio/codeforcespy/assets/118044992/cdb54788-3fbc-48db-b936-7f0e883f9709)

## 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 type-checked.

Built entirely based on the official [Codeforces API Documentation](https://codeforces.com/apiHelp/), codeforcespy adheres to industry best practices, offering a consistent API surface regardless of your chosen client mode.

## Table of Contents

- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
  - [Asynchronous Usage](#asynchronous-usage)
  - [Synchronous Usage](#synchronous-usage)
- [Customization and Advanced Usage](#customization-and-advanced-usage)
- [Contributing](#contributing)
- [License](#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 `enable_auth` parameter to the client constructor to access user-specific endpoints.

- **Modular and Extensible:**  
  Customize types using the provided `abc` module for a tailored experience.

- **Optimized Serialization:**  
  Utilizes [msgspec](https://github.com/jcrist/msgspec) for fast data validation and serialization.

- **Code Quality:**  
  Enforced by [ruff](https://github.com/astral-sh/ruff) for consistent formatting and adherence to best practices.

## Installation

### As a User

Install codeforcespy via pip:

```sh
pip install codeforcespy
```

### As a Developer

For development, install with the extra dependencies:

```sh
pip install codeforcespy[dev]
```

## Quick Start

### Asynchronous Usage

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

```python
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:

```python
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 `enable_auth=True` 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 `abc` 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](https://github.com/xscynio/codeforcespy/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](LICENSE) file for details.

---

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