233 lines
8.2 KiB
ReStructuredText
233 lines
8.2 KiB
ReStructuredText
|
|
:mod:`mimetypes` --- Map filenames to MIME types
|
|
================================================
|
|
|
|
.. module:: mimetypes
|
|
:synopsis: Mapping of filename extensions to MIME types.
|
|
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
|
|
|
|
|
|
.. index:: pair: MIME; content type
|
|
|
|
The :mod:`mimetypes` module converts between a filename or URL and the MIME type
|
|
associated with the filename extension. Conversions are provided from filename
|
|
to MIME type and from MIME type to filename extension; encodings are not
|
|
supported for the latter conversion.
|
|
|
|
The module provides one class and a number of convenience functions. The
|
|
functions are the normal interface to this module, but some applications may be
|
|
interested in the class as well.
|
|
|
|
The functions described below provide the primary interface for this module. If
|
|
the module has not been initialized, they will call :func:`init` if they rely on
|
|
the information :func:`init` sets up.
|
|
|
|
|
|
.. function:: guess_type(filename[, strict])
|
|
|
|
.. index:: pair: MIME; headers
|
|
|
|
Guess the type of a file based on its filename or URL, given by *filename*. The
|
|
return value is a tuple ``(type, encoding)`` where *type* is ``None`` if the
|
|
type can't be guessed (missing or unknown suffix) or a string of the form
|
|
``'type/subtype'``, usable for a MIME :mailheader:`content-type` header.
|
|
|
|
*encoding* is ``None`` for no encoding or the name of the program used to encode
|
|
(e.g. :program:`compress` or :program:`gzip`). The encoding is suitable for use
|
|
as a :mailheader:`Content-Encoding` header, *not* as a
|
|
:mailheader:`Content-Transfer-Encoding` header. The mappings are table driven.
|
|
Encoding suffixes are case sensitive; type suffixes are first tried case
|
|
sensitively, then case insensitively.
|
|
|
|
Optional *strict* is a flag specifying whether the list of known MIME types
|
|
is limited to only the official types `registered with IANA
|
|
<http://www.isi.edu/in-notes/iana/assignments/media-types>`_ are recognized.
|
|
When *strict* is true (the default), only the IANA types are supported; when
|
|
*strict* is false, some additional non-standard but commonly used MIME types
|
|
are also recognized.
|
|
|
|
|
|
.. function:: guess_all_extensions(type[, strict])
|
|
|
|
Guess the extensions for a file based on its MIME type, given by *type*. The
|
|
return value is a list of strings giving all possible filename extensions,
|
|
including the leading dot (``'.'``). The extensions are not guaranteed to have
|
|
been associated with any particular data stream, but would be mapped to the MIME
|
|
type *type* by :func:`guess_type`.
|
|
|
|
Optional *strict* has the same meaning as with the :func:`guess_type` function.
|
|
|
|
|
|
.. function:: guess_extension(type[, strict])
|
|
|
|
Guess the extension for a file based on its MIME type, given by *type*. The
|
|
return value is a string giving a filename extension, including the leading dot
|
|
(``'.'``). The extension is not guaranteed to have been associated with any
|
|
particular data stream, but would be mapped to the MIME type *type* by
|
|
:func:`guess_type`. If no extension can be guessed for *type*, ``None`` is
|
|
returned.
|
|
|
|
Optional *strict* has the same meaning as with the :func:`guess_type` function.
|
|
|
|
Some additional functions and data items are available for controlling the
|
|
behavior of the module.
|
|
|
|
|
|
.. function:: init([files])
|
|
|
|
Initialize the internal data structures. If given, *files* must be a sequence
|
|
of file names which should be used to augment the default type map. If omitted,
|
|
the file names to use are taken from :const:`knownfiles`. Each file named in
|
|
*files* or :const:`knownfiles` takes precedence over those named before it.
|
|
Calling :func:`init` repeatedly is allowed.
|
|
|
|
|
|
.. function:: read_mime_types(filename)
|
|
|
|
Load the type map given in the file *filename*, if it exists. The type map is
|
|
returned as a dictionary mapping filename extensions, including the leading dot
|
|
(``'.'``), to strings of the form ``'type/subtype'``. If the file *filename*
|
|
does not exist or cannot be read, ``None`` is returned.
|
|
|
|
|
|
.. function:: add_type(type, ext[, strict])
|
|
|
|
Add a mapping from the mimetype *type* to the extension *ext*. When the
|
|
extension is already known, the new type will replace the old one. When the type
|
|
is already known the extension will be added to the list of known extensions.
|
|
|
|
When *strict* is True (the default), the mapping will added to the official MIME
|
|
types, otherwise to the non-standard ones.
|
|
|
|
|
|
.. data:: inited
|
|
|
|
Flag indicating whether or not the global data structures have been initialized.
|
|
This is set to true by :func:`init`.
|
|
|
|
|
|
.. data:: knownfiles
|
|
|
|
.. index:: single: file; mime.types
|
|
|
|
List of type map file names commonly installed. These files are typically named
|
|
:file:`mime.types` and are installed in different locations by different
|
|
packages.
|
|
|
|
|
|
.. data:: suffix_map
|
|
|
|
Dictionary mapping suffixes to suffixes. This is used to allow recognition of
|
|
encoded files for which the encoding and the type are indicated by the same
|
|
extension. For example, the :file:`.tgz` extension is mapped to :file:`.tar.gz`
|
|
to allow the encoding and type to be recognized separately.
|
|
|
|
|
|
.. data:: encodings_map
|
|
|
|
Dictionary mapping filename extensions to encoding types.
|
|
|
|
|
|
.. data:: types_map
|
|
|
|
Dictionary mapping filename extensions to MIME types.
|
|
|
|
|
|
.. data:: common_types
|
|
|
|
Dictionary mapping filename extensions to non-standard, but commonly found MIME
|
|
types.
|
|
|
|
The :class:`MimeTypes` class may be useful for applications which may want more
|
|
than one MIME-type database:
|
|
|
|
|
|
.. class:: MimeTypes([filenames])
|
|
|
|
This class represents a MIME-types database. By default, it provides access to
|
|
the same database as the rest of this module. The initial database is a copy of
|
|
that provided by the module, and may be extended by loading additional
|
|
:file:`mime.types`\ -style files into the database using the :meth:`read` or
|
|
:meth:`readfp` methods. The mapping dictionaries may also be cleared before
|
|
loading additional data if the default data is not desired.
|
|
|
|
The optional *filenames* parameter can be used to cause additional files to be
|
|
loaded "on top" of the default database.
|
|
|
|
.. versionadded:: 2.2
|
|
|
|
An example usage of the module::
|
|
|
|
>>> import mimetypes
|
|
>>> mimetypes.init()
|
|
>>> mimetypes.knownfiles
|
|
['/etc/mime.types', '/etc/httpd/mime.types', ... ]
|
|
>>> mimetypes.suffix_map['.tgz']
|
|
'.tar.gz'
|
|
>>> mimetypes.encodings_map['.gz']
|
|
'gzip'
|
|
>>> mimetypes.types_map['.tgz']
|
|
'application/x-tar-gz'
|
|
|
|
|
|
.. _mimetypes-objects:
|
|
|
|
MimeTypes Objects
|
|
-----------------
|
|
|
|
:class:`MimeTypes` instances provide an interface which is very like that of the
|
|
:mod:`mimetypes` module.
|
|
|
|
|
|
.. attribute:: MimeTypes.suffix_map
|
|
|
|
Dictionary mapping suffixes to suffixes. This is used to allow recognition of
|
|
encoded files for which the encoding and the type are indicated by the same
|
|
extension. For example, the :file:`.tgz` extension is mapped to :file:`.tar.gz`
|
|
to allow the encoding and type to be recognized separately. This is initially a
|
|
copy of the global ``suffix_map`` defined in the module.
|
|
|
|
|
|
.. attribute:: MimeTypes.encodings_map
|
|
|
|
Dictionary mapping filename extensions to encoding types. This is initially a
|
|
copy of the global ``encodings_map`` defined in the module.
|
|
|
|
|
|
.. attribute:: MimeTypes.types_map
|
|
|
|
Dictionary mapping filename extensions to MIME types. This is initially a copy
|
|
of the global ``types_map`` defined in the module.
|
|
|
|
|
|
.. attribute:: MimeTypes.common_types
|
|
|
|
Dictionary mapping filename extensions to non-standard, but commonly found MIME
|
|
types. This is initially a copy of the global ``common_types`` defined in the
|
|
module.
|
|
|
|
|
|
.. method:: MimeTypes.guess_extension(type[, strict])
|
|
|
|
Similar to the :func:`guess_extension` function, using the tables stored as part
|
|
of the object.
|
|
|
|
|
|
.. method:: MimeTypes.guess_type(url[, strict])
|
|
|
|
Similar to the :func:`guess_type` function, using the tables stored as part of
|
|
the object.
|
|
|
|
|
|
.. method:: MimeTypes.read(path)
|
|
|
|
Load MIME information from a file named *path*. This uses :meth:`readfp` to
|
|
parse the file.
|
|
|
|
|
|
.. method:: MimeTypes.readfp(file)
|
|
|
|
Load MIME type information from an open file. The file must have the format of
|
|
the standard :file:`mime.types` files.
|
|
|