Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame] | 1 | \section{\module{mimetypes} --- |
Fred Drake | 86bd5e4 | 1999-04-23 16:02:30 +0000 | [diff] [blame] | 2 | Map filenames to MIME types} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 3 | |
Fred Drake | 180b68b | 1999-02-22 13:45:09 +0000 | [diff] [blame] | 4 | \declaremodule{standard}{mimetypes} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 5 | \modulesynopsis{Mapping of filename extensions to MIME types.} |
Fred Drake | 86bd5e4 | 1999-04-23 16:02:30 +0000 | [diff] [blame] | 6 | \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 7 | |
Fred Drake | 180b68b | 1999-02-22 13:45:09 +0000 | [diff] [blame] | 8 | |
Fred Drake | b818b46 | 1998-05-19 15:03:45 +0000 | [diff] [blame] | 9 | \indexii{MIME}{content type} |
| 10 | |
Barry Warsaw | 107771a | 2001-10-25 21:49:18 +0000 | [diff] [blame] | 11 | The \module{mimetypes} module converts between a filename or URL and |
| 12 | the MIME type associated with the filename extension. Conversions are |
| 13 | provided from filename to MIME type and from MIME type to filename |
| 14 | extension; encodings are not supported for the latter conversion. |
Fred Drake | b818b46 | 1998-05-19 15:03:45 +0000 | [diff] [blame] | 15 | |
Fred Drake | d5efb17 | 2001-08-03 21:03:14 +0000 | [diff] [blame] | 16 | The module provides one class and a number of convenience functions. |
| 17 | The functions are the normal interface to this module, but some |
| 18 | applications may be interested in the class as well. |
| 19 | |
Fred Drake | b818b46 | 1998-05-19 15:03:45 +0000 | [diff] [blame] | 20 | The functions described below provide the primary interface for this |
Fred Drake | 86bd5e4 | 1999-04-23 16:02:30 +0000 | [diff] [blame] | 21 | module. If the module has not been initialized, they will call |
Fred Drake | d5efb17 | 2001-08-03 21:03:14 +0000 | [diff] [blame] | 22 | \function{init()} if they rely on the information \function{init()} |
| 23 | sets up. |
Fred Drake | b818b46 | 1998-05-19 15:03:45 +0000 | [diff] [blame] | 24 | |
| 25 | |
Barry Warsaw | 107771a | 2001-10-25 21:49:18 +0000 | [diff] [blame] | 26 | \begin{funcdesc}{guess_type}{filename\optional{, strict}} |
Fred Drake | b818b46 | 1998-05-19 15:03:45 +0000 | [diff] [blame] | 27 | Guess the type of a file based on its filename or URL, given by |
Fred Drake | d86038d | 2001-08-03 18:39:36 +0000 | [diff] [blame] | 28 | \var{filename}. The return value is a tuple \code{(\var{type}, |
| 29 | \var{encoding})} where \var{type} is \code{None} if the type can't be |
Barry Warsaw | 107771a | 2001-10-25 21:49:18 +0000 | [diff] [blame] | 30 | guessed (missing or unknown suffix) or a string of the form |
Fred Drake | d86038d | 2001-08-03 18:39:36 +0000 | [diff] [blame] | 31 | \code{'\var{type}/\var{subtype}'}, usable for a MIME |
Barry Warsaw | 107771a | 2001-10-25 21:49:18 +0000 | [diff] [blame] | 32 | \mailheader{content-type} header\indexii{MIME}{headers}. |
| 33 | |
| 34 | \var{encoding} is \code{None} for no encoding or the name of the |
| 35 | program used to encode (e.g. \program{compress} or \program{gzip}). |
| 36 | The encoding is suitable for use as a \mailheader{Content-Encoding} |
| 37 | header, \emph{not} as a \mailheader{Content-Transfer-Encoding} header. |
| 38 | The mappings are table driven. Encoding suffixes are case sensitive; |
| 39 | type suffixes are first tried case sensitively, then case |
| 40 | insensitively. |
| 41 | |
| 42 | Optional \var{strict} is a flag specifying whether the list of known |
| 43 | MIME types is limited to only the official types \ulink{registered |
| 44 | with IANA}{http://www.isi.edu/in-notes/iana/assignments/media-types} |
| 45 | are recognized. When \var{strict} is true (the default), only the |
| 46 | IANA types are supported; when \var{strict} is false, some additional |
| 47 | non-standard but commonly used MIME types are also recognized. |
Fred Drake | b818b46 | 1998-05-19 15:03:45 +0000 | [diff] [blame] | 48 | \end{funcdesc} |
| 49 | |
Barry Warsaw | 107771a | 2001-10-25 21:49:18 +0000 | [diff] [blame] | 50 | \begin{funcdesc}{guess_extension}{type\optional{, strict}} |
Fred Drake | b818b46 | 1998-05-19 15:03:45 +0000 | [diff] [blame] | 51 | Guess the extension for a file based on its MIME type, given by |
| 52 | \var{type}. |
| 53 | The return value is a string giving a filename extension, including the |
| 54 | leading dot (\character{.}). The extension is not guaranteed to have been |
| 55 | associated with any particular data stream, but would be mapped to the |
| 56 | MIME type \var{type} by \function{guess_type()}. If no extension can |
| 57 | be guessed for \var{type}, \code{None} is returned. |
Barry Warsaw | 107771a | 2001-10-25 21:49:18 +0000 | [diff] [blame] | 58 | |
| 59 | Optional \var{strict} has the same meaning as with the |
| 60 | \function{guess_type()} function. |
Fred Drake | b818b46 | 1998-05-19 15:03:45 +0000 | [diff] [blame] | 61 | \end{funcdesc} |
| 62 | |
| 63 | |
| 64 | Some additional functions and data items are available for controlling |
| 65 | the behavior of the module. |
| 66 | |
| 67 | |
| 68 | \begin{funcdesc}{init}{\optional{files}} |
| 69 | Initialize the internal data structures. If given, \var{files} must |
| 70 | be a sequence of file names which should be used to augment the |
| 71 | default type map. If omitted, the file names to use are taken from |
Fred Drake | d86038d | 2001-08-03 18:39:36 +0000 | [diff] [blame] | 72 | \constant{knownfiles}. Each file named in \var{files} or |
| 73 | \constant{knownfiles} takes precedence over those named before it. |
Fred Drake | b818b46 | 1998-05-19 15:03:45 +0000 | [diff] [blame] | 74 | Calling \function{init()} repeatedly is allowed. |
| 75 | \end{funcdesc} |
| 76 | |
| 77 | \begin{funcdesc}{read_mime_types}{filename} |
| 78 | Load the type map given in the file \var{filename}, if it exists. The |
| 79 | type map is returned as a dictionary mapping filename extensions, |
| 80 | including the leading dot (\character{.}), to strings of the form |
| 81 | \code{'\var{type}/\var{subtype}'}. If the file \var{filename} does |
| 82 | not exist or cannot be read, \code{None} is returned. |
| 83 | \end{funcdesc} |
| 84 | |
| 85 | |
| 86 | \begin{datadesc}{inited} |
| 87 | Flag indicating whether or not the global data structures have been |
| 88 | initialized. This is set to true by \function{init()}. |
| 89 | \end{datadesc} |
| 90 | |
| 91 | \begin{datadesc}{knownfiles} |
| 92 | List of type map file names commonly installed. These files are |
Fred Drake | 86bd5e4 | 1999-04-23 16:02:30 +0000 | [diff] [blame] | 93 | typically named \file{mime.types} and are installed in different |
| 94 | locations by different packages.\index{file!mime.types} |
Fred Drake | b818b46 | 1998-05-19 15:03:45 +0000 | [diff] [blame] | 95 | \end{datadesc} |
| 96 | |
| 97 | \begin{datadesc}{suffix_map} |
| 98 | Dictionary mapping suffixes to suffixes. This is used to allow |
| 99 | recognition of encoded files for which the encoding and the type are |
| 100 | indicated by the same extension. For example, the \file{.tgz} |
| 101 | extension is mapped to \file{.tar.gz} to allow the encoding and type |
| 102 | to be recognized separately. |
| 103 | \end{datadesc} |
| 104 | |
| 105 | \begin{datadesc}{encodings_map} |
| 106 | Dictionary mapping filename extensions to encoding types. |
| 107 | \end{datadesc} |
| 108 | |
| 109 | \begin{datadesc}{types_map} |
| 110 | Dictionary mapping filename extensions to MIME types. |
| 111 | \end{datadesc} |
Fred Drake | d5efb17 | 2001-08-03 21:03:14 +0000 | [diff] [blame] | 112 | |
Barry Warsaw | 107771a | 2001-10-25 21:49:18 +0000 | [diff] [blame] | 113 | \begin{datadesc}{common_types} |
| 114 | Dictionary mapping filename extensions to non-standard, but commonly |
| 115 | found MIME types. |
| 116 | \end{datadesc} |
| 117 | |
Fred Drake | d5efb17 | 2001-08-03 21:03:14 +0000 | [diff] [blame] | 118 | |
| 119 | The \class{MimeTypes} class may be useful for applications which may |
| 120 | want more than one MIME-type database: |
| 121 | |
| 122 | \begin{classdesc}{MimeTypes}{\optional{filenames}} |
| 123 | This class represents a MIME-types database. By default, it |
| 124 | provides access to the same database as the rest of this module. |
| 125 | The initial database is a copy of that provided by the module, and |
| 126 | may be extended by loading additional \file{mime.types}-style files |
| 127 | into the database using the \method{read()} or \method{readfp()} |
| 128 | methods. The mapping dictionaries may also be cleared before |
| 129 | loading additional data if the default data is not desired. |
| 130 | |
| 131 | The optional \var{filenames} parameter can be used to cause |
| 132 | additional files to be loaded ``on top'' of the default database. |
Fred Drake | b3cc29b | 2001-08-04 00:48:49 +0000 | [diff] [blame] | 133 | |
| 134 | \versionadded{2.2} |
Fred Drake | d5efb17 | 2001-08-03 21:03:14 +0000 | [diff] [blame] | 135 | \end{classdesc} |
| 136 | |
| 137 | |
| 138 | \subsection{MimeTypes Objects \label{mimetypes-objects}} |
| 139 | |
| 140 | \class{MimeTypes} instances provide an interface which is very like |
| 141 | that of the \refmodule{mimetypes} module. |
| 142 | |
| 143 | \begin{datadesc}{suffix_map} |
| 144 | Dictionary mapping suffixes to suffixes. This is used to allow |
| 145 | recognition of encoded files for which the encoding and the type are |
| 146 | indicated by the same extension. For example, the \file{.tgz} |
| 147 | extension is mapped to \file{.tar.gz} to allow the encoding and type |
| 148 | to be recognized separately. This is initially a copy of the global |
| 149 | \code{suffix_map} defined in the module. |
| 150 | \end{datadesc} |
| 151 | |
| 152 | \begin{datadesc}{encodings_map} |
| 153 | Dictionary mapping filename extensions to encoding types. This is |
| 154 | initially a copy of the global \code{encodings_map} defined in the |
| 155 | module. |
| 156 | \end{datadesc} |
| 157 | |
| 158 | \begin{datadesc}{types_map} |
| 159 | Dictionary mapping filename extensions to MIME types. This is |
| 160 | initially a copy of the global \code{types_map} defined in the |
| 161 | module. |
| 162 | \end{datadesc} |
| 163 | |
Barry Warsaw | 107771a | 2001-10-25 21:49:18 +0000 | [diff] [blame] | 164 | \begin{datadesc}{common_types} |
| 165 | Dictionary mapping filename extensions to non-standard, but commonly |
| 166 | found MIME types. This is initially a copy of the global |
| 167 | \code{common_types} defined in the module. |
| 168 | \end{datadesc} |
| 169 | |
| 170 | \begin{methoddesc}{guess_extension}{type\optional{, strict}} |
Fred Drake | d5efb17 | 2001-08-03 21:03:14 +0000 | [diff] [blame] | 171 | Similar to the \function{guess_extension()} function, using the |
| 172 | tables stored as part of the object. |
| 173 | \end{methoddesc} |
| 174 | |
Barry Warsaw | 107771a | 2001-10-25 21:49:18 +0000 | [diff] [blame] | 175 | \begin{methoddesc}{guess_type}{url\optional{, strict}} |
Fred Drake | d5efb17 | 2001-08-03 21:03:14 +0000 | [diff] [blame] | 176 | Similar to the \function{guess_type()} function, using the tables |
| 177 | stored as part of the object. |
| 178 | \end{methoddesc} |
| 179 | |
| 180 | \begin{methoddesc}{read}{path} |
| 181 | Load MIME information from a file named \var{path}. This uses |
| 182 | \method{readfp()} to parse the file. |
| 183 | \end{methoddesc} |
| 184 | |
| 185 | \begin{methoddesc}{readfp}{file} |
| 186 | Load MIME type information from an open file. The file must have |
| 187 | the format of the standard \file{mime.types} files. |
| 188 | \end{methoddesc} |