Ratelimits and Retries

By default, when the library gets ratelimited, it will sleep for the duration required and then retry sending the request. This behavior covers most cases as the library will only sleep for about 60 seconds or less. However this is not always desirable and as such the library also provides you with the ability to decide when you want to sleep and when you want the library to raise the error through the Client.ratelimit_max_sleep parameter. By default this parameter is set to infinity which means that the library will always sleep the full duration. Be warned, if you are doing some heavy work using POST requests this could make you sleep for large durations like one hour. If you want finer control, you can pass an int representing the maximum number of seconds to sleep. Passing 0 will mean the libary will never sleep and always raise the error.

When letting the library raise the error, you can handle the rateliming yourself using the Client.retry_after attribute to know how long you should wait before trying the request again. Some quick exmaples to make everything clear:

• ratelimit_max_sleep is 60 and you’re ratelimited with retry_after being 60 -> library sleeps for 60 seconds
• ratelimit_max_sleep is 60 and you’re ratelimited with retry_after being 3600 -> library raises the error
• ratelimit_max_sleep is infinity and you’re ratelimited with retry_after being 60 -> library sleeps for 60 seconds
• ratelimit_max_sleep is 0 and you’re ratelimited with retry_after being 3600 -> library raises the error
• ratelimit_max_sleep is 3600 and you’re ratelimited with retry_after being 3600 -> library sleeps for 3600 seconds

Client

The Client object is the base class from which all the requests are made, this is where you can get your games, authentify and get the models for your authenticated user.

class modio.client.Client(*, api_key=None, access_token=None, lang='en', version='v1', test=False, platform=None, portal=None, ratelimit_max_sleep=inf)

Represents an authenticated client to make requests to the mod.io API with. If you desire to make aysnc requests you must call Client.start before making any async request.

Parameters:

• api_key (Optional[str]) – The api key that will be used to authenticate the bot while it makes most of its GET requests. This can be generated on the mod.io website. Optional if an access token is supplied.
• access_token (Optional[str]) – The OAuth 2 token that will be used to make more complex GET requests and to make POST requests. This can either be generated using the library’s oauth2 functions or through the mod.io website. This is referred as an access token in the rest of the documentation. If an access token is supplied it will be used for all requests.
• lang (Optional[str]) – The mod.io API provides localization for a collection of languages. To specify responses from the API to be in a particular language, simply provide the lang parameter with an ISO 639 compliant language code. Default is US English.
• test (Optional[bool]) – Whether or not to use the mod.io test environment. If not included will default to False.
• version (Optional[str]) – An optional keyword argument to allow you to pick a specific version of the API to query, usually you shouldn’t need to change this. Default is the latest supported version.
• platform (Optiona[TargetPlatform]) – The platform to target with requests.
• portal (Optional[TargetPortal]) – The portal to target with requests.
• ratelimit_max_sleep (Optiona[int]) – The maximum amount of time the library will sleep in the case of a ratelimit. If the ratelimit header returned dictates a longer sleep than that value then the library will instead raise the ratelimit. If it is less then the library will sleep for the duration required before retrying the request once.

retry_after

Number of seconds until the rate limits are reset for this API Key/access token. Is 0 until the API returns a 429.

Type:int

rate_limit

rate_remain

retry_after

set_platform(platform: Optional[modio.enums.TargetPlatform] = None) → None

Change the platform targetted by the client. Call without an argument to not target any specific paltform.

Parameters:platform (Optional[TargetPlatform]) – The platform to set

set_portal(portal: Optional[modio.enums.TargetPortal] = None) → None

Change the portal targetted by the client. Call without an argument to not target any specific portal.

Parameters:portal (Optional[TargetPortal]) – The portal to set

get_game(game_id: int) → modio.game.Game

Queries the mod.io API for the given game ID and if found returns it as a Game instance. If not found raises NotFound.

This method has an async equivalent prefixed with ‘async_’. You must use Client.start before using the async equivalent.

Parameters:game_id (int) – The ID of the game to query the API for Raises:NotFound – A game with the supplied id was not found. Returns:The game with the given ID Return type:Game

get_games(*, filters: modio.objects.Filter = None) → modio.objects.Returned[modio.game.Game][modio.game.Game]

Gets all the games available on mod.io. Returns a named tuple with parameters results and pagination. This method takes filtering arguments

This method has an async equivalent prefixed with ‘async_’. You must use Client.start before using the async equivalent.

Parameters:filters (Optional[Filter]) – A instance of Filter to be used for filtering, paginating and sorting results Returns:The results and pagination tuple from this request Return type:Returned[List[Game], Pagination]

get_my_user() → modio.entities.User

Gets the authenticated user’s details (aka the user who created the API key/access token)

This method has an async equivalent prefixed with ‘async_’. You must use Client.start before using the async equivalent.

Raises:Forbidden – The access token is invalid/missing Returns:The authenticated user Return type:User

get_my_subs(*, filters: modio.objects.Filter = None) → modio.objects.Returned[modio.mod.Mod][modio.mod.Mod]

Gets all the mods the authenticated user is subscribed to. This method takes filtering arguments

This method has an async equivalent prefixed with ‘async_’. You must use Client.start before using the async equivalent.

Parameters:filter (Optional[Filter]) – A instance of Filter to be used for filtering, paginating and sorting results Raises:Forbidden – The access token is invalid/missing Returns:The results and pagination tuple from this request Return type:Returned[List[Mod], Pagination]

get_my_events(*, filters: modio.objects.Filter = None) → modio.objects.Returned[modio.entities.Event][modio.entities.Event]

Get events that have been fired specifically for the authenticated user. This method takes filtering arguments

This method has an async equivalent prefixed with ‘async_’. You must use Client.start before using the async equivalent.

