https://github.com/niceaesth/aiosu
Simple and fast asynchronous osu! API v1 and v2 library
https://github.com/niceaesth/aiosu
async osu osu-api osu-api-v1 osu-api-v2 osu-libraries osu-web osugame python3
Last synced: 15 days ago
JSON representation
Simple and fast asynchronous osu! API v1 and v2 library
- Host: GitHub
- URL: https://github.com/niceaesth/aiosu
- Owner: NiceAesth
- License: gpl-3.0
- Created: 2022-09-03T20:04:31.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2025-05-05T18:59:20.000Z (17 days ago)
- Last Synced: 2025-05-07T23:13:35.971Z (15 days ago)
- Topics: async, osu, osu-api, osu-api-v1, osu-api-v2, osu-libraries, osu-web, osugame, python3
- Language: Python
- Homepage: https://aiosu.readthedocs.io
- Size: 3.88 MB
- Stars: 16
- Watchers: 1
- Forks: 3
- Open Issues: 15
-
Metadata Files:
- Readme: README.rst
- Contributing: .github/CONTRIBUTING.rst
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Security: .github/SECURITY.rst
Awesome Lists containing this project
README
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 `__
for README formatting
- `osu!Akatsuki `__
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