API Objects

`RainwaveClient`

class rainwaveclient.RainwaveClient(user_id: int | None = None, key: str | None = None)

A RainwaveClient object provides a simple interface to the Rainwave API (see https://rainwave.cc/api4/ for details about the API).

Parameters:

user_id (int) – the User ID to use when communicating with the API.
key (str) – the API key to use when communicating with the API.

art_fmt = 'https://rainwave.cc{0}_320.jpg': The format string used to build canonical album art URLs.

base_url = 'https://rainwave.cc/api4/': The URL upon which all API calls are based.

call(path: str, args: dict | None = None, method: str = 'POST') → dict

Make a direct call to the API if you know the necessary path and arguments.

Parameters:

path (str) – the URL path of the API method to call.
args (dict) – (optional) any arguments required by the API method.
method (str) – (optional) the HTTP method to use for the API call, default POST

Returns:

The raw data returned from the API call.

Return type:

dict

Usage:

>>> from rainwaveclient import RainwaveClient
>>> rw = RainwaveClient(5049, 'abcde12345')
>>> rw.call('album', {'id': 1, 'sid': 5})
{'album': {'name': 'Bravely Default: Flying Fairy', ...}}

property channels: list[RainwaveChannel]: A list of RainwaveChannel objects associated with this RainwaveClient object.

property key: str: The API key to use when communicating with the API. Find your API key at https://rainwave.cc/keys/.

property user_id: int: The User ID to use when communicating with the API. Find your User ID at https://rainwave.cc/keys/.

`RainwaveChannel`

class rainwaveclient.RainwaveChannel(client: RainwaveClient, raw_info: dict)

A RainwaveChannel object represents one channel on the Rainwave network.

Note

You should not instantiate an object of this class directly, but rather obtain one from RainwaveClient.channels.

property albums: list[RainwaveAlbum]: A list of RainwaveAlbum objects in the playlist of the channel.

property artists: list[RainwaveArtist]: A list of RainwaveArtist objects in the playlist of the channel.

property client: RainwaveClient: The RainwaveClient object that the channel belongs to.

property description: str: A description of the channel.

get_album_by_id(album_id: int) → RainwaveAlbum

Return a RainwaveAlbum for the given album ID. Raise an IndexError if there is no album with the given ID in the playlist of the channel.

Parameters:: album_id (int) – the ID of the desired album.

get_album_by_name(name: str) → RainwaveAlbum

Return a RainwaveAlbum for the given album name. Raise an IndexError if there is no album with the given name in the playlist of the channel.

Parameters:: name (str) – the name of the desired album.

get_artist_by_id(artist_id: int) → RainwaveArtist

Return a RainwaveArtist for the given artist ID. Raise an IndexError if there is no artist with the given ID in the playlist of the channel.

Parameters:: artist_id (int) – the ID of the desired artist.

get_listener_by_id(listener_id: int) → RainwaveListener

Return a RainwaveListener for the given listener ID. Raise an IndexError if there is no listener with the given ID.

Parameters:: listener_id (int) – the ID of the desired listener.

get_listener_by_name(name: str) → RainwaveListener

Return a RainwaveListener for the given listener name. Raise an IndexError if there is no listener with the given name currently listening to the channel.

Parameters:: name (str) – the name of the desired listener.

get_song_by_id(song_id: int) → RainwaveSong

Return a RainwaveSong for the given song ID. Raise an IndexError if there is no song with the given ID in the playlist of the channel.

Parameters:: song_id (int) – the ID of the desired song.

property id: int: The ID of the channel.

property key: str: The channel key, a short string that identifies the channel.

property listeners: list[RainwaveListener]: A list of RainwaveListener objects listening to the channel.

property mp3_stream: str: The URL of the MP3 stream for the channel. See also ogg_stream.

property name: str: The name of the channel.

property ogg_stream: str: The URL of the OGG stream for the channel. See also mp3_stream.

property requests: list[RainwaveRequest]: A list of RainwaveRequest objects in the request line of the channel.

property schedule_current: RainwaveSchedule: The current RainwaveSchedule for the channel.

property schedule_history: list[RainwaveSchedule]: A list of the past RainwaveSchedule objects for the channel. The events are sorted reverse-chronologically: the first event in the list was the most recent event.

property schedule_next: list[RainwaveSchedule]: A list of the next RainwaveSchedule objects for the channel. The events are sorted chronologically: the first event in the list will happen soonest.

start_sync() → None: Begin syncing the timeline for the channel.

stop_sync() → None: Stop syncing the timeline for the channel.

property url: str: The URL of the web interface for the channel.

property user_requests: RainwaveUserRequestQueue: A RainwaveUserRequestQueue of RainwaveUserRequest objects in the listener’s personal request queue.

`RainwaveAlbum`

class rainwaveclient.RainwaveAlbum(channel: RainwaveChannel, raw_info: dict)

A RainwaveAlbum object represents one album.

Note

You should not instantiate an object of this class directly, but rather obtain one from RainwaveChannel.albums.

property added_on: datetime: A datetime.datetime object specifying when the album was added to the playlist.

property art: str: The URL of the cover art for the album.

property categories: list[RainwaveCategory]: A list of RainwaveCategory objects representing the categories the songs on the album belong to.

property channel: RainwaveChannel: The RainwaveChannel object the album belongs to.

property cool: bool: A boolean representing whether the entire album is on cooldown. cool will be True if and only if every song on the album is on cooldown.

property cool_lowest: datetime: A datetime.datetime object specifying the earliest date and time a song on the album will be out of cooldown and available to play. If any song on the album is already available, cool_lowest will be in the past.

property fave: bool: A boolean representing whether the album is marked as a favourite or not. Change whether the album is a favourite by assigning a boolean value to this attribute.

property fave_count: int: The number of listeners who have marked the album as a favourite.

get_song_by_id(song_id: int) → RainwaveSong

Return a RainwaveSong for the given song ID. Raises an IndexError if there is no song with the given ID on the album.

Parameters:: song_id (int) – the ID of the desired song.

property id: int: The ID of the album.

property name: str: The name of the album.

property played_last: datetime: A datetime.datetime object specifying the most recent date and time when a song on the album played.

property rating: float: The average of all ratings given to songs on the album by only the listener authenticating to the API.

property rating_avg: float: The average of all ratings given to songs on the album by all listeners.

property rating_complete: bool: A boolean representing whether the listener has rated all songs on the album.

property rating_count: int: The total number of ratings given to songs on the album by all listeners.

property rating_histogram: dict[str, int]

A dictionary representing the distribution of ratings given to all songs on the album by all listeners. For example:

>>> album.rating_histogram
{'1.0': 4, '1.5': 4, '2.0': 6, ..., '4.5': 46, '5.0': 26}

property rating_rank: int: The position of the album when albums on the channel are ranked by rating. The highest-rated album will have rating_rank == 1.

property rating_user: float: See rating.

property request_count: int: The total number of times a song on the album was requested by any listener.

property request_rank: int: The position of the album when albums on the channel are ranked by how often they are requested. The most-requested album will have request_rank == 1.

property songs: list[RainwaveSong]: A list of RainwaveSong objects on the album.

property url: str: The URL of the album information page on https://rainwave.cc/

property vote_count: int: The total number of election votes songs on the album have received.

`RainwaveArtist`

class rainwaveclient.RainwaveArtist(channel: RainwaveChannel, raw_info: dict)

A RainwaveArtist object represents one artist.

Note

You should not instantiate an object of this class directly, but rather obtain one from RainwaveChannel.artists or RainwaveSong.artists.

property channel: RainwaveChannel: The RainwaveChannel object associated with the artist.

property id: int: The ID of the artist.

property name: str: The name of the artist.

property song_count: int: The number of songs attributed to the artist.

property songs: list[RainwaveSong]: A list of RainwaveSong objects attributed to the artist.

`RainwaveSong`

class rainwaveclient.RainwaveSong(album: RainwaveAlbum, raw_info: dict)

A RainwaveSong object represents one song.

Note

You should not instantiate an object of this class directly, but rather obtain one from RainwaveAlbum.songs, RainwaveArtist.songs, or some other object.

property album: RainwaveAlbum: The RainwaveAlbum object the song belongs to.

property artist_string: str: A single string with the names of all artists for the song.

property artists: list[RainwaveArtist]: A list of RainwaveArtist objects the song is attributed to.

property available: bool: A boolean representing whether the song is available to play or not. Opposite of cool.

property categories: list[RainwaveCategory]: A list of RainwaveCategory objects representing the categories the song belongs to.

property channel_id: int: The RainwaveChannel.id of the channel the song belongs to.

property cool: bool: A boolean representing whether the song is on cooldown. Opposite of available.

property fave: bool: A boolean representing whether the song is marked as a fave or not. Change whether the song is a fave by assigning a boolean value to this attribute.

property id: int: The ID of the song.

property length: int: The length of the song in seconds. RainwaveSong objects also support len(song).

property link_text: str: The link text that corresponds with url.

property origin_channel_id: int: The RainwaveChannel.id of the home channel for the song. This could be different from channel_id if the song is in the playlist of multiple channels.

property origin_sid: int: See origin_channel_id.

property rating: float: The rating given to the song by the listener authenticating to the API. Change the rating by assigning a new value to this attribute.

property rating_allowed: bool: A boolean representing whether the listener can currently rate the song.

property rating_avg: float: The average of all ratings given to the song by all listeners.

property rating_count: int: The total number of ratings given to the song by all listeners.

property rating_histogram: dict[str, int]

A dictionary representing the distribution of ratings given to the song by all listeners. For example:

>>> song.rating_histogram
{'1.0': 4, '1.5': 4, '2.0': 6, ..., '4.5': 46, '5.0': 26}

property rating_rank: int: The position of the album when albums on the channel are ranked by rating. The highest-rated album will have rating_rank == 1.

property rating_user: float: See rating.

request() → None: Add the song to the authenticating listener’s request queue.

property request_count: int: The total number of times the song has been requested by any listener.

property request_rank: int: The position of the song when songs on the channel are ranked by how often they are requested. The most-requested song will have rating_rank == 1.

property sid: int: See channel_id.

property title: str: The title of the song.

property url: str: The URL of more information about the song.

`RainwaveCandidate`

class rainwaveclient.RainwaveCandidate(album: RainwaveAlbum, election: RainwaveElection, raw_info: dict)

A RainwaveCandidate object is a subclass of RainwaveSong representing a song that is a candidate in an election.

property entry_id: int: The election entry ID for this candidate. Used for voting.

property is_request: bool: A boolean representing whether the candidate is a listener request or not.

property requested_by: RainwaveListener: The RainwaveListener who requested the candidate, if the candidate is a request. None otherwise.

vote() → None: Cast a vote for the candidate.

property votes: int: The number of votes this candidate received in the election. If the election has not ended, votes will be 0.

`RainwaveRequest`

class rainwaveclient.RainwaveRequest(album: RainwaveAlbum, raw_info: dict)

A RainwaveRequest object is a subclass of RainwaveSong representing a song that has been requested to play on the radio.

property requester: RainwaveListener: The RainwaveListener who made the request.

`RainwaveUserRequest`

class rainwaveclient.RainwaveUserRequest(album: RainwaveAlbum, raw_info: dict)

A RainwaveUserRequest object is a subclass of RainwaveSong representing a song in the authenticating listener’s requests queue.

property blocked: bool: True if the request is currently blocked. See blocked_by_album and blocked_by_category to determine why the request is blocked.

property blocked_by_album: bool: True if the request is currently blocked because a song from the same album is in an election.

property blocked_by_category: bool: True if the request is currently blocked because a song from the same category is in an election.

delete() → None: Remove the requested song from the authenticating listener’s request queue.

`RainwaveUserRequestQueue`

class rainwaveclient.RainwaveUserRequestQueue(channel: RainwaveChannel)

A RainwaveUserRequestQueue is a list-like object that supports explicit reordering.

clear() → None: Clear all requests from the queue.

reorder(order: list[int]) → None

Change the order of the requests in the queue.

Parameters:: order (sequence) – the indices of the requests in the new order.

Example usage:

If you have four songs in your request queue, and you want to move the last song to the top of the queue:

>>> from rainwaveclient import RainwaveClient
>>> rw = RainwaveClient(5049, 'abcde12345')
>>> game = rw.channels[0]
>>> rq = game.user_requests
>>> rq.reorder([3, 0, 1, 2])

To randomly shuffle your request queue:

>>> import random
>>> indices = list(range(len(game.user_requests)))
>>> random.shuffle(indices)
>>> rq.reorder(indices)

All indices must appear in order and each index must only appear once.

`RainwaveSchedule`

class rainwaveclient.RainwaveSchedule(channel: RainwaveChannel, raw_info: dict)

A RainwaveSchedule object represents an event on a channel.

Note

You should not instantiate an object of this class directly, but rather obtain one from RainwaveChannel.schedule_current, RainwaveChannel.schedule_next, or RainwaveChannel.schedule_history.

property channel: RainwaveChannel: The RainwaveChannel object the event belongs to.

property end: datetime: A datetime.datetime object representing the end time of the event. For future events, this should equal start + length. For current and past events this should equal start_actual + length.

property id: int: The ID of the event.

property length: int: The duration of the event in seconds. For future elections, this value is estimated by averaging the duration of all songs in the election. RainwaveSchedule objects also support len(schedule).

property start: datetime: A datetime.datetime object representing the estimated start time of the event. This is only useful for future events. For current and past events, see start_actual.

property start_actual: datetime: A datetime.datetime object representing the actual start time of the event. If the event has not started yet, this will be None.

property type: str: The type of event (e.g. Election or OneUp).

`RainwaveElection`

class rainwaveclient.RainwaveElection(channel: RainwaveChannel, raw_info: dict)

A RainwaveElection object is a subclass of RainwaveSchedule and represents an election event on a channel.

property candidates: list[RainwaveCandidate]: A list of RainwaveCandidate objects in the election.

property song: RainwaveCandidate: The first RainwaveCandidate object in the list of candidates. If the RainwaveElection event has already closed, this is the song that won the election.

property songs: list[RainwaveCandidate]: See candidates.

`RainwaveOneTimePlay`

class rainwaveclient.RainwaveOneTimePlay(channel: RainwaveChannel, raw_info: dict)

A RainwaveOneTimePlay object is a subclass of RainwaveSchedule and represents a song added directly to the timeline by a manager.

property name: str: The name of the event.

property song: RainwaveSong: The RainwaveSong for the event.

property songs: list[RainwaveSong]: A list containing the RainwaveSong for the event.

`RainwaveListener`

class rainwaveclient.RainwaveListener(channel: RainwaveChannel, raw_info: dict)

A RainwaveListener object represents a radio listener.

property avatar: str: The URL of the listener’s avatar.

channel: RainwaveChannel = None: The RainwaveChannel the listener belongs to.

property color: str: See colour.

property colour: str: A hexadecimal string representing the listener’s colour on the forums.

property id: int: The ID of the listener.

property losing_requests: int: The number of requests made by the listener that lost their election.

property losing_votes: int: The number of votes the listeners has given to a song that lost an election.

property mind_changes: int: The total number of times the listener changed a song rating.

property name: str: The name of the listener.

property rank: str: A string representing the listener’s title on the forums.

property total_ratings: int: The total number of songs the listener has rated.

property total_requests: int: The total number of requests the listener has made.

property total_votes: int: The number of votes the listener has cast in the last two weeks.

property user_id: int: See id.

property winning_requests: int: The number of requests made by the listener that won their election.

property winning_votes: int: The number of votes the listener has given to a song that won an election.

`RainwaveCategory`

class rainwaveclient.RainwaveCategory(channel: RainwaveChannel, category_id: int, name: str)