Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit ad9aaee

Browse files
warsawwarsaw
committed
Documentation for new RFC 3548 functions.
1 parent 30ff12f commit ad9aaee

1 file changed

Lines changed: 106 additions & 13 deletions

File tree

‎Doc/lib/libbase64.tex‎

Lines changed: 106 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,118 @@
11
\section{\module{base64} ---
2-
Encode and decode MIME base64 data}
2+
RFC 3548: Base16, Base32, Base64 Data Encodings}
33

44
\declaremodule{standard}{base64}
5-
\modulesynopsis{Encode and decode files using the MIME base64 data.}
5+
\modulesynopsis{RFC 3548: Base16, Base32, Base64 Data Encodings}
66

77

88
\indexii{base64}{encoding}
99
\index{MIME!base64 encoding}
1010

11-
This module performs base64 encoding and decoding of arbitrary binary
12-
strings into text strings that can be safely sent by email or included
13-
as part of an HTTP POST request. The
14-
encoding scheme is defined in \rfc{1521} (\emph{MIME
15-
(Multipurpose Internet Mail Extensions) Part One: Mechanisms for
16-
Specifying and Describing the Format of Internet Message Bodies},
17-
section 5.2, ``Base64 Content-Transfer-Encoding'') and is used for
18-
MIME email and various other Internet-related applications; it is not
19-
the same as the output produced by the \program{uuencode} program.
20-
For example, the string \code{'www.python.org'} is encoded as the
21-
string \code{'d3d3LnB5dGhvbi5vcmc=\e n'}.
11+
This module provides data encoding and decoding as specified in
12+
\rfc{3548}. This standard defines the Base16, Base32, and Base64
13+
algorithms for encoding and decoding arbitrary binary strings into
14+
text strings that can be safely sent by email, used as parts of URLs,
15+
or included as part of an HTTP POST request. The encoding algorith is
16+
not the same as the \program{uuencode} program.
2217

18+
There are two interfaces provided by this module. The modern
19+
interface supports encoding and decoding string objects using all
20+
three alphabets. The legacy interface provides for encoding and
21+
decoding to and from file-like objects as well as strings, but only
22+
using the Base64 standard alphabet.
23+
24+
The modern interface provides:
25+
26+
\begin{funcdesc}{b64encode}{s\optional{, altchars}}
27+
Encode a string use Base64.
28+
29+
\var{s} is the string to encode. Optional \var{altchars} must be a
30+
string of at least length 2 (additional characters are ignored) which
31+
specifies an alternative alphabet for the \code{+} and \code{/}
32+
characters. This allows an application to e.g. generate URL or
33+
filesystem safe Base64 strings. The default is \code{None}, for which
34+
the standard Base64 alphabet is used.
35+
36+
The encoded string is returned.
37+
\end{funcdesc}
38+
39+
\begin{funcdesc}{b64decode}{s\optional{, altchars}}
40+
Decode a Base64 encoded string.
41+
42+
\var{s} is the string to decode. Optional \var{altchars} must be a
43+
string of at least length 2 (additional characters are ignored) which
44+
specifies the alternative alphabet used instead of the \code{+} and
45+
\code{/} characters.
46+
47+
The decoded string is returned. A \exception{TypeError} is raised if
48+
\var{s} were incorrectly padded or if there are non-alphabet
49+
characters present in the string.
50+
\end{funcdesc}
51+
52+
\begin{funcdesc}{standard_b64encode}{s}
53+
Encode string \var{s} using the standard Base64 alphabet.
54+
\end{funcdesc}
55+
56+
\begin{funcdesc}{standard_b64decode}{s}
57+
Decode string \var{s} using the standard Base64 alphabet.
58+
\end{funcdesc}
59+
60+
\begin{funcdesc}{urlsafe_b64encode}{s}
61+
Encode string \var{s} using a URL-safe alphabet, which substitutes
62+
\code{-} instead of \code{+} and \code{_} instead of \code{/} in the
63+
standard Base64 alphabet.
64+
\end{funcdesc}
65+
66+
\begin{funcdesc}{urlsafe_b64decode}{s}
67+
Decode string \var{s} using a URL-safe alphabet, which substitutes
68+
\code{-} instead of \code{+} and \code{_} instead of \code{/} in the
69+
standard Base64 alphabet.
70+
\end{funcdesc}
71+
72+
\begin{funcdesc}{b32encode}{s}
73+
Encode a string using Base32. \var{s} is the string to encode. The
74+
encoded string is returned.
75+
\end{funcdesc}
76+
77+
\begin{funcdesc}{b32decode}{s\optional{, casefold\optional{, map01}}}
78+
Decode a Base32 encoded string.
79+
80+
\var{s} is the string to decode. Optional \var{casefold} is a flag
81+
specifying whether a lowercase alphabet is acceptable as input. For
82+
security purposes, the default is \code{False}.
83+
84+
\rfc{3548} allows for optional mapping of the digit 0 (zero) to the
85+
letter O (oh), and for optional mapping of the digit 1 (one) to either
86+
the letter I (eye) or letter L (el). The optional argument
87+
\var{map01} when not \code{None}, specifies which letter the digit 1 should
88+
be mapped to (when map01 is not \var{None}, the digit 0 is always
89+
mapped to the letter O). For security purposes the default is
90+
\code{None}, so that 0 and 1 are not allowed in the input.
91+
92+
The decoded string is returned. A \exception{TypeError} is raised if
93+
\var{s} were incorrectly padded or if there are non-alphabet characters
94+
present in the string.
95+
\end{funcdesc}
96+
97+
\begin{funcdesc}{b16encode}{s}
98+
Encode a string using Base16.
99+
100+
\var{s} is the string to encode. The encoded string is returned.
101+
\end{funcdesc}
102+
103+
\begin{funcdesc}{b16decode}{s\optional{, casefold}}
104+
Decode a Base16 encoded string.
105+
106+
\var{s} is the string to decode. Optional \var{casefold} is a flag
107+
specifying whether a lowercase alphabet is acceptable as input. For
108+
security purposes, the default is \code{False}.
109+
110+
The decoded string is returned. A \exception{TypeError} is raised if
111+
\var{s} were incorrectly padded or if there are non-alphabet
112+
characters present in the string.
113+
\end{funcdesc}
114+
115+
The legacy interface:
23116

24117
\begin{funcdesc}{decode}{input, output}
25118
Decode the contents of the \var{input} file and write the resulting

0 commit comments

Comments
 (0)