API Objects

`RainwaveClient`

class rainwaveclient.RainwaveClient(user_id: int = None, key: str = 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) → 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.

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, raw_info)

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: A list of RainwaveAlbum objects in the playlist of the channel.

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

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

property description: A description of the channel.

get_album_by_id(album_id)

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)

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)

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)

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)

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)

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: The ID of the channel.

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

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

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

property name: The name of the channel.

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

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

property schedule_current: The current RainwaveSchedule for the channel.

property schedule_history: A list of the past RainwaveSchedule objects for the channel.

property schedule_next: A list of the next RainwaveSchedule objects for the channel.

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

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

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

property user_requests: 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, raw_info)

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: The RainwaveChannel object associated with the artist.

property id: The ID of the artist.

property name: The name of the artist.

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

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

`RainwaveSong`

class rainwaveclient.RainwaveSong(album, raw_info)

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: The RainwaveAlbum object the song belongs to.

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

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

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

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

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

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

property fave: 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: The ID of the song.

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

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

property origin_channel_id: 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: See origin_channel_id.

property rating: 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: A boolean representing whether the listener can currently rate the song.

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

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

property rating_histogram

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: 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: See rating.

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

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

property request_rank: 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: See channel_id.

property title: The title of the song.

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

`RainwaveCandidate`

class rainwaveclient.RainwaveCandidate(album, raw_info)

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

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

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

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

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

property votes: 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, raw_info)

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

property requester: The RainwaveListener who made the request.

`RainwaveUserRequest`

class rainwaveclient.RainwaveUserRequest(album, raw_info)

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

property blocked: 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: True if the request is currently blocked because a song from the same album is in an election.

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

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

`RainwaveUserRequestQueue`

class rainwaveclient.RainwaveUserRequestQueue(channel)

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

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

reorder(order)

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, raw_info)

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: The RainwaveChannel object the event belongs to.

property id: The ID of the event.

property start: A datetime.datetime object representing the start time of the event in UTC time.

`RainwaveElection`

class rainwaveclient.RainwaveElection(channel, raw_info)

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

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

property song: 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: See candidates.

`RainwaveOneTimePlay`

class rainwaveclient.RainwaveOneTimePlay(channel, raw_info)

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

property name: The name of the event.

property song: The RainwaveSong for the event.

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

`RainwaveListener`

class rainwaveclient.RainwaveListener(channel, raw_info)

A RainwaveListener object represents a radio listener.

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

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

property color: See colour.

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

property id: The ID of the listener.

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

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

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

property name: The name of the listener.

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

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

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

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

property user_id: See id.

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

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