https://github.com/lekuruu/osu.py
A python library that emulates the osu! stable client
https://github.com/lekuruu/osu.py
bancho banchopy osu osugame python
Last synced: 5 months ago
JSON representation
A python library that emulates the osu! stable client
- Host: GitHub
- URL: https://github.com/lekuruu/osu.py
- Owner: Lekuruu
- License: mit
- Created: 2023-04-05T08:26:43.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-04-19T20:09:29.000Z (6 months ago)
- Last Synced: 2025-04-24T05:55:47.841Z (5 months ago)
- Topics: bancho, banchopy, osu, osugame, python
- Language: Python
- Homepage:
- Size: 272 KB
- Stars: 10
- Watchers: 1
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# osu.py
[](https://www.python.org/downloads/)
[](https://github.com/Lekuruu/osu.py/blob/main/LICENSE)
osu.py is a python library that emulates part of the online functionality of the osu! stable client.
**IMPORTANT:**
Use this library at your own risk! I am not responsible for any unexpected behavior of the client or anything that can happen to your account. If you want to test it out on a custom server, you can set the `server` attribute when initializing the client.
You can install this package with pip:
```shell
pip install osu
```
Or build it manually:
```shell
git clone https://github.com/Lekuruu/osu.py.git
cd osu.py
pip install setuptools
python setup.py install
```
## Features
- [x] Receiving player stats
- [x] Sending/Receiving chat messages
- [x] Spectating
- [x] Avatars
- [x] Comments
- [x] Replays
- [x] Scores/Leaderboards
- [x] Tournament client behaviour
- [x] Direct Search
- [x] Direct Download
- [ ] Multiplayer
- [ ] Documentation
## Example
Here is a small example of how to use this package:
```python
from osu.bancho.constants import ServerPackets
from osu.objects import Player
from osu import Game
import logging
# Enable extended logging
logging.basicConfig(
level=logging.INFO,
format='[%(asctime)s] - <%(name)s> %(levelname)s: %(message)s'
)
# Initialize the game class
game = Game(
USERNAME,
PASSWORD
)
# Simple message handler
@game.events.register(ServerPackets.SEND_MESSAGE)
def on_message(sender: Player, message: str, target: Player):
if message.startswith('?ping'):
sender.send_message('pong!')
# Run the game
game.run()
```
You can also run tasks, independent of server actions:
```python
# Example of a task, running every minute
@game.tasks.register(minutes=1, loop=True)
def example_task():
...
```
For a more in-depth example, please view [this project](https://github.com/lekuruu/osu-recorder).
---
If you have any questions, feel free to contact me on discord: `lekuru`