Getting started with osu.py

Client and AuthHandler

The simplest way to initialise the client class using client credential grant is like so.

from osu import Client

client = Client.from_credentials(client_id, client_secret, redirect_uri)

If you’re unsure of where to obtain a client id and secret, read managing oauth applications on the osu! docs.

There are also additional optional parameters that you can read about under Client.from_credentials.

The other way to initialise the Client class is directly passing an auth handler.

from osu import Client

auth = ...  # we'll get to this next

client = Client(auth)

There are similar optional parameters, which you can read about at Client.

The auth parameter for the client is an AuthHandler object. You can initialise it like so (see below). The AuthHandler.get_auth_token call is optional and will be lazily performed if using client credentials grant.

from osu import AuthHandler

auth = AuthHandler(client_id, client_secret, redirect_uri)
auth.get_auth_token()  # optional for client credentials grant

AuthHandler also has an optional parameter scope, which is a Scope object. You can read more about it at AuthHandler.

All those examples involved client credential grant, but you can also use authorization code grant. Here’s a full code example (this code is from the examples folder on the osu.py repo: auth_url.py)

from osu import Client, AuthHandler, Scope, GameModeStr
import os


client_id = int(os.getenv('osu_client_id'))
client_secret = os.getenv('osu_client_secret')
redirect_url = "http://127.0.0.1:8080"

# Usually you would redirect a user on your site
# to the authorize url with the redirect_url being back
# to your site where you can grab the code and get
# an access token.
# For this example, you are redirected to localhost with a code,
# which you can copy paste from the url
auth = AuthHandler(client_id, client_secret, redirect_url, Scope.identify())
print(auth.get_auth_url())
auth.get_auth_token(input("Code: "))  # The code is found in the redirect url (Ex. http://127.0.0.1:8080/?code=***********)
client = Client(auth)

user = client.get_own_data(GameModeStr.STANDARD)
print(user.username)

If you want to learn more about available api requests, read through the Client’s documentation or check the homepage for some specific examples.

AsynchronousClient

This class is the exact same as the Client class, but all api request functions are asynchronous and it uses AsynchronousAuthHandler. You can see it in use in the asynchronous_client.py example on the github.

Scope

The purpose of the scope class is to authorize under the desired scopes and to check the client scope against the scope required for a specific request.

You can create a Scope object in any of the ways shown below.

Scope.default()  # public
Scope.identify() # public, identify
Scope("public", "identify", "friends.read")

You can see a list of all valid scopes and their descriptions at Scope.

Getting started with osu.py

Client and AuthHandler

AsynchronousClient

Scope

Further reading