Client¶

Client is the main entry point to interacting with Geometry Dash servers using gd.py. It has many different methods which cover almost entire GD server API.

Typical usage is to create a client instance somewhere at the global scope, and then run its methods in async functions:

client = gd.Client()
song = await client.get_song(1)
# <Song id=1 name='Chilled 1' author='Recoil'>

Client instances have session objects bind to them, which allow to run methods with custom arguments, if needed. Every session object has http client object bound, that can be used for any request.

Here is more interesting client usage:

client = gd.Client()

level = await client.get_level(30029017)
# <Level id=30029017 name='VorteX' ...>

# some counters
total = 0
count = 0

# for each comment on the level, add its rating to total and increment count
for comment in await level.get_comments(amount=-1):  # all comments
    count += 1
    total += comment.rating

print('Average rating/comment on {0!r}: {1:.2f}.'.format(level.name, total/count))

Client objects also supported operations that require GD account.

Logging in with an account is fairly simple:

client = gd.Client()
await client.login('username', 'password')

Logged in Clients can like levels, post comments, send messages and friend requests, etc:

client = gd.Client()
# log in
await client.login('username', 'password')

rob = await client.find_user('RobTop')
# <AbstractUser name='RobTop' id=16 account_id=71>

for level in await rob.get_levels():
    print(level.name, level.id)
    await level.like()  # hehe

nekit = await client.fetch_user(5509312)
# <AbstractUser name='nekitdev' id=17876467 account_id=5509312>

# please do not spam me with those uwu ~ nekit
await nekit.send_friend_request('Hey there from gd.py')

bot = await client.search_user('GDBotAI')
# <User account_id=11676872 id=118270198 name='GDBotAI' ...>

# send a message
await bot.send('Ignore: gd.py', 'This is a message sent from gd.py')

Another example:

client = gd.Client()
# log in
await client.login('username', 'password')

for friend in await client.get_friends():
    print(friend.name)

You can even do this (I strongly do not recommend though):

level = await client.get_level(30029017)
# <Level id=30029017 name='VorteX' ...>

await level.upload(id=0)  # reupload a level...

Warning

If you ever need to initialize any object by hand, do not forget to attach a client:

level = gd.Level(id=30029017, client=client)

Client¶

class gd.Client(*, loop: Optional[asyncio.events.AbstractEventLoop] = None, load_after_post: bool = True, **http_args)[source]¶

A main class in the gd.py library, used for interacting with the servers of Geometry Dash.

Parameters

loop (Optional[asyncio.AbstractEventLoop]) – The asyncio.AbstractEventLoop to use for asynchronous operations. Defaults to None, in which case the default event loop is used via utils.acquire_loop().
load_after_post (bool) –
Whether to load comments/messages/requests after sending them.
Note

Defaults to True, in which case the following method calls will return objects:
Otherwise, if False or not found (extremely rarely), these methods will return None.
**http_args – Arguments to pass to HTTPClient constructor.

account_id¶

Account ID of the client. If not logged in, defaults to 0.

Type: int

id¶

ID (Player ID) of the client. If not logged in, defaults to 0.

Type: int

name¶

Name of the client. If not logged in, default is None.

Type: str

password¶

Password of the client. None if not logged in.

Type: str

encodedpass¶

Encoded Password of the client. None on init as well.

Type: str

db¶

Database/Save API. If not loaded, has empty parts inside.

Type: Optional[api.Database]

edit(**attrs) → gd.client.Client[source]¶

Update attributes given by attrs of self.

This could be used to manually set credentials, for example:

client = gd.Client()
client.edit(name='nekitdev', id=17876467, account_id=5509312, password='secret')

http¶

HTTP Client bound to that Client. Same as self.session.http.

Type: HTTPClient

is_logged() → bool [source]¶: bool: Indicates whether the Client is logged in.

await ping_server() → float [source]¶

This function is a coroutine.

Pings boomlings.com/database and returns the time taken.

Returns: Server ping, in milliseconds.
Return type: float

await get_artist_info(song_id: int = 0) → gd.song.ArtistInfo[source]¶

This function is a coroutine.

Retrieves artist info about for a song with a particular ID.

Parameters: song_id (int) – An ID of the song whose info to fetch.
Raises: MissingAccess – Failed to fetch the song info.
Returns: Info regarding the artist.
Return type: ArtistInfo

await get_song(song_id: int = 0) → gd.song.Song[source]¶

This function is a coroutine.

Fetches a song from Geometry Dash server.

Parameters

song_id (int) – An ID of the song to fetch.

Raises

MissingAccess – Song under given ID was not found or does not exist.
SongRestrictedForUsage – Song was not allowed to use.

