79 lines
2.4 KiB
Markdown
79 lines
2.4 KiB
Markdown
|
# BeatLeaderAPI Python Wrapper
|
||
|
|
|
||
|
|
This Python class provides a convenient wrapper for interacting with the BeatLeader API, specifically for retrieving player scores and song data for the game Beat Saber.
|
||
|
|
|
||
|
|
## Features
|
||
|
|
|
||
|
|
- Fetch player scores and song data from the BeatLeader API
|
||
|
|
- Local caching of API responses to reduce API calls and improve performance
|
||
|
|
- Automatic pagination handling to retrieve all available data
|
||
|
|
- Configurable cache expiration
|
||
|
|
- Methods to retrieve both full and minimal song data
|
||
|
|
|
||
|
|
## Usage
|
||
|
|
|
||
|
|
### Basic Usage
|
||
|
|
|
||
|
|
```python
|
||
|
|
from saberlist.beatleaderAPI import BeatLeaderAPI
|
||
|
|
|
||
|
|
# Initialize the API wrapper
|
||
|
|
api = BeatLeaderAPI(cache_expiry_days=1)
|
||
|
|
|
||
|
|
# Fetch player scores
|
||
|
|
player_id = '76561199407393962'
|
||
|
|
scores = api.get_player_scores(player_id)
|
||
|
|
|
||
|
|
# Get full song data
|
||
|
|
songs = api.get_player_songs(player_id)
|
||
|
|
|
||
|
|
# Get minimal song data
|
||
|
|
minimal_songs = api.get_player_songs_minimal(player_id)
|
||
|
|
```
|
||
|
|
|
||
|
|
### Caching
|
||
|
|
|
||
|
|
The class uses a local cache to store API responses. By default, the cache is located at:
|
||
|
|
|
||
|
|
- `~/.cache/saberlist/` on Unix-like systems (if `~/.cache/` exists)
|
||
|
|
- `./.cache/` in the current working directory (as a fallback)
|
||
|
|
|
||
|
|
You can control cache behavior:
|
||
|
|
|
||
|
|
```python
|
||
|
|
# Set cache expiry (in days)
|
||
|
|
api = BeatLeaderAPI(cache_expiry_days=7)
|
||
|
|
|
||
|
|
# Force a fresh API call (ignore cache)
|
||
|
|
fresh_scores = api.get_player_scores(player_id, use_cache=False)
|
||
|
|
|
||
|
|
# Clear cache for a specific player
|
||
|
|
api.clear_cache(player_id)
|
||
|
|
|
||
|
|
# Clear all cache
|
||
|
|
api.clear_cache()
|
||
|
|
|
||
|
|
# Get the current cache directory
|
||
|
|
cache_dir = api.get_cache_dir()
|
||
|
|
```
|
||
|
|
|
||
|
|
### Pagination
|
||
|
|
|
||
|
|
The `get_player_scores` method automatically handles pagination to retrieve all available scores. You can control this behavior:
|
||
|
|
|
||
|
|
```python
|
||
|
|
# Set a custom page size (default is 100)
|
||
|
|
scores = api.get_player_scores(player_id, page_size=50)
|
||
|
|
|
||
|
|
# Limit the number of pages fetched
|
||
|
|
scores = api.get_player_scores(player_id, max_pages=5)
|
||
|
|
```
|
||
|
|
|
||
|
|
## Methods
|
||
|
|
|
||
|
|
- `get_player_scores(player_id, use_cache=True, page_size=100, max_pages=None)`: Retrieves all scores for a player.
|
||
|
|
- `get_player_songs(player_id, page=1, count=100, use_cache=True)`: Retrieves full song data for all unique songs a player has played.
|
||
|
|
- `get_player_songs_minimal(player_id, page=1, count=100, use_cache=True)`: Retrieves minimal song data (id, name, author, mapper, hash, bpm, duration) for all unique songs a player has played.
|
||
|
|
- `clear_cache(player_id=None)`: Clears the cache for a specific player or all cached data.
|
||
|
|
- `get_cache_dir()`: Returns the path to the current cache directory.
|