| Name | speedruncompy JSON |
| Version |
0.5.0
JSON |
| download |
| home_page | None |
| Summary | A wrapper for speedrun.com's obscure new v2 API, as used by their new site |
| upload_time | 2025-01-12 03:41:24 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.11 |
| license | LGPLv2.1 |
| keywords |
speedrun
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Speedrun.com API V2 wrapper
A WIP Python wrapper for Speedrun.com's new backend API.
WIP documentation for the API can be found in [speedruncom-apiv2-docs](https://github.com/ManicJamie/speedruncom-apiv2-docs)
## Usage
`pip install speedruncompy`, then `import speedruncompy`.
Example:
```python
from speedruncompy import GetGameLeaderboard2, Verified
leaderboard = GetGameLeaderboard2(gameId="", categoryId="").perform() # Perform a single request (defaulting to page 1 where paginated)
leaderboard_full = GetGameLeaderboard2(gameId="", categoryId="").perform_all() # Perform a request for all pages available.
for run in leaderboard_full.runList:
if run.verified == Verified.VERIFIED:
print(run.description if run.description is not None else "No description!")
```
## Authorisation
Note that this uses the API in the same way as [https://speedrun.com]. The v2 API does not currently accept the Bearer token the v1 API can use - but v2 is also not half-broken, and contains most of the new features SRC has added over the years.
When working with auth, it is recommended to construct your own `SpeedrunClient` object rather than use the default:
```python
import os
from speedruncompy import SpeedrunClient, GetSession, set_default_PHPSESSID
secret = os.getenv("PHPSESSID")
# You shouldn't store PHPSESSID in the script directly, instead load it externally.
# `os.getenv()` assumes you have already set env variable PHPSESSID in your terminal;
# you can load it from a file instead using `open()` or library `load_dotenv`.
client = SpeedrunClient("my_app_name", PHPSESSID=secret)
# set_default_PHPSESSID(secret) # Would affect all calls
# that don't pass _api
session = GetSession(_api=client).perform() # Custom client given to endpoints by _api.
if session.session.signedIn:
print("I'm signed in!")
```
To authorise you must either complete a standard login flow (see [auth](./src/speedruncompy/auth.py)) or use the `PHPSESSID` of a session you logged in on browser. You can provide this object to endpoints as `_api`, and you can set `apiInstance.PHPSESSID` manually.
Note that sessions _may_ expire unexpectedly. Periodically calling `PutSessionPing` may help, but for long-lived applications you should have additional monitoring. If you need it, you may need to set up automatic login using `PutAuthLogin`, with potential email inbox monitoring for 2FA.
## Why use V2?
v1 is not actively maintained, and both misses a large number of modern features (including various social connections on user profiles) and has various issues clouding its use;
- pagination breaks at 10,000 items on all endpoints
- some endpoints are completely broken (notably run verification)
- some endpoints are in a degraded state (/leaderboards position)
However, V2 is poor for some specific tasks; since it can only fetch one category at a time, indexing all runs in a game (or site-wide) is slow. Rate limits are also less simple, undocumented & vary between endpoints.
Additionally, V2 has no promise of stability; it is use-at-your-own-risk, as it is directly tied to the data the site uses.
## Omissions
Admin-only endpoints will not be added due to lack of testability and usability. These include:
- GetUserList
- GetChallengesList
- GetAdminStatusSummary
- GetTicketQueueCounts
- GetTicketStatusCounts
- PutGameDelete - _Will be added once users can delete games again_
## Goals
Future versions will aim to assist further in development;
- Complete datatype coverage & testing to detect regressions & SRC-side additions
- Convenience properties potentially exploiting cached data?
Raw data
{
"_id": null,
"home_page": null,
"name": "speedruncompy",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "speedrun",
"author": null,
"author_email": "Jamie <jamie.on.twitch@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/a0/f4/26546c6da19931ae3999012a8abf130ed44f59525c7101f2b808e369eebe/speedruncompy-0.5.0.tar.gz",
"platform": null,
"description": "# Speedrun.com API V2 wrapper\n\nA WIP Python wrapper for Speedrun.com's new backend API.\n\nWIP documentation for the API can be found in [speedruncom-apiv2-docs](https://github.com/ManicJamie/speedruncom-apiv2-docs)\n\n## Usage\n\n`pip install speedruncompy`, then `import speedruncompy`.\n\nExample:\n\n```python\nfrom speedruncompy import GetGameLeaderboard2, Verified\n\nleaderboard = GetGameLeaderboard2(gameId=\"\", categoryId=\"\").perform() # Perform a single request (defaulting to page 1 where paginated)\nleaderboard_full = GetGameLeaderboard2(gameId=\"\", categoryId=\"\").perform_all() # Perform a request for all pages available.\n\nfor run in leaderboard_full.runList:\n if run.verified == Verified.VERIFIED:\n print(run.description if run.description is not None else \"No description!\")\n```\n\n## Authorisation\n\nNote that this uses the API in the same way as [https://speedrun.com]. The v2 API does not currently accept the Bearer token the v1 API can use - but v2 is also not half-broken, and contains most of the new features SRC has added over the years.\n\nWhen working with auth, it is recommended to construct your own `SpeedrunClient` object rather than use the default:\n\n```python\nimport os\nfrom speedruncompy import SpeedrunClient, GetSession, set_default_PHPSESSID\n\nsecret = os.getenv(\"PHPSESSID\")\n# You shouldn't store PHPSESSID in the script directly, instead load it externally.\n# `os.getenv()` assumes you have already set env variable PHPSESSID in your terminal;\n# you can load it from a file instead using `open()` or library `load_dotenv`.\n\nclient = SpeedrunClient(\"my_app_name\", PHPSESSID=secret)\n\n# set_default_PHPSESSID(secret) # Would affect all calls\n # that don't pass _api\n\nsession = GetSession(_api=client).perform() # Custom client given to endpoints by _api.\nif session.session.signedIn:\n print(\"I'm signed in!\")\n```\n\nTo authorise you must either complete a standard login flow (see [auth](./src/speedruncompy/auth.py)) or use the `PHPSESSID` of a session you logged in on browser. You can provide this object to endpoints as `_api`, and you can set `apiInstance.PHPSESSID` manually.\n\nNote that sessions _may_ expire unexpectedly. Periodically calling `PutSessionPing` may help, but for long-lived applications you should have additional monitoring. If you need it, you may need to set up automatic login using `PutAuthLogin`, with potential email inbox monitoring for 2FA.\n\n## Why use V2?\n\nv1 is not actively maintained, and both misses a large number of modern features (including various social connections on user profiles) and has various issues clouding its use;\n\n- pagination breaks at 10,000 items on all endpoints\n- some endpoints are completely broken (notably run verification)\n- some endpoints are in a degraded state (/leaderboards position)\n\nHowever, V2 is poor for some specific tasks; since it can only fetch one category at a time, indexing all runs in a game (or site-wide) is slow. Rate limits are also less simple, undocumented & vary between endpoints.\n\nAdditionally, V2 has no promise of stability; it is use-at-your-own-risk, as it is directly tied to the data the site uses.\n\n## Omissions\n\nAdmin-only endpoints will not be added due to lack of testability and usability. These include:\n\n- GetUserList\n- GetChallengesList\n- GetAdminStatusSummary\n- GetTicketQueueCounts\n- GetTicketStatusCounts\n- PutGameDelete - _Will be added once users can delete games again_\n\n## Goals\n\nFuture versions will aim to assist further in development;\n\n- Complete datatype coverage & testing to detect regressions & SRC-side additions\n- Convenience properties potentially exploiting cached data?\n",
"bugtrack_url": null,
"license": "LGPLv2.1",
"summary": "A wrapper for speedrun.com's obscure new v2 API, as used by their new site",
"version": "0.5.0",
"project_urls": {
"Bug Tracker": "https://github.com/ManicJamie/speedruncompy/issues",
"Homepage": "https://github.com/ManicJamie/speedruncompy",
"Repository": "https://github.com/ManicJamie/speedruncompy.git"
},
"split_keywords": [
"speedrun"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "679d6911d869c0f859d4592e13dc874432e8ef08096655f35848557c9bf28f94",
"md5": "104139683618ce6fb09c57bb424a1b25",
"sha256": "77d1443560a5059b96a778868ba920d3a84c2979e9d0c3abe8f73900a06875b1"
},
"downloads": -1,
"filename": "speedruncompy-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "104139683618ce6fb09c57bb424a1b25",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 43511,
"upload_time": "2025-01-12T03:41:22",
"upload_time_iso_8601": "2025-01-12T03:41:22.398179Z",
"url": "https://files.pythonhosted.org/packages/67/9d/6911d869c0f859d4592e13dc874432e8ef08096655f35848557c9bf28f94/speedruncompy-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a0f426546c6da19931ae3999012a8abf130ed44f59525c7101f2b808e369eebe",
"md5": "121bc27472bfc6133cf36153393cd48b",
"sha256": "a2d60537bebb4f0931f49c2d49150213faa55c00061536aa50297d3a5fc84c24"
},
"downloads": -1,
"filename": "speedruncompy-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "121bc27472bfc6133cf36153393cd48b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 50180,
"upload_time": "2025-01-12T03:41:24",
"upload_time_iso_8601": "2025-01-12T03:41:24.727372Z",
"url": "https://files.pythonhosted.org/packages/a0/f4/26546c6da19931ae3999012a8abf130ed44f59525c7101f2b808e369eebe/speedruncompy-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-12 03:41:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ManicJamie",
"github_project": "speedruncompy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "speedruncompy"
}