Returns

The song from the ID.

Return type

Song

await get_ng_song(song_id: int = 0) → gd.song.Song[source]¶

This function is a coroutine.

Fetches a song from Newgrounds.

This function is in most cases might be slower than Client.get_song(), but it does not raise errors if a song is banned on GD Server.

Parameters: song_id (int) – An ID of the song to fetch.
Raises: MissingAccess – Requested song is deleted from Newgrounds or does not exist.
Returns: The song found under given ID.
Return type: Song

await search_page_songs(query: str, page: int = 0) → List[gd.song.Song][source]¶

This function is a coroutine.

Search for songs on Newgrounds.

Parameters

query (str) – Query to search for.
page (int) – Page to look songs on.

Returns

A list of Songs, containing attributes id, name and author.

Return type

List[Song]

await search_songs(query: str, pages: Iterable[int] = range(0, 10)) → List[gd.song.Song][source]¶

This function is a coroutine.

Search for songs on Newgrounds.

Parameters

query (str) – Query to search for.
pages (Iterable[int]) – Pages to look songs on.

Returns

A list of Songs, containing attributes id, name and author.

Return type

List[Song]

await search_page_users(query: str, page: int = 0) → List[gd.song.Author][source]¶

This function is a coroutine.

Search for users on Newgrounds.

Parameters

query (str) – Query to search for.
page (int) – Page to look users on.

Returns

A list of Authors, containing attributes name and link.

Return type

List[Author]

await search_users(query: str, pages: Iterable[int] = range(0, 10)) → List[gd.song.Author][source]¶

This function is a coroutine.

Search for users on Newgrounds.

Parameters

query (str) – Query to search for.
pages (Iterable[int]) – Pages to look users on.

Returns

A list of Authors, containing attributes name and link.

Return type

List[Author]

await get_page_user_songs(user: Union[str, gd.song.Author], page: int = 0) → List[gd.song.Song][source]¶

This function is a coroutine.

Search for songs by a user on Newgrounds.

Parameters

query (str) – Query to search for.
page (int) – Page to look songs on.

Returns

A list of Songs, containing attributes id, name and author.

Return type

List[Song]

await get_user_songs(user: Union[str, gd.song.Author], pages: Iterable[int] = range(0, 10)) → List[gd.song.Song][source]¶

This function is a coroutine.

Search for songs by a user on Newgrounds.

Parameters

query (str) – Query to search for.
pages (Iterable[int]) – Page to look songs on.

Returns

A list of Songs, containing attributes id, name and author.

Return type

List[Song]

await get_user(account_id: int = 0) → gd.user.User[source]¶

This function is a coroutine.

Gets a user from Geometry Dash server.

Parameters: account_id (int) – An account ID of the user to fetch.
Raises: MissingAccess – User with given account ID was not found.
Returns: The user from the ID.
Return type: User

await fetch_user(account_id: int = 0, *, stats: bool = False) → Union[gd.abstractuser.AbstractUser, gd.user.UserStats][source]¶

This function is a coroutine.

This is almost like Client.get_user(), except that it returns either UserStats or AbstractUser object.

Parameters

account_id (int) – An account ID of the user to fetch stats of.
stats (bool) – Whether to return UserStats or AbstractUser. By default returns AbstractUser.

Raises

MissingAccess – User with given account ID was not found, so fetching stats failed or user can not be returned.

Returns

Abstract user or User stats from the ID. (if ID != -1)

Return type

Union[UserStats, AbstractUser]

await search_user(query: Union[int, str]) → gd.user.User[source]¶

This function is a coroutine.

Searches for a user on Geometry Dash servers.

Parameters: query (Union[int, str]) – A query to search for user with. Either Player ID or Name.
Raises: MissingAccess – Nothing was found.
Returns: A User found when searching with the query.
Return type: Union[User]

await find_user(query: Union[int, str]) → gd.abstractuser.AbstractUser[source]¶

This function is a coroutine.

Fetches a user on Geometry Dash servers by given query.

Works almost like Client.search_user(), except the fact that it returns AbstractUser.

Parameters: query (Union[int, str]) – A query to search for user with.
Raises: MissingAccess – No user was found.
Returns: An AbstractUser corresponding to the query.
Return type: Union[AbstractUser]

await get_daily() → gd.level.Level[source]¶

This function is a coroutine.

Gets current daily level.

Raises: MissingAccess – Nothing found or invalid response was received.
Returns: Current daily level.
Return type: Level

await get_weekly() → gd.level.Level[source]¶

This function is a coroutine.

Gets current weekly demon.

Raises: MissingAccess – Nothing found or invalid response was received.
Returns: Current weekly demon.
Return type: Level

