| \section{\module{mimetypes} --- |
| Map filenames to MIME types} |
| |
| \declaremodule{standard}{mimetypes} |
| \modulesynopsis{Mapping of filename extensions to MIME types.} |
| \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} |
| |
| |
| \indexii{MIME}{content type} |
| |
| The \module{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 |
| \function{init()} if they rely on the information \function{init()} |
| sets up. |
| |
| |
| \begin{funcdesc}{guess_type}{filename\optional{, strict}} |
| Guess the type of a file based on its filename or URL, given by |
| \var{filename}. The return value is a tuple \code{(\var{type}, |
| \var{encoding})} where \var{type} is \code{None} if the type can't be |
| guessed (missing or unknown suffix) or a string of the form |
| \code{'\var{type}/\var{subtype}'}, usable for a MIME |
| \mailheader{content-type} header\indexii{MIME}{headers}. |
| |
| \var{encoding} is \code{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, \emph{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 \var{strict} is a flag specifying whether the list of known |
| MIME types is limited to only the official types \ulink{registered |
| with IANA}{http://www.isi.edu/in-notes/iana/assignments/media-types} |
| are recognized. When \var{strict} is true (the default), only the |
| IANA types are supported; when \var{strict} is false, some additional |
| non-standard but commonly used MIME types are also recognized. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{guess_all_extensions}{type\optional{, strict}} |
| Guess the extensions for a file based on its MIME type, given by |
| \var{type}. |
| The return value is a list of strings giving all possible filename extensions, |
| including the leading dot (\character{.}). The extensions are not guaranteed |
| to have been associated with any particular data stream, but would be mapped |
| to the MIME type \var{type} by \function{guess_type()}. If no extension can |
| be guessed for \var{type}, \code{None} is returned. |
| |
| Optional \var{strict} has the same meaning as with the |
| \function{guess_type()} function. |
| \end{funcdesc} |
| |
| |
| \begin{funcdesc}{guess_extension}{type\optional{, strict}} |
| Guess the extension for a file based on its MIME type, given by |
| \var{type}. |
| The return value is a string giving a filename extension, including the |
| leading dot (\character{.}). The extension is not guaranteed to have been |
| associated with any particular data stream, but would be mapped to the |
| MIME type \var{type} by \function{guess_type()}. If no extension can |
| be guessed for \var{type}, \code{None} is returned. |
| |
| Optional \var{strict} has the same meaning as with the |
| \function{guess_type()} function. |
| \end{funcdesc} |
| |
| |
| Some additional functions and data items are available for controlling |
| the behavior of the module. |
| |
| |
| \begin{funcdesc}{init}{\optional{files}} |
| Initialize the internal data structures. If given, \var{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 |
| \constant{knownfiles}. Each file named in \var{files} or |
| \constant{knownfiles} takes precedence over those named before it. |
| Calling \function{init()} repeatedly is allowed. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{read_mime_types}{filename} |
| Load the type map given in the file \var{filename}, if it exists. The |
| type map is returned as a dictionary mapping filename extensions, |
| including the leading dot (\character{.}), to strings of the form |
| \code{'\var{type}/\var{subtype}'}. If the file \var{filename} does |
| not exist or cannot be read, \code{None} is returned. |
| \end{funcdesc} |
| |
| |
| \begin{funcdesc}{add_type}{type, ext\optional{, strict}} |
| Add a mapping from the mimetype \var{type} to the extension \var{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 \var{strict} is the mapping will added to the official |
| MIME types, otherwise to the non-standard ones. |
| \end{funcdesc} |
| |
| |
| \begin{datadesc}{inited} |
| Flag indicating whether or not the global data structures have been |
| initialized. This is set to true by \function{init()}. |
| \end{datadesc} |
| |
| \begin{datadesc}{knownfiles} |
| 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.\index{file!mime.types} |
| \end{datadesc} |
| |
| \begin{datadesc}{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. |
| \end{datadesc} |
| |
| \begin{datadesc}{encodings_map} |
| Dictionary mapping filename extensions to encoding types. |
| \end{datadesc} |
| |
| \begin{datadesc}{types_map} |
| Dictionary mapping filename extensions to MIME types. |
| \end{datadesc} |
| |
| \begin{datadesc}{common_types} |
| Dictionary mapping filename extensions to non-standard, but commonly |
| found MIME types. |
| \end{datadesc} |
| |
| |
| The \class{MimeTypes} class may be useful for applications which may |
| want more than one MIME-type database: |
| |
| \begin{classdesc}{MimeTypes}{\optional{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 \method{read()} or \method{readfp()} |
| methods. The mapping dictionaries may also be cleared before |
| loading additional data if the default data is not desired. |
| |
| The optional \var{filenames} parameter can be used to cause |
| additional files to be loaded ``on top'' of the default database. |
| |
| \versionadded{2.2} |
| \end{classdesc} |
| |
| |
| \subsection{MimeTypes Objects \label{mimetypes-objects}} |
| |
| \class{MimeTypes} instances provide an interface which is very like |
| that of the \refmodule{mimetypes} module. |
| |
| \begin{datadesc}{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 |
| \code{suffix_map} defined in the module. |
| \end{datadesc} |
| |
| \begin{datadesc}{encodings_map} |
| Dictionary mapping filename extensions to encoding types. This is |
| initially a copy of the global \code{encodings_map} defined in the |
| module. |
| \end{datadesc} |
| |
| \begin{datadesc}{types_map} |
| Dictionary mapping filename extensions to MIME types. This is |
| initially a copy of the global \code{types_map} defined in the |
| module. |
| \end{datadesc} |
| |
| \begin{datadesc}{common_types} |
| Dictionary mapping filename extensions to non-standard, but commonly |
| found MIME types. This is initially a copy of the global |
| \code{common_types} defined in the module. |
| \end{datadesc} |
| |
| \begin{methoddesc}{guess_extension}{type\optional{, strict}} |
| Similar to the \function{guess_extension()} function, using the |
| tables stored as part of the object. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{guess_type}{url\optional{, strict}} |
| Similar to the \function{guess_type()} function, using the tables |
| stored as part of the object. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{read}{path} |
| Load MIME information from a file named \var{path}. This uses |
| \method{readfp()} to parse the file. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{readfp}{file} |
| Load MIME type information from an open file. The file must have |
| the format of the standard \file{mime.types} files. |
| \end{methoddesc} |