Parameters:filter (Optional[Filter]) – A instance of Filter to be used for filtering, paginating and sorting results Returns:The results and pagination tuple from this request Return type:Returned[List[Event], Pagination]

get_my_games(filters: modio.objects.Filter = None) → modio.objects.Returned[modio.game.Game][modio.game.Game]

Get all the games the authenticated user added or is a team member of. This method takes filtering arguments

This method has an async equivalent prefixed with ‘async_’. You must use Client.start before using the async equivalent.

Parameters:filter (Optional[Filter]) – A instance of Filter to be used for filtering, paginating and sorting results Raises:Forbidden – The access token is invalid/missing Returns:The results and pagination tuple from this request Return type:Returned[List[Game], Pagination]

get_my_mods(*, filters: modio.objects.Filter = None) → modio.objects.Returned[modio.mod.Mod][modio.mod.Mod]

Get all the mods the authenticated user added or is a team member of. This method takes filtering arguments

This method has an async equivalent prefixed with ‘async_’. You must use Client.start before using the async equivalent.

Parameters:filter (Optional[Filter]) – A instance of Filter to be used for filtering, paginating and sorting results Raises:Forbidden – The access token is invalid/missing Returns:The results and pagination tuple from this request Return type:Returned[List[Mod], Pagination]

get_my_modfiles(*, filters: modio.objects.Filter = None) → modio.objects.Returned[modio.entities.ModFile][modio.entities.ModFile]

Get all the mods the authenticated user uploaded. The returned modfile objects cannot be edited or deleted and do not have a game_id attribute. Returns a named tuple with parameters results and pagination. This method takes filtering arguments

This method has an async equivalent prefixed with ‘async_’. You must use Client.start before using the async equivalent.

Parameters:filter (Optional[Filter]) – A instance of Filter to be used for filtering, paginating and sorting results Raises:Forbidden – The access token is invalid/missing Returns:The results and pagination tuple from this request Return type:Returned[List[ModFile], Pagination]

get_my_ratings(*, filters: modio.objects.Filter = None) → modio.objects.Returned[modio.entities.Rating][modio.entities.Rating]

Get all the ratings the authentitated user has submitted. Returns a named with parameter results and pagination. This method takes filtering arguments

This method has an async equivalent prefixed with ‘async_’. You must use Client.start before using the async equivalent.

Parameters:filter (Optional[Filter]) – A instance of Filter to be used for filtering, paginating and sorting results Raises:Forbidden – The access token is invalid/missing Returns:The results and pagination tuple from this request Return type:Returned[List[Rating], Pagination]

async_email_exchange(code: int, *, date_expires: datetime.datetime = None) → str

async_email_request(email: str)

async_get_game(game_id: int) → modio.game.Game

async_get_games(*, filters: modio.objects.Filter = None) → modio.objects.Returned[modio.game.Game][modio.game.Game]

async_get_my_events(*, filters: modio.objects.Filter = None) → modio.objects.Returned[modio.entities.Event][modio.entities.Event]

async_get_my_games(filters: modio.objects.Filter = None) → modio.objects.Returned[modio.game.Game][modio.game.Game]

async_get_my_modfiles(*, filters: modio.objects.Filter = None) → modio.objects.Returned[modio.entities.ModFile][modio.entities.ModFile]

async_get_my_mods(*, filters: modio.objects.Filter = None) → modio.objects.Returned[modio.mod.Mod][modio.mod.Mod]

async_get_my_mutes(*, filters: modio.objects.Filter = None) → modio.objects.Returned[modio.entities.User][modio.entities.User]

async_get_my_ratings(*, filters: modio.objects.Filter = None) → modio.objects.Returned[modio.entities.Rating][modio.entities.Rating]

async_get_my_subs(*, filters: modio.objects.Filter = None) → modio.objects.Returned[modio.mod.Mod][modio.mod.Mod]

async_get_my_user() → modio.entities.User

close()

This method has no sync equivalent. You must use Client.start before using this method This function is used to clean up the client in order to close the application that it uses gracefully. At the moment it is only used to close the client’s Session.

This method has an async equivalent prefixed with ‘async_’. You must use Client.start before using the async equivalent.

start()

This method has no sync equivalent. You must use Client.start before using this method This function is used to start up the async part of the client. This is required to avoid sync users from having to clean up stuff.

This method has an async equivalent prefixed with ‘async_’. You must use Client.start before using the async equivalent.

get_my_mutes(*, filters: modio.objects.Filter = None) → modio.objects.Returned[modio.entities.User][modio.entities.User]

Get all users muted by this user

This method has an async equivalent prefixed with ‘async_’. You must use Client.start before using the async equivalent.

Parameters:filter (Optional[Filter]) – A instance of Filter to be used for filtering, paginating and sorting results Raises:Forbidden – The access token is invalid/missing Returns:The results and pagination tuple from this request Return type:Returned[List[User], Pagination]

email_request(email: str)

Posts an email request for an OAuth2 token. A code will be sent to the given email address which can then be entered into email_exchange().

This method has an async equivalent prefixed with ‘async_’. You must use Client.start before using the async equivalent.

Parameters:email (str) – A valid email to which the 5-digit code will be sent

email_exchange(code: int, *, date_expires: datetime.datetime = None) → str

Exchanges the given 5-digit code for an OAuth2 token.

This method has an async equivalent prefixed with ‘async_’. You must use Client.start before using the async equivalent.

Parameters:

• code (int) – A 5-digit code received by email less than 15 minutes ago
• date_expires (Optional[datetime.datetime]) – Datetime of when the token will expire. By default this is a year, value cannot be greater than a year.

Raises:

• Unauthorized – Invalid security code
• ValueError – Security code was not 5 digits long

Returns:

The access code.

Return type:

str