await get_level(level_id: int = 0, get_data: bool = True) → gd.level.Level[source]¶

This function is a coroutine.

Fetches a level from Geometry Dash servers.

Parameters

level_id (int) –
An ID of the level to fetch.

Note

If the given ID is n, and 0 > n >= -2, this function will search for daily/weekly levels, however, it is not recommended to use since it can cause confusion. Use Client.get_daily() and Client.get_weekly() for better understanding.
get_data (bool) – Whether to download the level data or not.

Raises

MissingAccess – Level with given ID was not found.

Returns

The level corresponding to given id.

Return type

Level

await get_many_levels(*level_ids: Sequence[int]) → List[gd.level.Level][source]¶

This function is a coroutine.

Fetches many levels.

Parameters

*level_ids (Sequence[int]) –

IDs of levels to fetch. This function returns all the levels that it is able to find.

Example:

await client.get_many_levels(30029017, 44622744)

Raises

MissingAccess – Levels were not found.

Returns

A list of all levels found.

Return type

List[Level]

await get_gauntlets() → List[gd.level_packs.Gauntlet][source]¶

This function is a coroutine.

Fetches The Lost Gauntlets.

Returns: All gauntlets retrieved, as list.
Return type: List[Gauntlet]

await get_page_map_packs(page: int = 0, *, exclude: Tuple[Type[BaseException]] = (<class 'gd.errors.NothingFound'>, )) → List[gd.level_packs.MapPack][source]¶

This function is a coroutine.

Fetches map packs on given page.

Parameters

page (int) – Page to look for map packs on.
exclude (Tuple[Type[BaseException]]) – Exceptions to ignore. By default includes only NothingFound.

Returns

List of map packs retrieved.

Return type

List[MapPack]

Raises

NothingFound – No map packs were found at the given page.

await get_map_packs(pages: Optional[Iterable[int]] = range(0, 10)) → List[gd.level_packs.MapPack][source]¶

This function is a coroutine.

Gets map packs on given pages.

Parameters: pages (Iterable[int]) – Pages to search map packs on.
Returns: List of map packs found.
Return type: List[MapPack]

await unsafe_login(user: str, password: str) → None [source]¶

This function is a coroutine.

Login into account, without validating credentials.

Parameters

user (str) – A username of the account to log into.
password (str) – A password of the account to log into.

Raises

MissingAccess – Could not find account by given user.

await login(user: str, password: str) → None [source]¶

This function is a coroutine.

Tries to login with given parameters.

Parameters

user (str) – A username of the account to log into.
password (str) – A password of the account to log into.

Raises

LoginFailure – Given account credentials are not correct.

await upload_level(name: str = 'Unnamed', id: int = 0, version: int = 1, length: Union[int, str, gd.utils.enums.LevelLength] = 0, track: int = 0, song_id: int = 0, is_auto: bool = False, original: int = 0, two_player: bool = False, objects: Optional[int] = None, coins: int = 0, star_amount: int = 0, unlisted: bool = False, friends_only: bool = False, ldm: bool = False, password: Optional[Union[int, str]] = None, copyable: bool = False, data: Union[bytes, str] = '', description: str = '', *, load: bool = True) → gd.level.Level[source]¶

This function is a coroutine.

Upload a level.

Parameters

name (str) – A name of the level.
id (int) – An ID of the level. 0 if uploading a new level, non-zero when attempting to update already existing level.
version (int) – A version of the level.
length (Union[int, str, LevelLength]) – A length of the level. See LevelLength for more info.
track (int) – A normal track to set, e.g. 0 - Stereo Madness, 1 - Back on Track, ....
song_id (int) – An ID of the custom song to set.
is_auto (bool) – Indicates if the level is auto.
original (int) – An ID of the original level.
two_player (bool) – Indicates whether the level has enabled Two Player mode.
objects (int) – The amount of objects in the level. If not provided, the amount is being calculated from the data parameter.
coins (int) – An amount of coins the level has.
star_amount (int) – The amount of stars to request.
unlisted (bool) – Indicates whether the level should be unlisted.
friends_only (bool) – Whether the level should be seen by friends only.
ldm (bool) – Indicates if the level has LDM mode.
password (Union[int, str]) – The password to apply. Either a natural number or a string representing a natural number. If None, depending on what copyable is, either indicates whether a level is free to copy or not copyable at all.
copyable (bool) – Indicates whether the level should be copyable.
data (Union[bytes, str]) – The data of the level, as a stream.
description (str) – The description of the level.
load (bool) – Indicates whether the newly uploaded level should be loaded and returned. If false, the gd.Level(id=id, client=self) is returned.

Raises

MissingAccess – Failed to upload a level.

