← Back to branch summary

~ubuntu-branches/ubuntu/maverick/python3.1/maverick

« back to all changes in this revision

Viewing changes to Doc/library/mimetypes.rst

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2009-03-23 00:01:27 UTC
  • Revision ID: james.westby@ubuntu.com-20090323000127-5fstfxju4ufrhthq
Tags: upstream-3.1~a1+20090322
Import upstream version 3.1~a1+20090322

Show diffs side-by-side

added added

removed removed

Lines of Context:
Doc/library/mimetypes.rst
 
1
 
 
2
:mod:`mimetypes` --- Map filenames to MIME types
 
3
================================================
 
4
 
 
5
.. module:: mimetypes
 
6
   :synopsis: Mapping of filename extensions to MIME types.
 
7
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
 
8
 
 
9
 
 
10
.. index:: pair: MIME; content type
 
11
 
 
12
The :mod:`mimetypes` module converts between a filename or URL and the MIME type
 
13
associated with the filename extension.  Conversions are provided from filename
 
14
to MIME type and from MIME type to filename extension; encodings are not
 
15
supported for the latter conversion.
 
16
 
 
17
The module provides one class and a number of convenience functions. The
 
18
functions are the normal interface to this module, but some applications may be
 
19
interested in the class as well.
 
20
 
 
21
The functions described below provide the primary interface for this module.  If
 
22
the module has not been initialized, they will call :func:`init` if they rely on
 
23
the information :func:`init` sets up.
 
24
 
 
25
 
 
26
.. function:: guess_type(filename[, strict])
 
27
 
 
28
   .. index:: pair: MIME; headers
 
29
 
 
30
   Guess the type of a file based on its filename or URL, given by *filename*.  The
 
31
   return value is a tuple ``(type, encoding)`` where *type* is ``None`` if the
 
32
   type can't be guessed (missing or unknown suffix) or a string of the form
 
33
   ``'type/subtype'``, usable for a MIME :mailheader:`content-type` header.
 
34
 
 
35
   *encoding* is ``None`` for no encoding or the name of the program used to encode
 
36
   (e.g. :program:`compress` or :program:`gzip`). The encoding is suitable for use
 
37
   as a :mailheader:`Content-Encoding` header, *not* as a
 
38
   :mailheader:`Content-Transfer-Encoding` header. The mappings are table driven.
 
39
   Encoding suffixes are case sensitive; type suffixes are first tried case
 
40
   sensitively, then case insensitively.
 
41
 
 
42
   Optional *strict* is a flag specifying whether the list of known MIME types
 
43
   is limited to only the official types `registered with IANA
 
44
   <http://www.iana.org/assignments/media-types/>`_ are recognized.
 
45
   When *strict* is true (the default), only the IANA types are supported; when
 
46
   *strict* is false, some additional non-standard but commonly used MIME types
 
47
   are also recognized.
 
48
 
 
49
 
 
50
.. function:: guess_all_extensions(type[, strict])
 
51
 
 
52
   Guess the extensions for a file based on its MIME type, given by *type*. The
 
53
   return value is a list of strings giving all possible filename extensions,
 
54
   including the leading dot (``'.'``).  The extensions are not guaranteed to have
 
55
   been associated with any particular data stream, but would be mapped to the MIME
 
56
   type *type* by :func:`guess_type`.
 
57
 
 
58
   Optional *strict* has the same meaning as with the :func:`guess_type` function.
 
59
 
 
60
 
 
61
.. function:: guess_extension(type[, strict])
 
62
 
 
63
   Guess the extension for a file based on its MIME type, given by *type*. The
 
64
   return value is a string giving a filename extension, including the leading dot
 
65
   (``'.'``).  The extension is not guaranteed to have been associated with any
 
66
   particular data stream, but would be mapped to the  MIME type *type* by
 
67
   :func:`guess_type`.  If no extension can be guessed for *type*, ``None`` is
 
68
   returned.
 
69
 
 
70
   Optional *strict* has the same meaning as with the :func:`guess_type` function.
 
71
 
 
72
Some additional functions and data items are available for controlling the
 
73
behavior of the module.
 
74
 
 
75
 
 
76
.. function:: init([files])
 
77
 
 
78
   Initialize the internal data structures.  If given, *files* must be a sequence
 
79
   of file names which should be used to augment the default type map.  If omitted,
 
80
   the file names to use are taken from :const:`knownfiles`.  Each file named in
 
81
   *files* or :const:`knownfiles` takes precedence over those named before it.
 
82
   Calling :func:`init` repeatedly is allowed.
 
83
 
 
84
 
 
85
.. function:: read_mime_types(filename)
 
86
 
 
87
   Load the type map given in the file *filename*, if it exists.  The  type map is
 
88
   returned as a dictionary mapping filename extensions, including the leading dot
 
89
   (``'.'``), to strings of the form ``'type/subtype'``.  If the file *filename*
 
90
   does not exist or cannot be read, ``None`` is returned.
 
91
 
 
92
 
 
93
.. function:: add_type(type, ext[, strict])
 
94
 
 
95
   Add a mapping from the mimetype *type* to the extension *ext*. When the
 
96
   extension is already known, the new type will replace the old one. When the type
 
97
   is already known the extension will be added to the list of known extensions.
 
