1. api module

This module define the base API classes.

exception Error

Bases: exceptions.Exception

Base musiXmatch API error.

>>> import musixmatch
>>> raise musixmatch.api.Error('Error message')
Traceback (most recent call last):
...
Error: Error message

exception ResponseMessageError

Bases: musixmatch.api.Error

Represents errors occurred while parsing the response messages.

class ResponseStatusCode

Bases: int

Represents response message status code. Casting a ResponseStatusCode to str returns the message associated with the status code:

>>> from musixmatch.api import ResponseStatusCode
>>> str(ResponseStatusCode(200))
'The request was successful.'
>>> str(ResponseStatusCode(401))
'Authentication failed, probably because of a bad API key.'

The status code to description mapping is:

Code	Description
200	The request was successful.
400	The request had bad syntax or was inherently impossible to be satisfied.
401	Authentication failed, probably because of a bad API key.
402	A limit was reached, either you exceeded per hour requests limits or your balance is insufficient.
403	You are not authorized to perform this operation or the api version you’re trying to use has been shut down.
404	Requested resource was not found.
405	Requested method was not found.

Any other status code will produce a default message:

>>> from musixmatch.api import ResponseStatusCode
>>> str(ResponseStatusCode(666))
'Unknown status code 666!'

Casting a ResponseStatusCode to bool returns True if status code is 200, False otherwise:

>>> from musixmatch.api import ResponseStatusCode
>>> bool(ResponseStatusCode(200))
True
>>> bool(ResponseStatusCode(400))
False
>>> bool(ResponseStatusCode(666))
False

class ResponseMessage(response)

Abstract class which provides a base class for formatted response.

status_code

Is the ResponseStatusCode object representing the message status code.

Raises :ValueError if not set.

class JsonResponseMessage(response)

A ResponseMessage subclass which behaves like a dict to expose the Json structure contained in the response message. Parses the Json response message and build a proper python dict containing all the information. Also, setup a ResponseStatusCode by querying the dict for the [‘header’][‘status_code’] item.

class QueryString(items=(), **keywords)

A class representing the keyword arguments to be used in HTTP requests as query string. Takes a dict of keywords, and encode values using utf-8. Also, the query string is sorted by keyword name, so that its string representation is always the same, thus can be used in hashes.

Casting a QueryString to str returns the urlencoded query string:

>>> from musixmatch.api import QueryString
>>> str(QueryString({ 'country': 'it', 'page': 1, 'page_size': 3 }))
'country=it&page=1&page_size=3'

Using repr() on QueryString returns an evaluable representation of the current instance, excluding apikey value:

>>> from musixmatch.api import QueryString
>>> repr(QueryString({ 'country': 'it', 'page': 1, 'apikey': 'whatever'}))
"QueryString({'country': 'it', 'page': '1'})"

items()

Overloads dict.item() using __iter__().

class Method

Utility class to build API methods name and call them as functions.

Method has custom attribute access to build method names like those specified in the API. Each attribute access builds a new Method with a new name.

Calling a Method as a function with keyword arguments, builds a Request, runs it and returns the result. If apikey is undefined, environment variable musixmatch_apikey will be used. If format is undefined, environment variable musixmatch_format will be used. If musixmatch_format is undefined, jason format will be used.

>>> import musixmatch
>>> artist = musixmatch.api.Method('artist')
>>> 
>>> try:
...     chart = artist.chart.get(country='it', page=1, page_size=3)
... except musixmatch.api.Error, e:
...     pass

class Request(api_method, query=(), **keywords)

This is the main API class. Given a Method or a method name, a QueryString or a dict, it can build the API query URL, run the request and return the response either as a string or as a ResponseMessage subclass. Assuming the default web services location, this class try to build a proper request:

>>> from musixmatch.api import Request, Method, QueryString
>>> method_name = 'artist.chart.get'
>>> method = Method(method_name)
>>> keywords = { 'country': 'it', 'page': 1, 'page_size': 3 }
>>> query_string = QueryString(keywords)
>>> 
>>> r1 = Request(method_name, keywords)
>>> r2 = Request(method_name, **keywords)
>>> r3 = Request(method_name, query_string)
>>> r4 = Request(method, keywords)
>>> r5 = Request(method, **keywords)
>>> r6 = Request(method, query_string)

If method is string, try to cast it into a Method. If query_string is a dict, try to cast it into a QueryString. If query_string is not specified, try to use keywords arguments as a dict and cast it into a QueryString.

Turning the Request into a str returns the URL representing the API request:

>>> str(Request('artist.chart.get', { 'country': 'it', 'page': 1 }))
'http://api.musixmatch.com/ws/1.1/artist.chart.get?country=it&page=1'

query_string

The QueryString instance.

api_method

The Method instance.

response

The ResponseMessage based on the format key in the QueryString.