Returns

Newly uploaded level.

Return type

Level

await get_page_levels(page: int = 0, *, exclude: Tuple[Type[BaseException]] = (<class 'gd.errors.NothingFound'>, )) → List[gd.level.Level][source]¶

This function is a coroutine.

Gets levels of a client from a server.

Note

This method requires client to be logged in.

Parameters

page (int) – Page to look levels at.
exclude (Tuple[Type[BaseException]]) – Exceptions to ignore. By default includes only NothingFound.

Returns

All levels found, as list. Might be an empty list.

Return type

List[Level]

Raises

MissingAccess – No levels were found.

await get_levels(pages: Optional[Iterable[int]] = range(0, 10)) → List[gd.level.Level][source]¶

This function is a coroutine.

Searches for levels on given pages.

Note

This method requires authorised client.

Parameters: pages (Iterable[int]) – Pages to look for levels at.
Returns: All levels found, as list, which might be empty.
Return type: List[Level]

await load() → None [source]¶

This function is a coroutine.

Loads save from a server and parses it. Sets Client.save to Save namedtuple (completed, followed).

await backup(save_data: Optional[Sequence[Union[bytes, str]]] = None) → None [source]¶

This function is a coroutine.

Back up (save) the data of the client.

Parameters: save_data (Union[bytes, str]) – Save data to backup.
Raises: MissingAccess – Failed to do a backup.

await save(save_data: Optional[Sequence[Union[bytes, str]]] = None) → None ¶

This function is a coroutine.

Back up (save) the data of the client.

Parameters: save_data (Union[bytes, str]) – Save data to backup.
Raises: MissingAccess – Failed to do a backup.

close(message: Optional[str] = None) → None [source]¶

Closes client.

Basically sets its password and username to None, which actually implies that client logs out.

Parameters: message (str) – A message to print after closing.

temp_login(user: str, password: str) → Any[source]¶

Async context manager, used for temporarily logging in.

Typical usage can be, as follows:

async with client.temp_login('Name', 'Password'):
    await client.post_comment('Hey there from gd.py!')

await like(entity: Union[gd.comment.Comment, gd.level.Level]) → None [source]¶

This function is a coroutine.

Like an entity (either a comment or a level).

Parameters: entity (Union[Comment, Level]) – An entity to like.
Raises: MissingAccess – Failed to like an entity.

await dislike(entity: Union[gd.comment.Comment, gd.level.Level]) → None [source]¶

This function is a coroutine.

Dislike an entity (either a comment or a level).

Parameters: entity (Union[Comment, Level]) – An entity to like.
Raises: MissingAccess – Failed to dislike an entity.

await delete_comment(comment: gd.comment.Comment) → None [source]¶

This function is a coroutine.

Delete a comment.

Parameters: comment (Comment) – A comment to delete.
Raises: MissingAccess – Server did not return 1, which means comment was not deleted.

await read_friend_request(request: gd.friend_request.FriendRequest) → None [source]¶

This function is a coroutine.

Read a friend request.

Parameters: request (FriendRequest) – A friend request to read.
Raises: MissingAccess – Failed to read a request.

await delete_friend_request(request: gd.friend_request.FriendRequest) → None [source]¶

This function is a coroutine.

Delete a friend request.

Parameters: request (FriendRequest) – A friend request to delete.
Raises: MissingAccess – Failed to delete a friend request.

await accept_friend_request(request: gd.friend_request.FriendRequest) → None [source]¶

This function is a coroutine.

Accept a friend request.

Parameters: request (FriendRequest) – A friend request to accept.
Raises: MissingAccess – Failed to accept a friend request.

await read_message(message: gd.message.Message) → str [source]¶

This function is a coroutine.

Read a message.

Parameters: message (Message) – A message to read.
Returns: The content of the message.
Return type: str

await delete_message(message: gd.message.Message) → None [source]¶

This function is a coroutine.

Delete a message.

Parameters: message (Message) – A message to delete.
Raises: MissingAccess – Failed to delete a message.

await send_message(user: gd.abstractuser.AbstractUser, subject: str, body: str) → Optional[gd.message.Message][source]¶

This function is a coroutine.

Send a message.

Parameters

user (AbstractUser) – User to send a message to.
subject (str) – Subject of a new message.
body (str) – Body of a new message.

Raises

MissingAccess – Failed to send a message.

Returns

Sent message.

Return type

Optional[Message]

await block(user: gd.abstractuser.AbstractUser) → None [source]¶

This function is a coroutine.

Block a user.

Parameters: user (AbstractUser) – User to block.
Raises: MissingAccess – Failed to block a user.

await unblock(user: gd.abstractuser.AbstractUser) → None [source]¶

