Blame - docs/apiclient.mimeparse.html - platform/external/python/google-api-python-client

><a href=".">index</a> <a href="file:/usr/local/google/home/jcgregorio/projects/apiclient/apiclient/mimeparse.py">/usr/local/google/home/jcgregorio/projects/apiclient/apiclient/mimeparse.py</a></td></tr></table>

Joe Gregorio

b9e63ff

2011-06-30 12:38:10 -0400

[diff] [blame]

12

<tt>MIME-Type Parser

13

14

This module provides basic functions for handling mime-types. It can handle

15

matching mime-types against a list of media-ranges. See section 14.1 of the

16

HTTP specification [<a href="http://www.rfc-editor.org/rfc/rfc2616.txt">RFC 2616</a>] for a complete explanation.

17

18

<a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1">http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1</a>

19

20

Contents:

21

- <a href="#-parse_mime_type">parse_mime_type</a>():   Parses a mime-type into its component parts.

22

- <a href="#-parse_media_range">parse_media_range</a>(): Media-ranges are mime-types with wild-cards and a 'q'

23

quality parameter.

24

- <a href="#-quality">quality</a>():           Determines the quality ('q') of a mime-type when

25

compared against a list of media-ranges.

26

- <a href="#-quality_parsed">quality_parsed</a>():    Just like <a href="#-quality">quality</a>() except the second parameter must be

27

pre-parsed.

28

- <a href="#-best_match">best_match</a>():        Choose the mime-type with the highest quality ('q')

29

from a list of candidates.</tt>

<big>Functions</big></td></tr>

35

36

37

<td width="100%"><dl><dt><a name="-best_match">best_match</a>(supported, header)</dt><dd><tt>Return mime-type with the highest quality ('q') from list of candidates.

38

39

Takes a list of supported mime-types and finds the best match for all the

40

media-ranges listed in header. The value of header must be a string that

41

conforms to the format of the HTTP Accept: header. The value of 'supported'

42

is a list of mime-types. The list of supported mime-types should be sorted

43

in order of increasing desirability, in case of a situation where there is

44

a tie.

45

46

>>> <a href="#-best_match">best_match</a>(['application/xbel+xml', 'text/xml'],

47

'text/*;q=0.5,*/*; q=0.1')

48

'text/xml'</tt></dd></dl>

49

<dl><dt><a name="-fitness_and_quality_parsed">fitness_and_quality_parsed</a>(mime_type, parsed_ranges)</dt><dd><tt>Find the best match for a mime-type amongst parsed media-ranges.

50

51

Find the best match for a given mime-type against a list of media_ranges

52

that have already been parsed by <a href="#-parse_media_range">parse_media_range</a>(). Returns a tuple of

53

the fitness value and the value of the 'q' quality parameter of the best

54

match, or (-1, 0) if no match was found. Just as for <a href="#-quality_parsed">quality_parsed</a>(),

55

'parsed_ranges' must be a list of parsed media ranges.</tt></dd></dl>

56

<dl><dt><a name="-parse_media_range">parse_media_range</a>(range)</dt><dd><tt>Parse a media-range into its component parts.

57

58

Carves up a media range and returns a tuple of the (type, subtype,

59

params) where 'params' is a dictionary of all the parameters for the media

60

range.  For example, the media range 'application/*;q=0.5' would get parsed

61

into:

62

63

('application', '*', {'q', '0.5'})

64

65

In addition this function also guarantees that there is a value for 'q'

66

in the params dictionary, filling it in with a proper default if

67

necessary.</tt></dd></dl>

68

<dl><dt><a name="-parse_mime_type">parse_mime_type</a>(mime_type)</dt><dd><tt>Parses a mime-type into its component parts.

69

70

Carves up a mime-type and returns a tuple of the (type, subtype, params)

71

where 'params' is a dictionary of all the parameters for the media range.

72

For example, the media range 'application/xhtml;q=0.5' would get parsed

73

into:

74

75

('application', 'xhtml', {'q', '0.5'})</tt></dd></dl>

76

<dl><dt><a name="-quality">quality</a>(mime_type, ranges)</dt><dd><tt>Return the quality ('q') of a mime-type against a list of media-ranges.

77

78

Returns the quality 'q' of a mime-type when compared against the

79

media-ranges in ranges. For example:

80

81

>>> <a href="#-quality">quality</a>('text/html','text/*;q=0.3, text/html;q=0.7,

82

text/html;level=1, text/html;level=2;q=0.4, */*;q=0.5')

83

0.7</tt></dd></dl>

84

<dl><dt><a name="-quality_parsed">quality_parsed</a>(mime_type, parsed_ranges)</dt><dd><tt>Find the best match for a mime-type amongst parsed media-ranges.

85

86

Find the best match for a given mime-type against a list of media_ranges

87

that have already been parsed by <a href="#-parse_media_range">parse_media_range</a>(). Returns the 'q'

88

quality parameter of the best match, 0 if no match was found. This function

89

bahaves the same as <a href="#-quality">quality</a>() except that 'parsed_ranges' must be a list of

90

parsed media ranges.</tt></dd></dl>

91