[Python-checkins] python/dist/src/Doc/lib libbase64.tex,1.21,1.22

[bwarsaw at users.sourceforge.net]

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

Modified Files:
	libbase64.tex 
Log Message:
Documentation for new RFC 3548 functions.


Index: libbase64.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libbase64.tex,v
retrieving revision 1.21
retrieving revision 1.22
diff -C2 -d -r1.21 -r1.22
*** libbase64.tex	16 May 2002 04:28:44 -0000	1.21
--- libbase64.tex	4 Jan 2004 01:14:01 -0000	1.22
***************
*** 1,7 ****
  \section{\module{base64} ---
!          Encode and decode MIME base64 data}
  
  \declaremodule{standard}{base64}
! \modulesynopsis{Encode and decode files using the MIME base64 data.}
  
  
--- 1,7 ----
  \section{\module{base64} ---
! 	 RFC 3548: Base16, Base32, Base64 Data Encodings}
  
  \declaremodule{standard}{base64}
! \modulesynopsis{RFC 3548: Base16, Base32, Base64 Data Encodings}
  
  
***************
*** 9,24 ****
  \index{MIME!base64 encoding}
  
! This module performs base64 encoding and decoding of arbitrary binary
! strings into text strings that can be safely sent by email or included
! as part of an HTTP POST request.  The
! encoding scheme is defined in \rfc{1521} (\emph{MIME
! (Multipurpose Internet Mail Extensions) Part One: Mechanisms for
! Specifying and Describing the Format of Internet Message Bodies},
! section 5.2, ``Base64 Content-Transfer-Encoding'') and is used for
! MIME email and various other Internet-related applications; it is not
! the same as the output produced by the \program{uuencode} program.
! For example, the string \code{'www.python.org'} is encoded as the
! string \code{'d3d3LnB5dGhvbi5vcmc=\e n'}.  
  
  
  \begin{funcdesc}{decode}{input, output}
--- 9,117 ----
  \index{MIME!base64 encoding}
  
! This module provides data encoding and decoding as specified in
! \rfc{3548}.  This standard defines the Base16, Base32, and Base64
! algorithms for encoding and decoding arbitrary binary strings into
! text strings that can be safely sent by email, used as parts of URLs,
! or included as part of an HTTP POST request.  The encoding algorith is
! not the same as the \program{uuencode} program.
! 
! There are two interfaces provided by this module.  The modern
! interface supports encoding and decoding string objects using all
! three alphabets.  The legacy interface provides for encoding and
! decoding to and from file-like objects as well as strings, but only
! using the Base64 standard alphabet.
! 
! The modern interface provides:
! 
! \begin{funcdesc}{b64encode}{s\optional{, altchars}}
! Encode a string use Base64.
! 
! \var{s} is the string to encode.  Optional \var{altchars} must be a
! string of at least length 2 (additional characters are ignored) which
! specifies an alternative alphabet for the \code{+} and \code{/}
! characters.  This allows an application to e.g. generate URL or
! filesystem safe Base64 strings.  The default is \code{None}, for which
! the standard Base64 alphabet is used.
! 
! The encoded string is returned.
! \end{funcdesc}
! 
! \begin{funcdesc}{b64decode}{s\optional{, altchars}}
! Decode a Base64 encoded string.
  
+ \var{s} is the string to decode.  Optional \var{altchars} must be a
+ string of at least length 2 (additional characters are ignored) which
+ specifies the alternative alphabet used instead of the \code{+} and
+ \code{/} characters.
+ 
+ The decoded string is returned.  A \exception{TypeError} is raised if
+ \var{s} were incorrectly padded or if there are non-alphabet
+ characters present in the string.
+ \end{funcdesc}
+ 
+ \begin{funcdesc}{standard_b64encode}{s}
+ Encode string \var{s} using the standard Base64 alphabet.
+ \end{funcdesc}
+ 
+ \begin{funcdesc}{standard_b64decode}{s}
+ Decode string \var{s} using the standard Base64 alphabet.
+ \end{funcdesc}
+ 
+ \begin{funcdesc}{urlsafe_b64encode}{s}
+ Encode string \var{s} using a URL-safe alphabet, which substitutes
+ \code{-} instead of \code{+} and \code{_} instead of \code{/} in the
+ standard Base64 alphabet.
+ \end{funcdesc}
+ 
+ \begin{funcdesc}{urlsafe_b64decode}{s}
+ Decode string \var{s} using a URL-safe alphabet, which substitutes
+ \code{-} instead of \code{+} and \code{_} instead of \code{/} in the
+ standard Base64 alphabet.
+ \end{funcdesc}
+ 
+ \begin{funcdesc}{b32encode}{s}
+ Encode a string using Base32.  \var{s} is the string to encode.  The
+ encoded string is returned.
+ \end{funcdesc}
+ 
+ \begin{funcdesc}{b32decode}{s\optional{, casefold\optional{, map01}}}
+ Decode a Base32 encoded string.
+ 
+ \var{s} is the string to decode.  Optional \var{casefold} is a flag
+ specifying whether a lowercase alphabet is acceptable as input.  For
+ security purposes, the default is \code{False}.
+ 
+ \rfc{3548} allows for optional mapping of the digit 0 (zero) to the
+ letter O (oh), and for optional mapping of the digit 1 (one) to either
+ the letter I (eye) or letter L (el).  The optional argument
+ \var{map01} when not \code{None}, specifies which letter the digit 1 should
+ be mapped to (when map01 is not \var{None}, the digit 0 is always
+ mapped to the letter O).  For security purposes the default is
+ \code{None}, so that 0 and 1 are not allowed in the input.
+ 
+ The decoded string is returned.  A \exception{TypeError} is raised if
+ \var{s} were incorrectly padded or if there are non-alphabet characters
+ present in the string.
+ \end{funcdesc}
+ 
+ \begin{funcdesc}{b16encode}{s}
+ Encode a string using Base16.
+ 
+ \var{s} is the string to encode.  The encoded string is returned.
+ \end{funcdesc}
+ 
+ \begin{funcdesc}{b16decode}{s\optional{, casefold}}
+ Decode a Base16 encoded string.
+ 
+ \var{s} is the string to decode.  Optional \var{casefold} is a flag
+ specifying whether a lowercase alphabet is acceptable as input.  For
+ security purposes, the default is \code{False}.
+ 
+ The decoded string is returned.  A \exception{TypeError} is raised if
+ \var{s} were incorrectly padded or if there are non-alphabet
+ characters present in the string.
+ \end{funcdesc}
+ 
+ The legacy interface:
  
  \begin{funcdesc}{decode}{input, output}