abc_radio_wrapper package

Submodules

abc_radio_wrapper.abc_radio_wrapper module

Main and only module used to search through the abcradio API.

ABCRadio class is used to conduct the search. The other classes are used to provide structured data and functionality to the result

class abc_radio_wrapper.abc_radio_wrapper.ABCRadio

Bases: object

API wrapper for accessing playlist history of various Australian Broadcasting Corporation radio channels

static construct_query_string(**params: ~typing_extensions.) → str

Construct query string to communicate with ABC radio API

Returns

str

e.g.”?from=2020-04-30T03:00:00.000000Z&station=triplej&offset=0&limit=10” internally this will return the keys order:’from’,’to’,’station’,’’offset’,’limit’ although the ordering is not a requirement of the underlying web API

continuous_search(**params: ~typing_extensions.) → Iterator[SearchResult]

generate next set of search results each time the function is called.

Examples

for searchresult in ABC.continuous_search():

#see SearchResult documentation for usage from here.

Warnings

if parameters are not added to the continuous_search and the program flow is not controlled then allowing the generator to continuously generate results will lead to roughly a million requests to the underling API (~720,000 as of Jan 2023)

search(**params: ~typing_extensions.) → SearchResult

Send request to abc radio API endpoint and create SearchResult instance

Parameters

**params: RequestParams

params[“channel”]:str any of channels in self.available_stations params[‘startDate’]: datetime

class abc_radio_wrapper.abc_radio_wrapper.Album(url: str | None, title: str, artwork: Artwork | None, release_year: int | None)

Bases: object

Dataclass to represent an album (referred to as “releases” in underlying web API). A song can be featured on several albums.

artwork: Artwork | None

classmethod from_json(json_input: dict[str, Any]) → Album

static get_url(json_input)

release_year: int | None

title: str

url: str | None

class abc_radio_wrapper.abc_radio_wrapper.Artist(url: str | None, name: str, is_australian: bool | None)

Bases: object

Dataclass to represent Artists

Attributes

url: Optional[str]

url that points to musicbrainz info page for the artist

name: str

Name of the artist e.g. “Justin Bieber”

is_australian: Optional[bool]

Almost always will be null, the underlying REST api rarely provides a value

classmethod from_json(json_input: dict[str, Any]) → Artist

Construct the Artist object from the json representation in https://music.abcradio.net.au/api/v1/plays/search.json

is_australian: bool | None

name: str

url: str | None

class abc_radio_wrapper.abc_radio_wrapper.Artwork(url: str, type: str, sizes: List[ArtworkSize])

Bases: object

Dataclass to represent the artwork of an associated Album. Each album can have several artworks and each artwork can have several image formats/sizes.

classmethod from_json(json_input: dict[str, Any]) → Artwork

sizes: List[ArtworkSize]

type: str

url: str

class abc_radio_wrapper.abc_radio_wrapper.ArtworkSize(url: str, width: int, height: int, aspect_ratio: str)

Bases: object

Dataclass to represent the image format/size for each artwork. Most typical use case is providing large images or thumbnails for each different interface.

aspect_ratio: str

property aspect_ratio_float: float

classmethod from_json(json_input: dict[str, Any]) → ArtworkSize

height: int

url: str

width: int

class abc_radio_wrapper.abc_radio_wrapper.RadioSong(played_time: datetime, channel: str, song: Song)

Bases: object

Dataclass for each entity returned from ABCradio.search, A RadioSong is a Song played at a specific time on a specific channel.

Attributes

played_time: datetime

original playtime, including timezone information

channel: str

Name of channel in which song was played e.g. “triplej”,”doublej”,”classic”,”jazz”,”unearthed”,”country”

song: Song

contains metadata of the song including artist and album details

channel: str

classmethod from_json(json_input: dict[str, Any]) → RadioSong

Create RadioSong instance based on json_input

Parameters

json_inputdict[str,Any]

In the format of:

{“entity”:”Play”,

“arid”:”…”, “played_time”:”2020-01-01T12:00:00+00:00” “service_id”:”triplej” “recording”:…, # Song details (see Song class for more details) “release”: … # Album details (see Album class for more details) }

Returns

RadioSong

played_time: datetime

song: Song

class abc_radio_wrapper.abc_radio_wrapper.RequestParams(*args, **kwargs)

Bases: dict

**kwarg arguments to be used when searching in the ABC web api

Parameters

from_: datetime

The earliest data starts from “2014-04-30T03:00:04+00:00”

to: datetime

to value should be greater than from_

limit: int

number of results to display in a single request, effective limit is 100

offset: int

index at which to start returning results, you can iterate through all radio plays by updating this value. See continuous_search for an example implementation.

station: str

any one of: “jazz,dig,doublej,unearthed,country,triplej,classic,kidslisten”

from_: datetime

limit: int

offset: int

station: str

to: datetime

class abc_radio_wrapper.abc_radio_wrapper.SearchResult(total: int, offset: int, limit: int, radio_songs: List[RadioSong])

Bases: object

Dataclass returned from ABCRadio.search

classmethod from_json(json_input: dict[str, Any]) → SearchResult

Create hierarchy of objects using the result of a single request. To see the expected json_format: https://music.abcradio.net.au/api/v1/plays/search.json

limit: int

offset: int

radio_songs: List[RadioSong]

total: int

class abc_radio_wrapper.abc_radio_wrapper.Song(title: str, duration: int, artists: List[Artist], album: Album | None, url: str | None)

Bases: object

Dataclass to represent a song

album: Album | None

artists: List[Artist]

duration: int

classmethod from_json(json_input: dict[str, Any]) → Song

Create Song instance based on json_input

Parameters

json_inputdict[str,Any]

In the format of:

{“entity”:”Play”,

“arid”:”…”, “played_time”:”2020-01-01T12:00:00+00:00”, “service_id”:”triplej”, “recording”:…, # Song details “release”: … # Album details }

Returns

Song

static get_url(json_input)

Occassionally the url to musicbrainz will be missing, make the proper check and return the url if it exists otherwise return null

title: str

url: str | None

Module contents

Top-level package for ABC Radio Wrapper.