← Back to branch summary

~ubuntu-branches/ubuntu/trusty/python3.4/trusty-proposed

« back to all changes in this revision

Viewing changes to Doc/library/mimetypes.rst

  • Committer: Package Import Robot
  • Author(s): Matthias Klose
  • Date: 2013-11-25 09:44:27 UTC
  • Revision ID: package-import@ubuntu.com-20131125094427-lzxj8ap5w01lmo7f
Tags: upstream-3.4~b1
Import upstream version 3.4~b1

Show diffs side-by-side

added added

removed removed

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