This function is a coroutine.

Unblock a user.

Parameters: user (AbstractUser) – User to unblock.
Raises: MissingAccess – Failed to unblock a user.

await unfriend(user: gd.abstractuser.AbstractUser) → None [source]¶

This function is a coroutine.

Unfriend a user.

Parameters: user (AbstractUser) – User to unfriend.
Raises: MissingAccess – Failed to unfriend a user.

await send_friend_request(user: gd.abstractuser.AbstractUser, message: str = '') → Optional[gd.friend_request.FriendRequest][source]¶

This function is a coroutine.

Send a friend request.

Parameters

user (AbstractUser) – User to send a request to.
message (str) – Body of friend request message.

Raises

MissingAccess – Failed to send a friend request to user.

Returns

Sent friend request.

Return type

Optional[FriendRequest]

await retrieve_page_comments(user: gd.abstractuser.AbstractUser, type: str = 'profile', page: int = 0, strategy: Union[int, str, gd.utils.enums.CommentStrategy] = 0, exclude: Tuple[Type[BaseException]] = (<class 'gd.errors.NothingFound'>, )) → List[gd.comment.Comment][source]¶

This function is a coroutine.

Retrieve comments of a user.

Parameters

user (AbstractUser) – User to retrieve comments of.
type (str) – Type of comments to look for. Either profile or level.
page (int) – Page to look comments on.
exclude (Tuple[Type[BaseException]]) – Exceptions to ignore. By default includes only NothingFound.
strategy (Union[int, str, CommentStrategy]) – Strategy to use. recent or most_liked.

Returns

Retrieved comments.

Return type

List[Comment]

await retrieve_comments(user: gd.abstractuser.AbstractUser, type: str = 'profile', pages: Optional[Iterable[int]] = range(0, 10), strategy: Union[int, str, gd.utils.enums.CommentStrategy] = 0) → List[gd.comment.Comment][source]¶

This function is a coroutine.

Retrieve comments of a user.

Parameters

user (AbstractUser) – User to retrieve comments of.
type (str) – Type of comments to look for. Either profile or level.
pages (Iterable[int]) – Pages to look comments on.
strategy (Union[int, str, CommentStrategy]) – Strategy to use. recent or most_liked.

Returns

Retrieved comments.

Return type

List[Comment]

await report_level(level: gd.level.Level) → None [source]¶

This function is a coroutine.

Report a level.

Parameters: level (Level) – A level to report.
Raises: MissingAccess – Failed to report a level.

await delete_level(level: gd.level.Level) → None [source]¶

This function is a coroutine.

Delete a level.

Parameters: level (Level) – A level to delete.
Raises: MissingAccess – Failed to delete a level.

await update_level_description(level: gd.level.Level, content: str) → None [source]¶

This function is a coroutine.

Update description a level.

Parameters

level (Level) – A level to update description of.
content (str) – Content of a new description.

await rate_level(level: gd.level.Level, stars: int = 1) → None [source]¶

This function is a coroutine.

Rate a level.

Parameters

level (Level) – A level to rate.
stars (int) – Amount of stars to rate a level with.

Raises

MissingAccess – Failed to rate a level.

await rate_demon(level: gd.level.Level, demon_difficulty: Union[int, str, gd.utils.enums.DemonDifficulty] = 1, as_mod: bool = False) → None [source]¶

This function is a coroutine.

Rate a level as demon.

Parameters

level (Level) – A level to rate.
demon_difficulty (Union[int, str, DemonDifficulty]) – Demon difficulty to rate a level with.
as_mod (bool) – Whether to attempt to rate a level as moderator.

await send_level(level: gd.level.Level, stars: int = 1, featured: bool = True) → None [source]¶

This function is a coroutine.

Send a level to RobTop.

Parameters

level (Level) – A level to send.
stars (int) – Amount of stars to send a level with.
featured (bool) – Whether to send a level for feature.

Raises

MissingAccess – Missing required moderator permissions.

await comment_level(level: gd.level.Level, content: str, percentage: int = 0) → Optional[gd.comment.Comment][source]¶

This function is a coroutine.

Comment a level.

Parameters

level (Level) – A level to comment.
content (str) – Content of a comment to post.
precentage (int) – Percentage to put a comment with.

Raises

MissingAccess – Failed to post a level comment.

Returns

Sent comment.

Return type

Optional[Comment]

await get_level_leaderboard(level: gd.level.Level, strategy: Union[int, str, gd.utils.enums.LevelLeaderboardStrategy]) → List[gd.abstractuser.LevelRecord][source]¶

This function is a coroutine.

Get leaderboard of a level.

Parameters

