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    .. versionadded:: 2.2
 158
 159 An example usage of the module::
 160
 161    >>> import mimetypes
 162    >>> mimetypes.init()
 163    >>> mimetypes.knownfiles
 164    ['/etc/mime.types', '/etc/httpd/mime.types', ... ]
 165    >>> mimetypes.suffix_map['.tgz']
 166    '.tar.gz'
 167    >>> mimetypes.encodings_map['.gz']
 168    'gzip'
 169    >>> mimetypes.types_map['.tgz']
 170    'application/x-tar-gz'
 171
 172
 173 .. _mimetypes-objects:
 174
 175 MimeTypes Objects
 176 -----------------
 177
 178 :class:`MimeTypes` instances provide an interface which is very like that of the
 179 :mod:`mimetypes` module.
 180
 181
 182 .. attribute:: MimeTypes.suffix_map
 183
 184    Dictionary mapping suffixes to suffixes.  This is used to allow recognition of
 185    encoded files for which the encoding and the type are indicated by the same
 186    extension.  For example, the :file:`.tgz` extension is mapped to :file:`.tar.gz`
 187    to allow the encoding and type to be recognized separately.  This is initially a
 188    copy of the global ``suffix_map`` defined in the module.
 189
 190
 191 .. attribute:: MimeTypes.encodings_map
 192
 193    Dictionary mapping filename extensions to encoding types.  This is initially a
 194    copy of the global ``encodings_map`` defined in the module.
 195
 196
 197 .. attribute:: MimeTypes.types_map
 198
 199    Dictionary mapping filename extensions to MIME types.  This is initially a copy
 200    of the global ``types_map`` defined in the module.
 201
 202
 203 .. attribute:: MimeTypes.common_types
 204
 205    Dictionary mapping filename extensions to non-standard, but commonly found MIME
 206    types.  This is initially a copy of the global ``common_types`` defined in the
 207    module.
 208
 209
 210 .. method:: MimeTypes.guess_extension(type[, strict])
 211
 212    Similar to the :func:`guess_extension` function, using the tables stored as part
 213    of the object.
 214
 215
 216 .. method:: MimeTypes.guess_type(url[, strict])
 217
 218    Similar to the :func:`guess_type` function, using the tables stored as part of
 219    the object.
 220
 221
 222 .. method:: MimeTypes.read(path)
 223
 224    Load MIME information from a file named *path*.  This uses :meth:`readfp` to
 225    parse the file.
 226
 227
 228 .. method:: MimeTypes.readfp(file)
 229
 230    Load MIME type information from an open file.  The file must have the format of
 231    the standard :file:`mime.types` files.
 232