[Python-checkins] CVS: python/dist/src/Doc/lib libmimetypes.tex,1.7,1.8

[Fred L. Drake]

Update of /cvsroot/python/python/dist/src/Doc/lib
In directory usw-pr-cvs1:/tmp/cvs-serv21733

Modified Files:
	libmimetypes.tex 
Log Message:

Add documentation for the new aspects of the mimetypes module.

This closes the SF bug (feature request) #439710.


Index: libmimetypes.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libmimetypes.tex,v
retrieving revision 1.7
retrieving revision 1.8
diff -C2 -d -r1.7 -r1.8
*** libmimetypes.tex	2001/08/03 18:39:36	1.7
--- libmimetypes.tex	2001/08/03 21:03:14	1.8
***************
*** 14,20 ****
  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
! \function{init()}.
  
  
--- 14,25 ----
  encodings are not supported for the later 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.
  
  
***************
*** 93,94 ****
--- 98,163 ----
  Dictionary mapping filename extensions to 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.
+ \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{methoddesc}{guess_extension}{type}
+   Similar to the \function{guess_extension()} function, using the
+   tables stored as part of the object.
+ \end{methoddesc}
+ 
+ \begin{methoddesc}{guess_type}{url}
+   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}