level (Level) – A level to fetch a leaderboard of.
strategy (Union[int, str, LevelLeaderboardStrategy]) – Strategy to use when fetching a leaderboard.

Returns

Level records that were found.

Return type

List[LevelRecord]

await get_level_comments(level: gd.level.Level, strategy: Union[int, str, gd.utils.enums.CommentStrategy] = 0, amount: int = 20, exclude: Tuple[Type[BaseException]] = (<class 'gd.errors.NothingFound'>, )) → List[gd.comment.Comment][source]¶

This function is a coroutine.

Get comments of a level.

Parameters

level (Level) – A level to fetch comments of.
strategy (Union[int, str, CommentStrategy]) – Strategy to use when fetching a leaderboard.
amount (int) – Amount of comments to fetch. When lower than 0, adds 2^31 to the amount. (meaning to fetch all the comments)
exclude (Tuple[Type[BaseException]]) – Exceptions to ignore. By default includes only NothingFound.

Returns

Comments that were found.

Return type

List[Comment]

await get_blocked_users(exclude: Tuple[Type[BaseException]] = (<class 'gd.errors.NothingFound'>, )) → List[gd.abstractuser.AbstractUser][source]¶

This function is a coroutine.

Get all users blocked by a client.

Parameters

exclude (Tuple[Type[BaseException]]) – Exceptions to ignore. By default includes only NothingFound.

Returns

All blocked users retrieved, as list.

Return type

List[AbstractUser]

Raises

MissingAccess – Failed to fetch blocked users of a client.
NothingFound – No blocked users were found. Cool.

await get_friends(exclude: Tuple[Type[BaseException]] = (<class 'gd.errors.NothingFound'>, )) → List[gd.abstractuser.AbstractUser][source]¶

This function is a coroutine.

Get all friends of a client.

Parameters

exclude (Tuple[Type[BaseException]]) – Exceptions to ignore. By default includes only NothingFound.

Returns

All friends retrieved, as list.

Return type

List[AbstractUser]

Raises

MissingAccess – Failed to fetch friends of a client.
NothingFound – No friends were found. Sadly…

await to_user() → gd.user.User[source]¶

This function is a coroutine.

Gets user with Client.account_id, which means that client should be logged in.

Returns: User corresponding to Client.account_id.
Return type: User

await get_page_messages(sent_or_inbox: str = 'inbox', page: int = 0, *, exclude: Tuple[Type[BaseException]] = (<class 'gd.errors.NothingFound'>, )) → List[gd.message.Message][source]¶

This function is a coroutine.

Gets messages on a specified page.

Requires logged in client.

Parameters

sent_or_inbox (str) – The type of messages to look for. Either inbox or sent.
page (int) – Number of page to look at.
exclude (Tuple[Type[BaseException]]) – Exceptions to ignore. By default includes only NothingFound.

Returns

List of messages found. Can be empty.

Return type

List[Message]

Raises

MissingAccess – Failed to get messages.
NothingFound – No messages were found.

await get_messages(sent_or_inbox: str = 'inbox', pages: Optional[Iterable[int]] = range(0, 10)) → List[gd.message.Message][source]¶

This function is a coroutine.

Retrieves messages from given pages.

Parameters

sent_or_inbox (str) – Type of messages to retrieve. Either ‘sent’ or ‘inbox’. Defaults to the latter.
pages (Iterable[int]) – Pages to look at, represented as a finite sequence, so iterations can be performed.

Returns

List of messages found. Can be an empty list.

Return type

List[Message]

await get_page_friend_requests(sent_or_inbox: str = 'inbox', page: int = 0, *, exclude: Tuple[Type[BaseException]] = (<class 'gd.errors.NothingFound'>, )) → List[gd.friend_request.FriendRequest][source]¶

This function is a coroutine.

Gets friend requests on a specified page.

Requires logged in client.

Parameters

sent_or_inbox (str) – The type of friend requests to look for. Either inbox or sent.
page (int) – Number of page to look at.
exclude (Tuple[Type[BaseException]]) – Exceptions to ignore. By default includes only NothingFound.

Returns

List of friend requests found. Can be empty.

Return type

List[FriendRequest]

Raises

MissingAccess – Failed to get friend requests.
NothingFound – No friend requests were found.

await get_friend_requests(sent_or_inbox: str = 'inbox', pages: Optional[Iterable[int]] = range(0, 10)) → List[gd.friend_request.FriendRequest][source]¶

This function is a coroutine.

Retrieves friend requests from given pages.

Parameters

sent_or_inbox (str) – Type of friend requests to retrieve. Either ‘sent’ or ‘inbox’. Defaults to the latter.
pages (Iterable[int]) – Pages to look at, represented as a finite sequence, so iterations can be performed.

