• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Copyright 2014 Joe Gregorio
2#
3# Licensed under the MIT License
4
5"""MIME-Type Parser
6
7This module provides basic functions for handling mime-types. It can handle
8matching mime-types against a list of media-ranges. See section 14.1 of the
9HTTP specification [RFC 2616] for a complete explanation.
10
11   http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1
12
13Contents:
14 - parse_mime_type():   Parses a mime-type into its component parts.
15 - parse_media_range(): Media-ranges are mime-types with wild-cards and a 'q'
16                          quality parameter.
17 - quality():           Determines the quality ('q') of a mime-type when
18                          compared against a list of media-ranges.
19 - quality_parsed():    Just like quality() except the second parameter must be
20                          pre-parsed.
21 - best_match():        Choose the mime-type with the highest quality ('q')
22                          from a list of candidates.
23"""
24from __future__ import absolute_import
25from functools import reduce
26import six
27
28__version__ = '0.1.3'
29__author__ = 'Joe Gregorio'
30__email__ = 'joe@bitworking.org'
31__license__ = 'MIT License'
32__credits__ = ''
33
34
35def parse_mime_type(mime_type):
36    """Parses a mime-type into its component parts.
37
38    Carves up a mime-type and returns a tuple of the (type, subtype, params)
39    where 'params' is a dictionary of all the parameters for the media range.
40    For example, the media range 'application/xhtml;q=0.5' would get parsed
41    into:
42
43       ('application', 'xhtml', {'q', '0.5'})
44       """
45    parts = mime_type.split(';')
46    params = dict([tuple([s.strip() for s in param.split('=', 1)])\
47            for param in parts[1:]
48                  ])
49    full_type = parts[0].strip()
50    # Java URLConnection class sends an Accept header that includes a
51    # single '*'. Turn it into a legal wildcard.
52    if full_type == '*':
53        full_type = '*/*'
54    (type, subtype) = full_type.split('/')
55
56    return (type.strip(), subtype.strip(), params)
57
58
59def parse_media_range(range):
60    """Parse a media-range into its component parts.
61
62    Carves up a media range and returns a tuple of the (type, subtype,
63    params) where 'params' is a dictionary of all the parameters for the media
64    range.  For example, the media range 'application/*;q=0.5' would get parsed
65    into:
66
67       ('application', '*', {'q', '0.5'})
68
69    In addition this function also guarantees that there is a value for 'q'
70    in the params dictionary, filling it in with a proper default if
71    necessary.
72    """
73    (type, subtype, params) = parse_mime_type(range)
74    if 'q' not in params or not params['q'] or \
75            not float(params['q']) or float(params['q']) > 1\
76            or float(params['q']) < 0:
77        params['q'] = '1'
78
79    return (type, subtype, params)
80
81
82def fitness_and_quality_parsed(mime_type, parsed_ranges):
83    """Find the best match for a mime-type amongst parsed media-ranges.
84
85    Find the best match for a given mime-type against a list of media_ranges
86    that have already been parsed by parse_media_range(). Returns a tuple of
87    the fitness value and the value of the 'q' quality parameter of the best
88    match, or (-1, 0) if no match was found. Just as for quality_parsed(),
89    'parsed_ranges' must be a list of parsed media ranges.
90    """
91    best_fitness = -1
92    best_fit_q = 0
93    (target_type, target_subtype, target_params) =\
94            parse_media_range(mime_type)
95    for (type, subtype, params) in parsed_ranges:
96        type_match = (type == target_type or\
97                      type == '*' or\
98                      target_type == '*')
99        subtype_match = (subtype == target_subtype or\
100                         subtype == '*' or\
101                         target_subtype == '*')
102        if type_match and subtype_match:
103            param_matches = reduce(lambda x, y: x + y, [1 for (key, value) in \
104                    six.iteritems(target_params) if key != 'q' and \
105                    key in params and value == params[key]], 0)
106            fitness = (type == target_type) and 100 or 0
107            fitness += (subtype == target_subtype) and 10 or 0
108            fitness += param_matches
109            if fitness > best_fitness:
110                best_fitness = fitness
111                best_fit_q = params['q']
112
113    return best_fitness, float(best_fit_q)
114
115
116def quality_parsed(mime_type, parsed_ranges):
117    """Find the best match for a mime-type amongst parsed media-ranges.
118
119    Find the best match for a given mime-type against a list of media_ranges
120    that have already been parsed by parse_media_range(). Returns the 'q'
121    quality parameter of the best match, 0 if no match was found. This function
122    bahaves the same as quality() except that 'parsed_ranges' must be a list of
123    parsed media ranges.
124    """
125
126    return fitness_and_quality_parsed(mime_type, parsed_ranges)[1]
127
128
129def quality(mime_type, ranges):
130    """Return the quality ('q') of a mime-type against a list of media-ranges.
131
132    Returns the quality 'q' of a mime-type when compared against the
133    media-ranges in ranges. For example:
134
135    >>> quality('text/html','text/*;q=0.3, text/html;q=0.7,
136                  text/html;level=1, text/html;level=2;q=0.4, */*;q=0.5')
137    0.7
138
139    """
140    parsed_ranges = [parse_media_range(r) for r in ranges.split(',')]
141
142    return quality_parsed(mime_type, parsed_ranges)
143
144
145def best_match(supported, header):
146    """Return mime-type with the highest quality ('q') from list of candidates.
147
148    Takes a list of supported mime-types and finds the best match for all the
149    media-ranges listed in header. The value of header must be a string that
150    conforms to the format of the HTTP Accept: header. The value of 'supported'
151    is a list of mime-types. The list of supported mime-types should be sorted
152    in order of increasing desirability, in case of a situation where there is
153    a tie.
154
155    >>> best_match(['application/xbel+xml', 'text/xml'],
156                   'text/*;q=0.5,*/*; q=0.1')
157    'text/xml'
158    """
159    split_header = _filter_blank(header.split(','))
160    parsed_header = [parse_media_range(r) for r in split_header]
161    weighted_matches = []
162    pos = 0
163    for mime_type in supported:
164        weighted_matches.append((fitness_and_quality_parsed(mime_type,
165                                 parsed_header), pos, mime_type))
166        pos += 1
167    weighted_matches.sort()
168
169    return weighted_matches[-1][0][1] and weighted_matches[-1][2] or ''
170
171
172def _filter_blank(i):
173    for s in i:
174        if s.strip():
175            yield s
176