diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex index 5ee098e4472..4f46bf7f7bb 100644 --- a/Doc/lib/lib.tex +++ b/Doc/lib/lib.tex @@ -173,6 +173,7 @@ add new extensions to Python and how to embed it in other applications. \input{libbinascii} \input{libxdrlib} \input{libmailcap} +\input{libmimetypes} \input{libbase64} \input{libquopri} \input{libsocksvr} diff --git a/Doc/lib/libmimetypes.tex b/Doc/lib/libmimetypes.tex new file mode 100644 index 00000000000..6cfd8534ae3 --- /dev/null +++ b/Doc/lib/libmimetypes.tex @@ -0,0 +1,94 @@ +% This document section was written by Fred L. Drake, Jr. +% , based in part on original docstrings in the +% mimetypes module. + +\section{Standard Module \module{mimetypes}} +\label{module-mimetypes} +\stmodindex{mimetypes} +\indexii{MIME}{content type} + +The \module{mimetypes} 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 later conversion. + +The functions described below provide the primary interface for this +module. If the module has not been initialized, they will call the +\function{init()}. + + +\begin{funcdesc}{guess_type}{filename} +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 (no or unknown +suffix) or a string of the form \code{'\var{type}/\var{subtype}'}, +usable for a MIME \code{content-type} header\indexii{MIME}{headers}; and +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 \code{content-encoding} header, +\emph{not} as a \code{content-transfer-encoding} header. The mappings +are table driven. Encoding suffixes are case sensitive; type suffixes +are first tried case sensitive, then case insensitive. +\end{funcdesc} + +\begin{funcdesc}{guess_extension}{type} +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. +\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 +\code{knownfiles}. Each file named in \var{files} or +\code{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{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 names \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}