Skip to content


Phillip is an event driven osu! feed for Python. It is written on top of asyncio.


  • Asyncronous
  • Event-driven API
  • Easy to use
  • Rate limited to not get you IP banned from peppy's server


  • Python 3.6+


  • pyee - To fire events into handlers.
  • beautifulsoup4 - HTML parsing from osu! site.
  • aiohttp - Asyncronously requests data from osu! site.
  • asyncio-throttle - Rate limiting for web scraper.


$ git clone
$ cd Phillip
$ python -m pip install .

PyPI release is planned.


Discord Webhook

from phillip.application import Phillip
p = Phillip(
    "0c38a********************", # osu! API token
    webhook_url="************" # Discord webhook URL

Advanced Usage

This section will give you an example of using custom Handler to handle beatmap events

from phillip.application import Phillip
from phillip.discord import gen_embed
from phillip.handlers import Handler
import aiohttp

# Always inherit Handler class!
# It has some magic functions to register the event emitter so that listening function could work.
class HandleMap(Handler):
    # Function to handle every beatmap event.
    # To see other event handler you can add, see
    async def on_map_event(self, event):
        # Generate webhook dict of the event. This will be converted to JSON later.
        embed = await gen_embed(event,

        # Send webhook with aiohttp.
        # It is better to use aiohttp as it's already embedded when you install notAiess.
        with aiohttp.ClientSession() as session:
            await, json={
                'content': event.event_source_url,
                'embeds': [embed]

p = Phillip(