API Objects

RainwaveClient

class rainwaveclient.RainwaveClient(user_id=None, key=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 – the User ID to use when communicating with the API.

  • key – 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, args=None)

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.

Usage:

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

A list of RainwaveChannel objects associated with this RainwaveClient object.

property key

The API key to use when communicating with the API. Find your API key at http://rainwave.cc/keys/.

property user_id

The User ID to use when communicating with the API. Find your User ID at http://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

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 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 user_requests

A RainwaveUserRequestQueue of RainwaveUserRequest objects in the listener’s personal request queue.

RainwaveAlbum

class rainwaveclient.RainwaveAlbum(channel, raw_info)

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

A datetime.datetime object specifying when the album was added to the playlist.

property art

The URL of the cover art for the album.

property categories

A list of RainwaveCategory objects representing the categories the songs in the album belong to.

property channel

The RainwaveChannel object the album belongs to.

property cool

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

property cool_lowest

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

property fave

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

property fave_count

The number of listeners who have marked the album as a favourite.

get_song_by_id(song_id)

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

Parameters

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

property id

The ID of the album.

property name

The name of the album.

property played_last

A datetime.datetime object specifying the most recent date and time when a song in the album played.

property rating

The average of all ratings given to songs in the album by only the listener authenticating to the API.

property rating_avg

The average of all ratings given to songs in the album by all listeners.

property rating_complete

A boolean representing whether the listener has rated all songs in the album.

property rating_count

The total number of ratings given to songs in the album by all listeners.

property rating_histogram

A dictionary representing the distribution of ratings given to all songs in 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

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.

property request_count

The total number of times a song in the album was requested by any listener.

property request_rank

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

A list of RainwaveSong objects in the album.

property vote_count

The total number of election votes songs in 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).

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

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.