Home | Trees | Index | Help |
---|
Package musicbrainz2 :: Module webservice :: Class Query |
|
object
--+
|
Query
A simple interface to the MusicBrainz web service.
This is a facade which provides a simple interface to the MusicBrainz web service. It hides all the details like fetching data from a server, parsing the XML and creating an object tree. Using this class, you can request data by ID or search the collection of all resources (artists, releases, or tracks) to retrieve those matching given criteria. This document contains examples to get you started.http://musicbrainz.org/artist/c0b2500e-0cef-4130-869d-732b23ed9df5In some situations it is obvious from the context what type of resource an ID refers to. In these cases, abbreviated identifiers may be used, which are just the UUID part of the URI. Thus the ID above may also be written like this:
c0b2500e-0cef-4130-869d-732b23ed9df5All methods in this class which require IDs accept both the absolute URI and the abbreviated form (aka the relative URI).
Query
object is as simple as this:
>>> import musicbrainz2.webservice as ws
>>> q = ws.Query()
>>>
The instantiated object uses the standard WebService
class to access the
MusicBrainz web service. If you want to use a different server or you
have to pass user name and password because one of your queries
requires authentication, you have to create the WebService
object yourself and configure
it appropriately. This example uses the MusicBrainz test server and
also sets authentication data:
>>> import musicbrainz2.webservice as ws
>>> service = ws.WebService(host='test.musicbrainz.org',
... username='whatever', password='secret')
>>> q = ws.Query(service)
>>>
getArtistById
, getReleaseById
, or getTrackById
method can be used to
retrieve it. Example:
>>> import musicbrainz2.webservice as ws >>> q = ws.Query() >>> artist = q.getArtistById('c0b2500e-0cef-4130-869d-732b23ed9df5') >>> artist.name u'Tori Amos' >>> artist.sortName u'Amos, Tori' >>> print artist.type http://musicbrainz.org/ns/mmd-1.0#Person >>>
This returned just the basic artist data, however. To get more
detail about a resource, the include
parameters may be
used which expect an ArtistIncludes
, ReleaseIncludes
, or TrackIncludes
object, depending on the
resource type.
>>> import musicbrainz2.webservice as ws >>> q = ws.Query() >>> releaseId = '33dbcf02-25b9-4a35-bdb7-729455f33ad7' >>> include = ws.ReleaseIncludes(artist=True, tracks=True) >>> release = q.getReleaseById(releaseId, include) >>> release.title u'Tales of a Librarian' >>> release.artist.name u'Tori Amos' >>> release.tracks[0].title u'Precious Things' >>>Note that the query gets more expensive for the server the more data you request, so please be nice.
For each resource type (artist, release, and track), there is one
collection which contains all resources of a type. You can search these
collections using the getArtists
, getReleases
, and getTracks
methods. The collections are
huge, so you have to use filters (ArtistFilter
, ReleaseFilter
, or TrackFilter
) to retrieve only resources
matching given criteria.
getReleases
and a ReleaseFilter
object:
>>> import musicbrainz2.webservice as ws >>> q = ws.Query() >>> filter = ws.ReleaseFilter(discId='8jJklE258v6GofIqDIrE.c5ejBE-') >>> results = q.getReleases(filter=filter) >>> results[0].score 100 >>> results[0].release.title u'Under the Pink' >>>
The query returns a list of results (wsxml.ReleaseResult
objects in this
case), which are ordered by score, with a higher score indicating a
better match. Note that those results don't contain all the data about
a resource. If you need more detail, you can then use the getArtistById
, getReleaseById
, or getTrackById
methods to request the
resource.
limit
argument to limit the
number of results returned. This defaults to 25, but the server won't
send more than 100 results to save bandwidth and processing power.
WebServiceError
exception in case of
errors. Depending on the method, a subclass of WebServiceError
may be raised which
allows an application to handle errors more precisely. The following
example handles connection errors (invalid host name etc.) separately
and all other web service errors in a combined catch clause:
>>> try:
... artist = q.getArtistById('c0b2500e-0cef-4130-869d-732b23ed9df5')
... except ws.ConnectionError, e:
... pass # implement your error handling here
... except ws.WebServiceError, e:
... pass # catches all other web service errors
...
>>>
Method Summary | |
---|---|
Constructor. | |
Returns an artist. | |
Returns artists matching given criteria. | |
Returns a release. | |
Returns releases matching given criteria. | |
Returns a track. | |
Returns tracks matching given criteria. | |
Returns information about a MusicBrainz user. | |
Submit track to PUID mappings. | |
Inherited from object | |
x.__delattr__('name') <==> del x.name | |
x.__getattribute__('name') <==> x.name | |
x.__hash__() <==> hash(x) | |
T.__new__(S, ...) -> a new object with type S, a subtype of T | |
helper for pickle | |
helper for pickle | |
x.__repr__() <==> repr(x) | |
x.__setattr__('name', value) <==> x.name = value | |
x.__str__() <==> str(x) |
Method Details |
---|
__init__(self,
ws=None,
wsFactory=<class 'musicbrainz2.webservice.WebService'>,
clientId=None)
|
getArtistById(self, id_, include=None)Returns an artist. If no artist with that ID can be found,include
contains invalid tags or there's a server problem, an exception is
raised.
|
getArtists(self, filter)Returns artists matching given criteria.
|
getReleaseById(self, id_, include=None)Returns a release. If no release with that ID can be found,include
contains invalid tags or there's a server problem, and exception is
raised.
|
getReleases(self, filter)Returns releases matching given criteria.
|
getTrackById(self, id_, include=None)Returns a track. If no track with that ID can be found,include contains
invalid tags or there's a server problem, and exception is raised.
|
getTracks(self, filter)Returns tracks matching given criteria.
|
getUserByName(self, name)Returns information about a MusicBrainz user. You can only request user data if you know the user name and
password for that account. If username and/or password are incorrect,
an Query on how to supply user name and
password.
|
submitPuids(self, tracks2puids)Submit track to PUID mappings. The Query on how to supply authentication
data.
|
Home | Trees | Index | Help |
---|
Generated by Epydoc 2.1 on Wed Dec 20 18:19:28 2006 | http://epydoc.sf.net |