Returns

List of friend requests found. Can be an empty list.

Return type

List[FriendRequests]

await get_top(strategy: Union[int, str, gd.utils.enums.LeaderboardStrategy] = 0, *, count: int = 100) → List[gd.user.UserStats][source]¶

This function is a coroutine.

Fetches user top by given strategy.

Example:

# getting top 10 creators
top10_creators = await client.get_top('creators', count=10)

Note

Players Top 100 has stopped refreshing in 2.1 version of Geometry Dash. However, you can fetch it by searching using 'relative' strategy and giving huge count argument.

Also, please note that searching with 'friends' and 'relative' strategies requires logged in client.

Parameters: strategy (Union[int, str, LeaderboardStrategy]) – Strategy to apply when searching.
Returns
Return type: List[UserStats]

await get_leaderboard(strategy: Union[int, str, gd.utils.enums.LeaderboardStrategy] = 0, *, count: int = 100) → List[gd.user.UserStats][source]¶

This function is a coroutine.

This is an alias for Client.get_top().

await post_comment(content: str) → Optional[gd.comment.Comment][source]¶

This function is a coroutine.

Post a profile comment.

Parameters: content (str) – The content of a comment.
Raises: MissingAccess – Failed to post a comment.
Returns: Posted comment.
Return type: Optional[Comment]

await update_profile(stars: Optional[int] = None, demons: Optional[int] = None, diamonds: Optional[int] = None, has_glow: Optional[bool] = None, icon_type: Optional[Union[int, str, gd.utils.enums.IconType]] = None, icon: Optional[int] = None, color_1: Optional[int] = None, color_2: Optional[int] = None, coins: Optional[int] = None, user_coins: Optional[int] = None, cube: Optional[int] = None, ship: Optional[int] = None, ball: Optional[int] = None, ufo: Optional[int] = None, wave: Optional[int] = None, robot: Optional[int] = None, spider: Optional[int] = None, explosion: Optional[int] = None, special: int = 0, set_as_user: Optional[gd.user.User] = None) → None [source]¶

This function is a coroutine.

Updates the profile of a client.

Note

gd.py developers are not responsible for any effects that calling this function may cause. Use this method on your own risk.

Parameters

stars (int) – An amount of stars to set.
demons (int) – An amount of completed demons to set.
diamonds (int) – An amount of diamonds to set.
has_glow (bool) – Indicates whether a user should have the glow outline.
icon_type (int) – Icon type that should be used. See IconType for info.
icon (int) – Icon ID that should be used.
color_1 (int) – Index of a color to use as the main color.
color_2 (int) – Index of a color to use as the secodary color.
coins (int) – An amount of secret coins to set.
user_coins (int) – An amount of user coins to set.
cube (int) – An index of a cube icon to apply.
ship (int) – An index of a ship icon to apply.
ball (int) – An index of a ball icon to apply.
ufo (int) – An index of a ufo icon to apply.
wave (int) – An index of a wave icon to apply.
robot (int) – An index of a robot icon to apply.
spider (int) – An index of a spider icon to apply.
explosion (int) – An index of a explosion to apply.
special (int) – The purpose of this parameter is unknown.
set_as_user (User) – Passing this parameter allows to copy user’s profile.

await update_settings(*, message_policy: Optional[Union[int, str, gd.utils.enums.MessagePolicyType]] = None, friend_request_policy: Optional[Union[int, str, gd.utils.enums.FriendRequestPolicyType]] = None, comment_policy: Optional[Union[int, str, gd.utils.enums.CommentPolicyType]] = None, youtube: Optional[str] = None, twitter: Optional[str] = None, twitch: Optional[str] = None) → None [source]¶

This function is a coroutine.

Updates profile settings of a client.

Note

For parameter in parameters, if parameter is None or omitted, it will be set to the current policy/link of the user corresponding to this client; that implies that running the following:

await client.update_settings()

will cause no effect on profile settings.

Parameters

message_policy (Union[int, str, MessagePolicyType]) – New message policy.
friend_request_policy (Union[int, str, FriendRequestPolicyType]) – New friend request policy.
comment_policy (Union[int, str, CommentPolicyType]) – New comment history policy.
youtube (str) – New youtube channel string. (not link)
twitter (str) – New twitter profile name.
twitch (str) – New twitch profile name.

Raises

MissingAccess – Failed to update profile.

await get_quests() → List[gd.rewards.Quest][source]¶

This function is a coroutine.

Get quests of a user.

Returns: Quests of a user.
Return type: List[Quest]

await get_chests(reward_type: Union[int, str, gd.utils.enums.RewardType] = 0) → List[gd.rewards.Chest][source]¶

