aiosu

Simple and fast asynchronous osu! API v1 and v2 library with various utilities.

Features

Support for modern async syntax (async with)
Support for API v1 and API v2
Rate limit handling
Utilities for osu! related calculations
Easy to use

Installing

Python 3.10 or higher is required

To install the library, simply run the following commands

.. code:: sh

# Linux/macOS
python3 -m pip install -U aiosu

# Windows
py -3 -m pip install -U aiosu

To install the development version, do the following:

.. code:: sh

$ git clone https://github.com/NiceAesth/aiosu
$ cd aiosu
$ python3 -m pip install -U .

API v1 Example

.. code:: py

import aiosu import asyncio

async def main(): # async with syntax async with aiosu.v1.Client("osu api token") as client: user = await client.get_user(7782553)

   # regular syntax
   client = aiosu.v1.Client("osu api token")
   user = await client.get_user(7782553)
   await client.aclose()

if name == "main": asyncio.run(main())

API v2 Example

.. code:: py

import aiosu
import asyncio
import datetime


async def main():
    token = aiosu.models.OAuthToken.model_validate(json_token_from_api)

    # or

    token = aiosu.models.OAuthToken(
        access_token="access token",
        refresh_token="refresh token",
        expires_on=datetime.datetime.utcnow()
        + datetime.timedelta(days=1),  # can also be string
    )

    # async with syntax
    async with aiosu.v2.Client(
        client_secret="secret", client_id=1000, token=token
    ) as client:
        user = await client.get_me()

    # regular syntax
    client = aiosu.v2.Client(client_secret="secret", client_id=1000, token=token)
    user = await client.get_me()
    await client.aclose()


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

You can find more examples in the examples directory.

Contributing

Please read the CONTRIBUTING.rst <.github/CONTRIBUTING.rst>__ to learn how to contribute to aiosu!

Acknowledgments

discord.py <https://github.com/Rapptz/discord.py>__ for README formatting
osu!Akatsuki <https://github.com/osuAkatsuki/performance-calculator>__ for performance and accuracy utils

.. |Python| image:: https://img.shields.io/pypi/pyversions/aiosu.svg :target: https://pypi.python.org/pypi/aiosu :alt: Python version info .. |pypi| image:: https://img.shields.io/pypi/v/aiosu.svg :target: https://pypi.python.org/pypi/aiosu :alt: PyPI version info .. |pre-commit.ci status| image:: https://results.pre-commit.ci/badge/github/NiceAesth/aiosu/master.svg :target: https://results.pre-commit.ci/latest/github/NiceAesth/aiosu/master :alt: pre-commit.ci status .. |pytest| image:: https://github.com/NiceAesth/aiosu/actions/workflows/pytest.yml/badge.svg :target: https://github.com/NiceAesth/aiosu/actions/workflows/pytest.yml :alt: pytest Status .. |mypy| image:: https://github.com/NiceAesth/aiosu/actions/workflows/mypy.yml/badge.svg :target: https://github.com/NiceAesth/aiosu/actions/workflows/mypy.yml :alt: mypy Status .. |rtd| image:: https://readthedocs.org/projects/aiosu/badge/?version=latest :target: https://aiosu.readthedocs.io/en/latest/?badge=latest :alt: Documentation Status .. |codacy| image:: https://app.codacy.com/project/badge/Grade/9bf211d7e29546dc99cc0b1a3d89b291 :target: https://app.codacy.com/gh/NiceAesth/aiosu/dashboard?utm_source=github.com&utm_medium=referral&utm_content=NiceAesth/aiosu&utm_campaign=Badge_Grade :alt: Codacy Status

Aiosu

Install / Use

README