1:mod:`mimetypes` --- Map filenames to MIME types
2================================================
3
4.. module:: mimetypes
5   :synopsis: Mapping of filename extensions to MIME types.
6
7.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
8
9**Source code:** :source:`Lib/mimetypes.py`
10
11.. index:: pair: MIME; content type
12
13--------------
14
15The :mod:`mimetypes` module converts between a filename or URL and the MIME type
16associated with the filename extension.  Conversions are provided from filename
17to MIME type and from MIME type to filename extension; encodings are not
18supported for the latter conversion.
19
20The module provides one class and a number of convenience functions. The
21functions are the normal interface to this module, but some applications may be
22interested in the class as well.
23
24The functions described below provide the primary interface for this module.  If
25the module has not been initialized, they will call :func:`init` if they rely on
26the 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   <https://www.iana.org/assignments/media-types/media-types.xhtml>`_.
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
75Some additional functions and data items are available for controlling the
76behavior 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   If *files* is ``None`` the internal data structure is completely rebuilt to its
92   initial default value. This is a stable operation and will produce the same results
93   when called multiple times.
94
95   .. versionchanged:: 3.2
96      Previously, Windows registry settings were ignored.
97
98
99.. function:: read_mime_types(filename)
100
101   Load the type map given in the file *filename*, if it exists.  The type map is
102   returned as a dictionary mapping filename extensions, including the leading dot
103   (``'.'``), to strings of the form ``'type/subtype'``.  If the file *filename*
104   does not exist or cannot be read, ``None`` is returned.
105
106
107.. function:: add_type(type, ext, strict=True)
108
109   Add a mapping from the MIME type *type* to the extension *ext*. When the
110   extension is already known, the new type will replace the old one. When the type
111   is already known the extension will be added to the list of known extensions.
112
113   When *strict* is ``True`` (the default), the mapping will be added to the
114   official MIME types, otherwise to the non-standard ones.
115
116
117.. data:: inited
118
119   Flag indicating whether or not the global data structures have been initialized.
120   This is set to ``True`` by :func:`init`.
121
122
123.. data:: knownfiles
124
125   .. index:: single: file; mime.types
126
127   List of type map file names commonly installed.  These files are typically named
128   :file:`mime.types` and are installed in different locations by different
129   packages.
130
131
132.. data:: suffix_map
133
134   Dictionary mapping suffixes to suffixes.  This is used to allow recognition of
135   encoded files for which the encoding and the type are indicated by the same
136   extension.  For example, the :file:`.tgz` extension is mapped to :file:`.tar.gz`
137   to allow the encoding and type to be recognized separately.
138
139
140.. data:: encodings_map
141
142   Dictionary mapping filename extensions to encoding types.
143
144
145.. data:: types_map
146
147   Dictionary mapping filename extensions to MIME types.
148
149
150.. data:: common_types
151
152   Dictionary mapping filename extensions to non-standard, but commonly found MIME
153   types.
154
155
156An example usage of the module::
157
158   >>> import mimetypes
159   >>> mimetypes.init()
160   >>> mimetypes.knownfiles
161   ['/etc/mime.types', '/etc/httpd/mime.types', ... ]
162   >>> mimetypes.suffix_map['.tgz']
163   '.tar.gz'
164   >>> mimetypes.encodings_map['.gz']
165   'gzip'
166   >>> mimetypes.types_map['.tgz']
167   'application/x-tar-gz'
168
169
170.. _mimetypes-objects:
171
172MimeTypes Objects
173-----------------
174
175The :class:`MimeTypes` class may be useful for applications which may want more
176than one MIME-type database; it provides an interface similar to the one of the
177:mod:`mimetypes` module.
178
179
180.. class:: MimeTypes(filenames=(), strict=True)
181
182   This class represents a MIME-types database.  By default, it provides access to
183   the same database as the rest of this module. The initial database is a copy of
184   that provided by the module, and may be extended by loading additional
185   :file:`mime.types`\ -style files into the database using the :meth:`read` or
186   :meth:`readfp` methods.  The mapping dictionaries may also be cleared before
187   loading additional data if the default data is not desired.
188
189   The optional *filenames* parameter can be used to cause additional files to be
190   loaded "on top" of the default database.
191
192
193   .. attribute:: MimeTypes.suffix_map
194
195      Dictionary mapping suffixes to suffixes.  This is used to allow recognition of
196      encoded files for which the encoding and the type are indicated by the same
197      extension.  For example, the :file:`.tgz` extension is mapped to :file:`.tar.gz`
198      to allow the encoding and type to be recognized separately.  This is initially a
199      copy of the global :data:`suffix_map` defined in the module.
200
201
202   .. attribute:: MimeTypes.encodings_map
203
204      Dictionary mapping filename extensions to encoding types.  This is initially a
205      copy of the global :data:`encodings_map` defined in the module.
206
207
208   .. attribute:: MimeTypes.types_map
209
210      Tuple containing two dictionaries, mapping filename extensions to MIME types:
211      the first dictionary is for the non-standards types and the second one is for
212      the standard types. They are initialized by :data:`common_types` and
213      :data:`types_map`.
214
215
216   .. attribute:: MimeTypes.types_map_inv
217
218      Tuple containing two dictionaries, mapping MIME types to a list of filename
219      extensions: the first dictionary is for the non-standards types and the
220      second one is for the standard types. They are initialized by
221      :data:`common_types` and :data:`types_map`.
222
223
224   .. method:: MimeTypes.guess_extension(type, strict=True)
225
226      Similar to the :func:`guess_extension` function, using the tables stored as part
227      of the object.
228
229
230   .. method:: MimeTypes.guess_type(url, strict=True)
231
232      Similar to the :func:`guess_type` function, using the tables stored as part of
233      the object.
234
235
236   .. method:: MimeTypes.guess_all_extensions(type, strict=True)
237
238      Similar to the :func:`guess_all_extensions` function, using the tables stored
239      as part of the object.
240
241
242   .. method:: MimeTypes.read(filename, strict=True)
243
244      Load MIME information from a file named *filename*.  This uses :meth:`readfp` to
245      parse the file.
246
247      If *strict* is ``True``, information will be added to list of standard types,
248      else to the list of non-standard types.
249
250
251   .. method:: MimeTypes.readfp(fp, strict=True)
252
253      Load MIME type information from an open file *fp*.  The file must have the format of
254      the standard :file:`mime.types` files.
255
256      If *strict* is ``True``, information will be added to the list of standard
257      types, else to the list of non-standard types.
258
259
260   .. method:: MimeTypes.read_windows_registry(strict=True)
261
262      Load MIME type information from the Windows registry.
263
264      .. availability:: Windows.
265
266      If *strict* is ``True``, information will be added to the list of standard
267      types, else to the list of non-standard types.
268
269      .. versionadded:: 3.2
270