diff options
Diffstat (limited to 'Doc/library/mimetypes.rst')
| -rw-r--r-- | Doc/library/mimetypes.rst | 232 |
1 files changed, 232 insertions, 0 deletions
diff --git a/Doc/library/mimetypes.rst b/Doc/library/mimetypes.rst new file mode 100644 index 0000000..fd5e12d --- /dev/null +++ b/Doc/library/mimetypes.rst @@ -0,0 +1,232 @@ + +: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 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. + |