Skip to content

Commit

Permalink
README changes
Browse files Browse the repository at this point in the history
  • Loading branch information
ManicJamie committed May 25, 2024
1 parent abbbac6 commit 5f735af
Showing 1 changed file with 13 additions and 3 deletions.
16 changes: 13 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,13 @@ 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`.

`speedruncompy.endpoints` contains all endpoints, and currently includes `datatypes`, `enums` & `responses`. Login flow in `speedruncompy.auth`. Other notable fields include `enums` and `exceptions`.

Example:

```python
from speedruncompy.endpoints import GetGameLeaderboard2
from speedruncompy.enums import Verified
Expand All @@ -23,9 +25,11 @@ for run in leaderboard_full.runList:
```

## 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.

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 `SpeedrunComPy` object rather than use the default:

```python
from speedruncompy.endpoints import GetGameLeaderboard2
from speedruncompy.api import SpeedrunComPy
Expand All @@ -47,21 +51,27 @@ To authorise you must either complete a standard login flow (see [auth](./src/sp
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.

## Omissions

Admin-only endpoints will not be added due to lack of testability and usability. These include:

- GetAdminStatusSummary
- GetTicketQueueCounts
- GetTicketStatusCounts
- PutGameDelete
- 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?
- Convenience properties potentially exploiting cached data?

0 comments on commit 5f735af

Please sign in to comment.