Source Code for Module grassyknoll.compat.mimeparse

  1  """MIME-Type Parser 
  2   
  3  This module provides basic functions for handling mime-types. It can handle 
  4  matching mime-types against a list of media-ranges. See section 14.1 of  
  5  the HTTP specification [RFC 2616] for a complete explaination. 
  6   
  7     http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1 
  8   
  9  Contents: 
 10      - parse_mime_type():   Parses a mime-type into it's component parts. 
 11      - parse_media_range(): Media-ranges are mime-types with wild-cards and a 'q' quality parameter. 
 12      - quality():           Determines the quality ('q') of a mime-type when compared against a list of media-ranges. 
 13      - quality_parsed():    Just like quality() except the second parameter must be pre-parsed. 
 14      - best_match():        Choose the mime-type with the highest quality ('q') from a list of candidates.  
 15  """ 
 16   
 17  __version__ = "0.1.1" 
 18  __author__ = 'Joe Gregorio' 
 19  __email__ = "joe@bitworking.org" 
 20  __credits__ = "" 
 21   
 22 -def parse_mime_type(mime_type): 
 23      """Carves up a mime_type and returns a tuple of the 
 24         (type, subtype, params) where 'params' is a dictionary 
 25         of all the parameters for the media range. 
 26         For example, the media range 'application/xhtml;q=0.5' would 
 27         get parsed into: 
 28   
 29         ('application', 'xhtml', {'q', '0.5'}) 
 30         """ 
 31      parts = mime_type.split(";") 
 32      params = dict([tuple([s.strip() for s in param.split("=")])\ 
 33              for param in parts[1:] ]) 
 34      (type, subtype) = parts[0].split("/") 
 35      return (type.strip(), subtype.strip(), params) 
 36   
 37 -def parse_media_range(range): 
 38      """Carves up a media range and returns a tuple of the 
 39         (type, subtype, params) where 'params' is a dictionary 
 40         of all the parameters for the media range. 
 41         For example, the media range 'application/*;q=0.5' would 
 42         get parsed into: 
 43   
 44         ('application', '*', {'q', '0.5'}) 
 45   
 46         In addition this function also guarantees that there  
 47         is a value for 'q' in the params dictionary, filling it 
 48         in with a proper default if necessary. 
 49         """ 
 50      (type, subtype, params) = parse_mime_type(range) 
 51      if not params.has_key('q') or not params['q'] or \ 
 52              not float(params['q']) or float(params['q']) > 1\ 
 53              or float(params['q']) < 0: 
 54          params['q'] = '1' 
 55      return (type, subtype, params) 
 56   
 57 -def quality_parsed(mime_type, parsed_ranges): 
 58      """Find the best match for a given mime_type against  
 59         a list of media_ranges that have already been  
 60         parsed by parse_media_range(). Returns the  
 61         'q' quality parameter of the best match, 0 if no 
 62         match was found. This function bahaves the same as quality() 
 63         except that 'parsed_ranges' must be a list of 
 64         parsed media ranges. """ 
 65      best_fitness = -1  
 66      best_match = "" 
 67      best_fit_q = 0 
 68      (target_type, target_subtype, target_params) =\ 
 69              parse_media_range(mime_type) 
 70      for (type, subtype, params) in parsed_ranges: 
 71          param_matches = reduce(lambda x, y: x+y, [1 for (key, value) in \ 
 72                  target_params.iteritems() if key != 'q' and \ 
 73                  params.has_key(key) and value == params[key]], 0) 
 74          if (type == target_type or type == '*' or target_type == '*') and \ 
 75                  (subtype == target_subtype or subtype == '*' or target_subtype == '*'): 
 76              fitness = (type == target_type) and 100 or 0 
 77              fitness += (subtype == target_subtype) and 10 or 0 
 78              fitness += param_matches 
 79              if fitness > best_fitness: 
 80                  best_fitness = fitness 
 81                  best_fit_q = params['q'] 
 82               
 83      return float(best_fit_q) 
 84       
 85 -def quality(mime_type, ranges): 
 86      """Returns the quality 'q' of a mime_type when compared 
 87      against the media-ranges in ranges. For example: 
 88   
 89      >>> quality('text/html','text/*;q=0.3, text/html;q=0.7, text/html;level=1, text/html;level=2;q=0.4, */*;q=0.5') 
 90      0.7 
 91       
 92      """  
 93      parsed_ranges = [parse_media_range(r) for r in ranges.split(",")] 
 94      return quality_parsed(mime_type, parsed_ranges) 
 95   
 96 -def best_match(supported, header): 
 97      """Takes a list of supported mime-types and finds the best 
 98      match for all the media-ranges listed in header. The value of 
 99      header must be a string that conforms to the format of the  
100      HTTP Accept: header. The value of 'supported' is a list of 
101      mime-types. 
102       
103      >>> best_match(['application/xbel+xml', 'text/xml'], 'text/*;q=0.5,*/*; q=0.1') 
104      'text/xml' 
105      """ 
106      parsed_header = [parse_media_range(r) for r in header.split(",")] 
107      weighted_matches = [(quality_parsed(mime_type, parsed_header), mime_type)\ 
108              for mime_type in supported] 
109      weighted_matches.sort() 
110      return weighted_matches[-1][0] and weighted_matches[-1][1] or '' 
111   
112  if __name__ == "__main__": 
113      import unittest 
114   
115 -    class TestMimeParsing(unittest.TestCase): 
116   
117 -        def test_parse_media_range(self): 
118              self.assert_(('application', 'xml', {'q': '1'}) == parse_media_range('application/xml;q=1')) 
119              self.assertEqual(('application', 'xml', {'q': '1'}), parse_media_range('application/xml')) 
120              self.assertEqual(('application', 'xml', {'q': '1'}), parse_media_range('application/xml;q=')) 
121              self.assertEqual(('application', 'xml', {'q': '1'}), parse_media_range('application/xml ; q=')) 
122              self.assertEqual(('application', 'xml', {'q': '1', 'b': 'other'}), parse_media_range('application/xml ; q=1;b=other')) 
123              self.assertEqual(('application', 'xml', {'q': '1', 'b': 'other'}), parse_media_range('application/xml ; q=2;b=other')) 
124   
125 -        def test_rfc_2616_example(self): 
126              accept = "text/*;q=0.3, text/html;q=0.7, text/html;level=1, text/html;level=2;q=0.4, */*;q=0.5" 
127              self.assertEqual(1, quality("text/html;level=1", accept)) 
128              self.assertEqual(0.7, quality("text/html", accept)) 
129              self.assertEqual(0.3, quality("text/plain", accept)) 
130              self.assertEqual(0.5, quality("image/jpeg", accept)) 
131              self.assertEqual(0.4, quality("text/html;level=2", accept)) 
132              self.assertEqual(0.7, quality("text/html;level=3", accept)) 
133   
134 -        def test_best_match(self): 
135              mime_types_supported = ['application/xbel+xml', 'application/xml'] 
136              # direct match 
137              self.assertEqual(best_match(mime_types_supported, 'application/xbel+xml'), 'application/xbel+xml') 
138              # direct match with a q parameter 
139              self.assertEqual(best_match(mime_types_supported, 'application/xbel+xml; q=1'), 'application/xbel+xml') 
140              # direct match of our second choice with a q parameter 
141              self.assertEqual(best_match(mime_types_supported, 'application/xml; q=1'), 'application/xml') 
142              # match using a subtype wildcard 
143              self.assertEqual(best_match(mime_types_supported, 'application/*; q=1'), 'application/xml') 
144              # match using a type wildcard 
145              self.assertEqual(best_match(mime_types_supported, '*/*'), 'application/xml') 
146   
147              mime_types_supported = ['application/xbel+xml', 'text/xml'] 
148              # match using a type versus a lower weighted subtype 
149              self.assertEqual(best_match(mime_types_supported, 'text/*;q=0.5,*/*; q=0.1'), 'text/xml') 
150              # fail to match anything 
151              self.assertEqual(best_match(mime_types_supported, 'text/html,application/atom+xml; q=0.9'), '') 
152   
153 -        def test_support_wildcards(self): 
154              mime_types_supported = ['image/*', 'application/xml'] 
155              # match using a type wildcard 
156              self.assertEqual(best_match(mime_types_supported, 'image/png'), 'image/*') 
157              # match using a wildcard for both requested and supported  
158              self.assertEqual(best_match(mime_types_supported, 'image/*'), 'image/*') 
159   
160      unittest.main() 
161