This function is a coroutine.

Get chests of a user.

Parameters: reward_type (Union[int, str, RewardType]) – Reward type. If given and non-zero, “opens” a chest.
Returns: Chests of a user.
Return type: List[Chest]

await search_levels_on_page(page: int = 0, query: Union[str, int] = '', filters: Optional[gd.utils.filters.Filters] = None, user: Optional[Union[int, gd.abstractuser.AbstractUser]] = None, gauntlet: Optional[Union[gd.level_packs.Gauntlet, int]] = None, *, exclude: Tuple[Type[BaseException]] = (<class 'gd.errors.NothingFound'>, )) → List[gd.level.Level][source]¶

This function is a coroutine.

Searches levels on given page by given query, applying filters as well.

Parameters

page (int) – A page to search levels on.
query (Union[str, int]) – A query to search with.
filters (Filters) – Filters to apply, as an object.
user (Union[int, AbstractUser]) – A user to search levels by. (if Filters has parameter strategy equal to SearchStrategy BY_USER. Can be omitted, then logged in client is required.)
gauntlet (Union[int, Gauntlet]) – A gauntlet to get levels in.
exclude (Tuple[Type[BaseException]]) – Exceptions to ignore. By default includes only NothingFound.

Returns

Levels found on given page.

Return type

List[Level]

await search_levels(query: Union[str, int] = '', filters: Optional[gd.utils.filters.Filters] = None, user: Optional[Union[int, gd.abstractuser.AbstractUser]] = None, gauntlet: Optional[Union[gd.level_packs.Gauntlet, int]] = None, pages: Optional[Iterable[int]] = range(0, 10)) → List[gd.level.Level][source]¶

This function is a coroutine.

Searches levels on given pages.

Parameters

query (Union[str,:class:int]) – A query to search with.
filters (Filters) – Filters to apply, as an object.
user (Union[int, AbstractUser]) – A user to search levels by. (if Filters has parameter strategy equal to SearchStrategy BY_USER. Can be omitted, then logged in client is required.)
pages (Iterable[int]) – Pages to look at, represented as a finite sequence, so iterations can be performed.

Returns

List of levels found. Can be an empty list.

Return type

List[Level]

await on_new_daily(level: gd.level.Level) → Any[source]¶

This function is a coroutine.

This is an event that is fired when a new daily level is set.

See Event Reference for more info.

await on_new_weekly(level: gd.level.Level) → Any[source]¶

This function is a coroutine.

This is an event that is fired when a new weekly demon is assigned.

See Event Reference for more info.

await on_level_rated(level: gd.level.Level) → Any[source]¶

This function is a coroutine.

This is an event that is fired when a new level is rated.

See Event Reference for more info.

await on_level_unrated(level: gd.level.Level) → Any[source]¶

This function is a coroutine.

This is an event that is fired when a level is unrated.

See Event Reference for more info.

await on_message(message: gd.message.Message) → Any[source]¶

This function is a coroutine.

This is an event that is fired when a logged in client gets a message.

See Event Reference for more info.

await on_friend_request(friend_request: gd.friend_request.FriendRequest) → Any[source]¶

This function is a coroutine.

This is an event that is fired when a logged in client gets a friend request.

See Event Reference for more info.

await on_level_comment(level: gd.level.Level, comment: gd.comment.Comment) → Any[source]¶

This function is a coroutine.

This is an event that is fired when a comment is posted on some level.

See Event Reference for more info.

listen_for(type: str, entity_id: Optional[int] = None, delay: Optional[float] = None) → None [source]¶

Function for enabling listeners of events.

client.listen_for("daily")

@client.event
async def on_new_daily(level: gd.Level) -> None:
    print(f"New daily: {level.name} (ID: {level.id}).")

See Event Reference for more info.

await dispatch(event_name: str, *args, **kwargs) → Any[source]¶

This function is a coroutine.

Dispatch an event given by event_name with *args and **kwargs.

Parameters

event_name (str) – Name of event to dispatch, e.g. "new_daily".
*args – Args to call handler with.
**kwargs – Keyword args to call handler with.

Returns

Whatever handler returns.

Return type

Any

run(coro: Coroutine, *, debug: bool = False) → Any[source]¶

A handy shortcut for utils.run().

This is equivalent to:

gd.utils.run(coro, loop=self.loop, debug=debug)

event(coro: Coroutine) → Coroutine[source]¶

A decorator that registers an event to listen to.

Events must be a coroutine, if not, TypeError is raised.

Example

@client.event
async def on_level_rated(level):
    print(level.name)

Raises: TypeError – The coroutine passed is not actually a coroutine.