Debian Codegraph @

Doc/library/mimetypes.rst

raw
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. <[email protected]>
8
9 **Source code:** :source:`Lib/mimetypes.py`
10
11 .. index:: pair: MIME; content type
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, path or URL, given by *url*.
34 URL can be a string or a :term:`path-like object`.
35
36 The return value is a tuple ``(type, encoding)`` where *type* is ``None`` if the
37 type can't be guessed (missing or unknown suffix) or a string of the form
38 ``'type/subtype'``, usable for a MIME :mailheader:`content-type` header.
39
40 *encoding* is ``None`` for no encoding or the name of the program used to encode
41 (e.g. :program:`compress` or :program:`gzip`). The encoding is suitable for use
42 as a :mailheader:`Content-Encoding` header, **not** as a
43 :mailheader:`Content-Transfer-Encoding` header. The mappings are table driven.
44 Encoding suffixes are case sensitive; type suffixes are first tried case
45 sensitively, then case insensitively.
46
47 The optional *strict* argument is a flag specifying whether the list of known MIME types
48 is limited to only the official types `registered with IANA
49 <https://www.iana.org/assignments/media-types/media-types.xhtml>`_.
50 When *strict* is ``True`` (the default), only the IANA types are supported; when
51 *strict* is ``False``, some additional non-standard but commonly used MIME types
52 are also recognized.
53
54 .. versionchanged:: 3.8
55 Added support for *url* being a :term:`path-like object`.
56
57 .. soft-deprecated:: 3.13
58 Passing a file path instead of URL is :term:`soft deprecated`.
59 Use :func:`guess_file_type` for this.
60
61
62 .. function:: guess_file_type(path, *, strict=True)
63
64 .. index:: pair: MIME; headers
65
66 Guess the type of a file based on its path, given by *path*.
67 Similar to the :func:`guess_type` function, but accepts a path instead of URL.
68 Path can be a string, a bytes object or a :term:`path-like object`.
69
70 .. versionadded:: 3.13
71
72
73 .. function:: guess_all_extensions(type, strict=True)
74
75 Guess the extensions for a file based on its MIME type, given by *type*. The
76 return value is a list of strings giving all possible filename extensions,
77 including the leading dot (``'.'``). The extensions are not guaranteed to have
78 been associated with any particular data stream, but would be mapped to the MIME
79 type *type* by :func:`guess_type` and :func:`guess_file_type`.
80
81 The optional *strict* argument has the same meaning as with the :func:`guess_type` function.
82
83
84 .. function:: guess_extension(type, strict=True)
85
86 Guess the extension for a file based on its MIME type, given by *type*. The
87 return value is a string giving a filename extension, including the leading dot
88 (``'.'``). The extension is not guaranteed to have been associated with any
89 particular data stream, but would be mapped to the MIME type *type* by
90 :func:`guess_type` and :func:`guess_file_type`.
91 If no extension can be guessed for *type*, ``None`` is returned.
92
93 The optional *strict* argument has the same meaning as with the :func:`guess_type` function.
94
95 Some additional functions and data items are available for controlling the
96 behavior of the module.
97
98
99 .. function:: init(files=None)
100
101 Initialize the internal data structures. If given, *files* must be a sequence
102 of file names which should be used to augment the default type map. If omitted,
103 the file names to use are taken from :const:`knownfiles`; on Windows, the
104 current registry settings are loaded. Each file named in *files* or
105 :const:`knownfiles` takes precedence over those named before it. Calling
106 :func:`init` repeatedly is allowed.
107
108 Specifying an empty list for *files* will prevent the system defaults from
109 being applied: only the well-known values will be present from a built-in list.
110
111 If *files* is ``None`` the internal data structure is completely rebuilt to its
112 initial default value. This is a stable operation and will produce the same results
113 when called multiple times.
114
115 .. versionchanged:: 3.2
116 Previously, Windows registry settings were ignored.
117
118
119 .. function:: read_mime_types(file)
120
121 Load the type map given in the file named by *file*, if it exists. *file*
122 must be a string specifying the name of the file to read. The type map is
123 returned as a dictionary mapping file extensions, including the leading dot
124 (``'.'``), to strings of the form ``'type/subtype'``. If the file does not
125 exist or cannot be read, ``None`` is returned.
126
127
128 .. function:: add_type(type, ext, strict=True)
129
130 Add a mapping from the MIME type *type* to the extension *ext*. When the
131 extension is already known, the new type will replace the old one. When the type
132 is already known the extension will be added to the list of known extensions.
133
134 When *strict* is ``True`` (the default), the mapping will be added to the
135 official MIME types, otherwise to the non-standard ones.
136
137
138 .. data:: inited
139
140 Flag indicating whether or not the global data structures have been initialized.
141 This is set to ``True`` by :func:`init`.
142
143
144 .. data:: knownfiles
145
146 .. index:: single: file; mime.types
147
148 List of type map file names commonly installed. These files are typically named
149 :file:`mime.types` and are installed in different locations by different
150 packages.
151
152
153 .. data:: suffix_map
154
155 Dictionary mapping suffixes to suffixes. This is used to allow recognition of
156 encoded files for which the encoding and the type are indicated by the same
157 extension. For example, the :file:`.tgz` extension is mapped to :file:`.tar.gz`
158 to allow the encoding and type to be recognized separately.
159
160
161 .. data:: encodings_map
162
163 Dictionary mapping filename extensions to encoding types.
164
165
166 .. data:: types_map
167
168 Dictionary mapping filename extensions to MIME types.
169
170
171 .. data:: common_types
172
173 Dictionary mapping filename extensions to non-standard, but commonly found MIME
174 types.
175
176
177 An example usage of the module::
178
179 >>> import mimetypes
180 >>> mimetypes.init()
181 >>> mimetypes.knownfiles
182 ['/etc/mime.types', '/etc/httpd/mime.types', ... ]
183 >>> mimetypes.suffix_map['.tgz']
184 '.tar.gz'
185 >>> mimetypes.encodings_map['.gz']
186 'gzip'
187 >>> mimetypes.types_map['.tgz']
188 'application/x-tar-gz'
189
190
191 .. _mimetypes-objects:
192
193 MimeTypes Objects
194 -----------------
195
196 The :class:`MimeTypes` class may be useful for applications which may want more
197 than one MIME-type database; it provides an interface similar to the one of the
198 :mod:`mimetypes` module.
199
200
201 .. class:: MimeTypes(filenames=(), strict=True)
202
203 This class represents a MIME-types database. By default, it provides access to
204 the same database as the rest of this module. The initial database is a copy of
205 that provided by the module, and may be extended by loading additional
206 :file:`mime.types`\ -style files into the database using the :meth:`read` or
207 :meth:`readfp` methods. The mapping dictionaries may also be cleared before
208 loading additional data if the default data is not desired.
209
210 The optional *filenames* parameter can be used to cause additional files to be
211 loaded "on top" of the default database.
212
213
214 .. attribute:: MimeTypes.suffix_map
215
216 Dictionary mapping suffixes to suffixes. This is used to allow recognition of
217 encoded files for which the encoding and the type are indicated by the same
218 extension. For example, the :file:`.tgz` extension is mapped to :file:`.tar.gz`
219 to allow the encoding and type to be recognized separately. This is initially a
220 copy of the global :data:`suffix_map` defined in the module.
221
222
223 .. attribute:: MimeTypes.encodings_map
224
225 Dictionary mapping filename extensions to encoding types. This is initially a
226 copy of the global :data:`encodings_map` defined in the module.
227
228
229 .. attribute:: MimeTypes.types_map
230
231 Tuple containing two dictionaries, mapping filename extensions to MIME types:
232 the first dictionary is for the non-standards types and the second one is for
233 the standard types. They are initialized by :data:`common_types` and
234 :data:`types_map`.
235
236
237 .. attribute:: MimeTypes.types_map_inv
238
239 Tuple containing two dictionaries, mapping MIME types to a list of filename
240 extensions: the first dictionary is for the non-standards types and the
241 second one is for the standard types. They are initialized by
242 :data:`common_types` and :data:`types_map`.
243
244
245 .. method:: MimeTypes.guess_extension(type, strict=True)
246
247 Similar to the :func:`guess_extension` function, using the tables stored as part
248 of the object.
249
250
251 .. method:: MimeTypes.guess_type(url, strict=True)
252
253 Similar to the :func:`guess_type` function, using the tables stored as part of
254 the object.
255
256
257 .. method:: MimeTypes.guess_file_type(path, *, strict=True)
258
259 Similar to the :func:`guess_file_type` function, using the tables stored
260 as part of the object.
261
262 .. versionadded:: 3.13
263
264
265 .. method:: MimeTypes.guess_all_extensions(type, strict=True)
266
267 Similar to the :func:`guess_all_extensions` function, using the tables stored
268 as part of the object.
269
270
271 .. method:: MimeTypes.read(filename, strict=True)
272
273 Load MIME information from a file named *filename*. This uses :meth:`readfp` to
274 parse the file.
275
276 If *strict* is ``True``, information will be added to list of standard types,
277 else to the list of non-standard types.
278
279
280 .. method:: MimeTypes.readfp(fp, strict=True)
281
282 Load MIME type information from an open file *fp*. The file must have the format of
283 the standard :file:`mime.types` files.
284
285 If *strict* is ``True``, information will be added to the list of standard
286 types, else to the list of non-standard types.
287
288
289 .. method:: MimeTypes.read_windows_registry(strict=True)
290
291 Load MIME type information from the Windows registry.
292
293 .. availability:: Windows.
294
295 If *strict* is ``True``, information will be added to the list of standard
296 types, else to the list of non-standard types.
297
298 .. versionadded:: 3.2
299
300
301 .. method:: MimeTypes.add_type(type, ext, strict=True)
302
303 Add a mapping from the MIME type *type* to the extension *ext*. When the
304 extension is already known, the new type will replace the old one. When the type
305 is already known the extension will be added to the list of known extensions.
306
307 When *strict* is ``True`` (the default), the mapping will be added to the
308 official MIME types, otherwise to the non-standard ones.