98
 
 
99
   When *strict* is True (the default), the mapping will added to the official MIME
 
100
   types, otherwise to the non-standard ones.
 
101
 
 
102
 
 
103
.. data:: inited
 
104
 
 
105
   Flag indicating whether or not the global data structures have been initialized.
 
106
   This is set to true by :func:`init`.
 
107
 
 
108
 
 
109
.. data:: knownfiles
 
110
 
 
111
   .. index:: single: file; mime.types
 
112
 
 
113
   List of type map file names commonly installed.  These files are typically named
 
114
   :file:`mime.types` and are installed in different locations by different
 
115
   packages.
 
116
 
 
117
 
 
118
.. data:: suffix_map
 
119
 
 
120
   Dictionary mapping suffixes to suffixes.  This is used to allow recognition of
 
121
   encoded files for which the encoding and the type are indicated by the same
 
122
   extension.  For example, the :file:`.tgz` extension is mapped to :file:`.tar.gz`
 
123
   to allow the encoding and type to be recognized separately.
 
124
 
 
125
 
 
126
.. data:: encodings_map
 
127
 
 
128
   Dictionary mapping filename extensions to encoding types.
 
129
 
 
130
 
 
131
.. data:: types_map
 
132
 
 
133
   Dictionary mapping filename extensions to MIME types.
 
134
 
 
135
 
 
136
.. data:: common_types
 
137
 
 
138
   Dictionary mapping filename extensions to non-standard, but commonly found MIME
 
139
   types.
 
140
 
 
141
The :class:`MimeTypes` class may be useful for applications which may want more
 
142
than one MIME-type database:
 
143
 
 
144
 
 
145
.. class:: MimeTypes([filenames])
 
146
 
 
147
   This class represents a MIME-types database.  By default, it provides access to
 
148
   the same database as the rest of this module. The initial database is a copy of
 
149
   that provided by the module, and may be extended by loading additional
 
150
   :file:`mime.types`\ -style files into the database using the :meth:`read` or
 
151
   :meth:`readfp` methods.  The mapping dictionaries may also be cleared before
 
152
   loading additional data if the default data is not desired.
 
153
 
 
154
   The optional *filenames* parameter can be used to cause additional files to be
 
155
   loaded "on top" of the default database.
 
156
 
 
157
 
 
158
An example usage of the module::
 
159
 
 
160
   >>> import mimetypes
 
161
   >>> mimetypes.init()
 
162
   >>> mimetypes.knownfiles
 
163
   ['/etc/mime.types', '/etc/httpd/mime.types', ... ]
 
164
   >>> mimetypes.suffix_map['.tgz']
 
165
   '.tar.gz'
 
166
   >>> mimetypes.encodings_map['.gz']
 
167
   'gzip'
 
168
   >>> mimetypes.types_map['.tgz']
 
169
   'application/x-tar-gz'
 
170
 
 
171
 
 
172
.. _mimetypes-objects:
 
173
 
 
174
MimeTypes Objects
 
175
-----------------
 
176
 
 
177
:class:`MimeTypes` instances provide an interface which is very like that of the
 
178
:mod:`mimetypes` module.
 
179
 
 
180
 
 
181
.. attribute:: MimeTypes.suffix_map
 
182
 
 
183
   Dictionary mapping suffixes to suffixes.  This is used to allow recognition of
 
184
   encoded files for which the encoding and the type are indicated by the same
 
185
   extension.  For example, the :file:`.tgz` extension is mapped to :file:`.tar.gz`
 
186
   to allow the encoding and type to be recognized separately.  This is initially a
 
187
   copy of the global ``suffix_map`` defined in the module.
 
188
 
 
189
 
 
190
.. attribute:: MimeTypes.encodings_map
 
191
 
 
192
   Dictionary mapping filename extensions to encoding types.  This is initially a
 
193
   copy of the global ``encodings_map`` defined in the module.
 
194
 
 
195
 
 
196
.. attribute:: MimeTypes.types_map
 
197
 
 
198
   Dictionary mapping filename extensions to MIME types.  This is initially a copy
 
199
   of the global ``types_map`` defined in the module.
 
200
 
 
201
 
 
202
.. attribute:: MimeTypes.common_types
 
203
 
 
204
   Dictionary mapping filename extensions to non-standard, but commonly found MIME
 
205
   types.  This is initially a copy of the global ``common_types`` defined in the
 
206
   module.
 
207
 
 
208
 
 
209
.. method:: MimeTypes.guess_extension(type[, strict])
 
210
 
 
211
   Similar to the :func:`guess_extension` function, using the tables stored as part
 
212
   of the object.
 
213
 
 
214
 
 
215
.. method:: MimeTypes.guess_type(url[, strict])
 
216
 
 
217
   Similar to the :func:`guess_type` function, using the tables stored as part of
 
218
   the object.
 
219
 
 
220
 
 
221
.. method:: MimeTypes.read(path)
 
222
 
 
223
   Load MIME information from a file named *path*.  This uses :meth:`readfp` to
 
224
   parse the file.
 
225
 
 
226
 
 
227
.. method:: MimeTypes.readfp(file)
 
228
 
 
229
   Load MIME type information from an open file.  The file must have the format of
 
230
   the standard :file:`mime.types` files.
 
231