Package musicbrainz2 :: Module utils
[frames] | no frames]

Source Code for Module musicbrainz2.utils

  1  """Various utilities to simplify common tasks. 
  2   
  3  This module contains helper functions to make common tasks easier. 
  4   
  5  @author: Matthias Friedrich <matt@mafr.de> 
  6  """ 
  7  __revision__ = '$Id: utils.py 13322 2011-11-03 13:38:06Z luks $' 
  8   
  9  import re 
 10  import urlparse 
 11   
 12  __all__ = [ 
 13          'extractUuid', 'extractFragment', 'extractEntityType', 
 14          'getReleaseTypeName', 'getCountryName', 'getLanguageName', 
 15          'getScriptName', 
 16  ] 
 17   
 18   
 19  # A pattern to split the path part of an absolute MB URI. 
 20  PATH_PATTERN = '^/(artist|release|track|label|release-group)/([^/]*)$' 
 21   
 22   
23 -def extractUuid(uriStr, resType=None):
24 """Extract the UUID part from a MusicBrainz identifier. 25 26 This function takes a MusicBrainz ID (an absolute URI) as the input 27 and returns the UUID part of the URI, thus turning it into a relative 28 URI. If C{uriStr} is None or a relative URI, then it is returned 29 unchanged. 30 31 The C{resType} parameter can be used for error checking. Set it to 32 'artist', 'release', or 'track' to make sure C{uriStr} is a 33 syntactically valid MusicBrainz identifier of the given resource 34 type. If it isn't, a C{ValueError} exception is raised. 35 This error checking only works if C{uriStr} is an absolute URI, of 36 course. 37 38 Example: 39 40 >>> from musicbrainz2.utils import extractUuid 41 >>> extractUuid('http://musicbrainz.org/artist/c0b2500e-0cef-4130-869d-732b23ed9df5', 'artist') 42 'c0b2500e-0cef-4130-869d-732b23ed9df5' 43 >>> 44 45 @param uriStr: a string containing a MusicBrainz ID (an URI), or None 46 @param resType: a string containing a resource type 47 48 @return: a string containing a relative URI, or None 49 50 @raise ValueError: the given URI is no valid MusicBrainz ID 51 """ 52 if uriStr is None: 53 return None 54 55 (scheme, netloc, path) = urlparse.urlparse(uriStr)[:3] 56 57 if scheme == '': 58 return uriStr # no URI, probably already the UUID 59 60 if scheme != 'http' or netloc != 'musicbrainz.org': 61 raise ValueError('%s is no MB ID.' % uriStr) 62 63 m = re.match(PATH_PATTERN, path) 64 65 if m: 66 if resType is None: 67 return m.group(2) 68 else: 69 if m.group(1) == resType: 70 return m.group(2) 71 else: 72 raise ValueError('expected "%s" Id' % resType) 73 else: 74 raise ValueError('%s is no valid MB ID.' % uriStr)
75 76
77 -def extractFragment(uriStr, uriPrefix=None):
78 """Extract the fragment part from a URI. 79 80 If C{uriStr} is None or no absolute URI, then it is returned unchanged. 81 82 The C{uriPrefix} parameter can be used for error checking. If C{uriStr} 83 is an absolute URI, then the function checks if it starts with 84 C{uriPrefix}. If it doesn't, a C{ValueError} exception is raised. 85 86 @param uriStr: a string containing an absolute URI 87 @param uriPrefix: a string containing an URI prefix 88 89 @return: a string containing the fragment, or None 90 91 @raise ValueError: the given URI doesn't start with C{uriPrefix} 92 """ 93 if uriStr is None: 94 return None 95 96 (scheme, netloc, path, params, query, frag) = urlparse.urlparse(uriStr) 97 if scheme == '': 98 return uriStr # this is no URI 99 100 if uriPrefix is None or uriStr.startswith(uriPrefix): 101 return frag 102 else: 103 raise ValueError("prefix doesn't match URI %s" % uriStr)
104 105
106 -def extractEntityType(uriStr):
107 """Returns the entity type an entity URI is referring to. 108 109 @param uriStr: a string containing an absolute entity URI 110 111 @return: a string containing 'artist', 'release', 'track', or 'label' 112 113 @raise ValueError: if the given URI is no valid MusicBrainz ID 114 """ 115 if uriStr is None: 116 raise ValueError('None is no valid entity URI') 117 118 (scheme, netloc, path) = urlparse.urlparse(uriStr)[:3] 119 120 if scheme == '': 121 raise ValueError('%s is no absolute MB ID.' % uriStr) 122 123 if scheme != 'http' or netloc != 'musicbrainz.org': 124 raise ValueError('%s is no MB ID.' % uriStr) 125 126 m = re.match(PATH_PATTERN, path) 127 128 if m: 129 return m.group(1) 130 else: 131 raise ValueError('%s is no valid MB ID.' % uriStr)
132 133
134 -def getReleaseTypeName(releaseType):
135 """Returns the name of a release type URI. 136 137 @param releaseType: a string containing a release type URI 138 139 @return: a string containing a printable name for the release type 140 141 @see: L{musicbrainz2.model.Release} 142 """ 143 from musicbrainz2.data.releasetypenames import releaseTypeNames 144 return releaseTypeNames.get(releaseType)
145 146
147 -def getCountryName(id_):
148 """Returns a country's name based on an ISO-3166 country code. 149 150 The country table this function is based on has been modified for 151 MusicBrainz purposes by using the extension mechanism defined in 152 ISO-3166. All IDs are still valid ISO-3166 country codes, but some 153 IDs have been added to include historic countries and some of the 154 country names have been modified to make them better suited for 155 display purposes. 156 157 If the country ID is not found, None is returned. This may happen 158 for example, when new countries are added to the MusicBrainz web 159 service which aren't known to this library yet. 160 161 @param id_: a two-letter upper case string containing an ISO-3166 code 162 163 @return: a string containing the country's name, or None 164 165 @see: L{musicbrainz2.model} 166 """ 167 from musicbrainz2.data.countrynames import countryNames 168 return countryNames.get(id_)
169 170
171 -def getLanguageName(id_):
172 """Returns a language name based on an ISO-639-2/T code. 173 174 This function uses a subset of the ISO-639-2/T code table to map 175 language IDs (terminologic, not bibliographic ones!) to names. 176 177 @param id_: a three-letter upper case string containing an ISO-639-2/T code 178 179 @return: a string containing the language's name, or None 180 181 @see: L{musicbrainz2.model} 182 """ 183 from musicbrainz2.data.languagenames import languageNames 184 return languageNames.get(id_)
185 186
187 -def getScriptName(id_):
188 """Returns a script name based on an ISO-15924 code. 189 190 This function uses a subset of the ISO-15924 code table to map 191 script IDs to names. 192 193 @param id_: a four-letter string containing an ISO-15924 script code 194 195 @return: a string containing the script's name, or None 196 197 @see: L{musicbrainz2.model} 198 """ 199 from musicbrainz2.data.scriptnames import scriptNames 200 return scriptNames.get(id_)
201 202 203 # EOF 204