aiosu

aiosu

|Python| |pypi| |pre-commit.ci status| |rtd| |pytest| |mypy| |codacy|

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.9 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