MythTV  master
caa.py
Go to the documentation of this file.
1 # This file is part of the musicbrainzngs library
2 # Copyright (C) Alastair Porter, Wieland Hoffmann, and others
3 # This file is distributed under a BSD-2-Clause type license.
4 # See the COPYING file for more information.
5 
6 __all__ = [
7  'set_caa_hostname', 'get_image_list', 'get_release_group_image_list',
8  'get_release_group_image_front', 'get_image_front', 'get_image_back',
9  'get_image'
10  ]
11 
12 import json
13 
14 from musicbrainzngs import compat
15 from musicbrainzngs import musicbrainz
16 
17 hostname = "coverartarchive.org"
18 
19 
20 def set_caa_hostname(new_hostname):
21  """Set the base hostname for Cover Art Archive requests.
22  Defaults to 'coverartarchive.org'."""
23  global hostname
24  hostname = new_hostname
25 
26 
27 def _caa_request(mbid, imageid=None, size=None, entitytype="release"):
28  """ Make a CAA request.
29 
30  :param imageid: ``front``, ``back`` or a number from the listing obtained
31  with :meth:`get_image_list`.
32  :type imageid: str
33 
34  :param size: 250, 500
35  :type size: str or None
36 
37  :param entitytype: ``release`` or ``release-group``
38  :type entitytype: str
39  """
40  # Construct the full URL for the request, including hostname and
41  # query string.
42  path = [entitytype, mbid]
43  if imageid and size:
44  path.append("%s-%s" % (imageid, size))
45  elif imageid:
46  path.append(imageid)
47  url = compat.urlunparse((
48  'http',
49  hostname,
50  '/%s' % '/'.join(path),
51  '',
52  '',
53  ''
54  ))
55  musicbrainz._log.debug("GET request for %s" % (url, ))
56 
57  # Set up HTTP request handler and URL opener.
58  httpHandler = compat.HTTPHandler(debuglevel=0)
59  handlers = [httpHandler]
60 
61  opener = compat.build_opener(*handlers)
62 
63  # Make request.
64  req = musicbrainz._MusicbrainzHttpRequest("GET", url, None)
65  # Useragent isn't needed for CAA, but we'll add it if it exists
66  if musicbrainz._useragent != "":
67  req.add_header('User-Agent', musicbrainz._useragent)
68  musicbrainz._log.debug("requesting with UA %s" % musicbrainz._useragent)
69 
70  resp = musicbrainz._safe_read(opener, req, None)
71 
72  # TODO: The content type declared by the CAA for JSON files is
73  # 'applicaiton/octet-stream'. This is not useful to detect whether the
74  # content is JSON, so default to decoding JSON if no imageid was supplied.
75  # http://tickets.musicbrainz.org/browse/CAA-75
76  if imageid:
77  # If we asked for an image, return the image
78  return resp
79  else:
80  # Otherwise it's json
81  return json.loads(resp)
82 
83 
84 def get_image_list(releaseid):
85  """Get the list of cover art associated with a release.
86 
87  The return value is the deserialized response of the `JSON listing
88  <http://musicbrainz.org/doc/Cover_Art_Archive/API#.2Frelease.2F.7Bmbid.7D.2F>`_
89  returned by the Cover Art Archive API.
90 
91  If an error occurs then a :class:`~musicbrainzngs.ResponseError` will
92  be raised with one of the following HTTP codes:
93 
94  * 400: `Releaseid` is not a valid UUID
95  * 404: No release exists with an MBID of `releaseid`
96  * 503: Ratelimit exceeded
97  """
98  return _caa_request(releaseid)
99 
100 
101 def get_release_group_image_list(releasegroupid):
102  """Get the list of cover art associated with a release group.
103 
104  The return value is the deserialized response of the `JSON listing
105  <http://musicbrainz.org/doc/Cover_Art_Archive/API#.2Frelease-group.2F.7Bmbid.7D.2F>`_
106  returned by the Cover Art Archive API.
107 
108  If an error occurs then a :class:`~musicbrainzngs.ResponseError` will
109  be raised with one of the following HTTP codes:
110 
111  * 400: `Releaseid` is not a valid UUID
112  * 404: No release exists with an MBID of `releaseid`
113  * 503: Ratelimit exceeded
114  """
115  return _caa_request(releasegroupid, entitytype="release-group")
116 
117 
118 def get_release_group_image_front(releasegroupid, size=None):
119  """Download the front cover art for a release group.
120  The `size` argument and the possible error conditions are the same as for
121  :meth:`get_image`.
122  """
123  return get_image(releasegroupid, "front", size=size,
124  entitytype="release-group")
125 
126 
127 def get_image_front(releaseid, size=None):
128  """Download the front cover art for a release.
129  The `size` argument and the possible error conditions are the same as for
130  :meth:`get_image`.
131  """
132  return get_image(releaseid, "front", size=size)
133 
134 
135 def get_image_back(releaseid, size=None):
136  """Download the back cover art for a release.
137  The `size` argument and the possible error conditions are the same as for
138  :meth:`get_image`.
139  """
140  return get_image(releaseid, "back", size=size)
141 
142 
143 def get_image(mbid, coverid, size=None, entitytype="release"):
144  """Download cover art for a release. The coverart file to download
145  is specified by the `coverid` argument.
146 
147  If `size` is not specified, download the largest copy present, which can be
148  very large.
149 
150  If an error occurs then a :class:`~musicbrainzngs.ResponseError`
151  will be raised with one of the following HTTP codes:
152 
153  * 400: `Releaseid` is not a valid UUID or `coverid` is invalid
154  * 404: No release exists with an MBID of `releaseid`
155  * 503: Ratelimit exceeded
156 
157  :param coverid: ``front``, ``back`` or a number from the listing obtained with
158  :meth:`get_image_list`
159  :type coverid: int or str
160 
161  :param size: 250, 500 or None. If it is None, the largest available picture
162  will be downloaded. If the image originally uploaded to the
163  Cover Art Archive was smaller than the requested size, only
164  the original image will be returned.
165  :type size: str or None
166 
167  :param entitytype: The type of entity for which to download the cover art.
168  This is either ``release`` or ``release-group``.
169  :type entitytype: str
170  :return: The binary image data
171  :type: str
172  """
173  if isinstance(coverid, int):
174  coverid = "%d" % (coverid, )
175  if isinstance(size, int):
176  size = "%d" % (size, )
177  return _caa_request(mbid, coverid, size=size, entitytype=entitytype)
def set_caa_hostname(new_hostname)
Definition: caa.py:20
def get_image_front(releaseid, size=None)
Definition: caa.py:127
def get_release_group_image_front(releasegroupid, size=None)
Definition: caa.py:118
def get_release_group_image_list(releasegroupid)
Definition: caa.py:101
def get_image_list(releaseid)
Definition: caa.py:84
def get_image_back(releaseid, size=None)
Definition: caa.py:135
def _caa_request(mbid, imageid=None, size=None, entitytype="release")
Definition: caa.py:27
def get_image(mbid, coverid, size=None, entitytype="release")
Definition: caa.py:143