Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libmimify.tex @ 21467:4e35fa5d5708 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add documentation for the help() built-in; contributed by Ka-Ping Yee. This is part of SF patch #494622.
author Fred Drake <fdrake@acm.org>
date Tue, 18 Dec 2001 16:31:08 +0000
parents eeb2e77c5bad
children 7e3eac5d3299
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
8918
acfffe14628e New section header style.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
1 \section{\module{mimify} ---
10723
48037f4814b1 Shorten the section title.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
2 MIME processing of mail messages}
48037f4814b1 Shorten the section title.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
3
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
4 \declaremodule{standard}{mimify}
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
5 \modulesynopsis{Mimification and unmimification of mail messages.}
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
6
5910
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
7
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
8 The mimify module defines two functions to convert mail messages to
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
9 and from MIME format. The mail message can be either a simple message
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
10 or a so-called multipart message. Each part is treated separately.
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
11 Mimifying (a part of) a message entails encoding the message as
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
12 quoted-printable if it contains any characters that cannot be
10723
48037f4814b1 Shorten the section title.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
13 represented using 7-bit \ASCII. Unmimifying (a part of) a message
5910
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
14 entails undoing the quoted-printable encoding. Mimify and unmimify
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
15 are especially useful when a message has to be edited before being
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
16 sent. Typical use would be:
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
17
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
18 \begin{verbatim}
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
19 unmimify message
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
20 edit message
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
21 mimify message
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
22 send message
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
23 \end{verbatim}
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
24
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
25 The modules defines the following user-callable functions and
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
26 user-settable variables:
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
27
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
28 \begin{funcdesc}{mimify}{infile, outfile}
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
29 Copy the message in \var{infile} to \var{outfile}, converting parts to
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
30 quoted-printable and adding MIME mail headers when necessary.
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
31 \var{infile} and \var{outfile} can be file objects (actually, any
10723
48037f4814b1 Shorten the section title.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
32 object that has a \method{readline()} method (for \var{infile}) or a
48037f4814b1 Shorten the section title.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
33 \method{write()} method (for \var{outfile})) or strings naming the files.
5910
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
34 If \var{infile} and \var{outfile} are both strings, they may have the
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
35 same value.
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
36 \end{funcdesc}
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
37
10723
48037f4814b1 Shorten the section title.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
38 \begin{funcdesc}{unmimify}{infile, outfile\optional{, decode_base64}}
5910
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
39 Copy the message in \var{infile} to \var{outfile}, decoding all
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
40 quoted-printable parts. \var{infile} and \var{outfile} can be file
10723
48037f4814b1 Shorten the section title.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
41 objects (actually, any object that has a \method{readline()} method (for
48037f4814b1 Shorten the section title.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
42 \var{infile}) or a \method{write()} method (for \var{outfile})) or strings
5910
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
43 naming the files. If \var{infile} and \var{outfile} are both strings,
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
44 they may have the same value.
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
45 If the \var{decode_base64} argument is provided and tests true, any
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
46 parts that are coded in the base64 encoding are decoded as well.
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
47 \end{funcdesc}
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
48
6011
cc577001f7ec Documented mime_decode_header() and mime_encode_header().
Guido van Rossum <guido@python.org>
parents: 5910
diff changeset
49 \begin{funcdesc}{mime_decode_header}{line}
cc577001f7ec Documented mime_decode_header() and mime_encode_header().
Guido van Rossum <guido@python.org>
parents: 5910
diff changeset
50 Return a decoded version of the encoded header line in \var{line}.
cc577001f7ec Documented mime_decode_header() and mime_encode_header().
Guido van Rossum <guido@python.org>
parents: 5910
diff changeset
51 \end{funcdesc}
cc577001f7ec Documented mime_decode_header() and mime_encode_header().
Guido van Rossum <guido@python.org>
parents: 5910
diff changeset
52
cc577001f7ec Documented mime_decode_header() and mime_encode_header().
Guido van Rossum <guido@python.org>
parents: 5910
diff changeset
53 \begin{funcdesc}{mime_encode_header}{line}
cc577001f7ec Documented mime_decode_header() and mime_encode_header().
Guido van Rossum <guido@python.org>
parents: 5910
diff changeset
54 Return a MIME-encoded version of the header line in \var{line}.
cc577001f7ec Documented mime_decode_header() and mime_encode_header().
Guido van Rossum <guido@python.org>
parents: 5910
diff changeset
55 \end{funcdesc}
cc577001f7ec Documented mime_decode_header() and mime_encode_header().
Guido van Rossum <guido@python.org>
parents: 5910
diff changeset
56
5910
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
57 \begin{datadesc}{MAXLEN}
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
58 By default, a part will be encoded as quoted-printable when it
18411
eeb2e77c5bad Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents: 12234
diff changeset
59 contains any non-\ASCII{} characters (characters with the 8th bit
10723
48037f4814b1 Shorten the section title.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
60 set), or if there are any lines longer than \constant{MAXLEN} characters
5910
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
61 (default value 200).
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
62 \end{datadesc}
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
63
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
64 \begin{datadesc}{CHARSET}
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
65 When not specified in the mail headers, a character set must be filled
10723
48037f4814b1 Shorten the section title.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
66 in. The string used is stored in \constant{CHARSET}, and the default
5910
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
67 value is ISO-8859-1 (also known as Latin1 (latin-one)).
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
68 \end{datadesc}
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
69
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
70 This module can also be used from the command line. Usage is as
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
71 follows:
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
72 \begin{verbatim}
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
73 mimify.py -e [-l length] [infile [outfile]]
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
74 mimify.py -d [-b] [infile [outfile]]
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
75 \end{verbatim}
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
76 to encode (mimify) and decode (unmimify) respectively. \var{infile}
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
77 defaults to standard input, \var{outfile} defaults to standard output.
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
78 The same file can be specified for input and output.
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
79
10723
48037f4814b1 Shorten the section title.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
80 If the \strong{-l} option is given when encoding, if there are any lines
5910
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
81 longer than the specified \var{length}, the containing part will be
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
82 encoded.
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
83
10723
48037f4814b1 Shorten the section title.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
84 If the \strong{-b} option is given when decoding, any base64 parts will
5910
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
85 be decoded as well.
89771a46ca35 Added mimify docs (Sjoerd).
Guido van Rossum <guido@python.org>
parents:
diff changeset
86
12234
145c0073d785 Added "See also" section; from Peter Funk <pf@artcom-gmbh.de>.
Fred Drake <fdrake@acm.org>
parents: 10723
diff changeset
87 \begin{seealso}
145c0073d785 Added "See also" section; from Peter Funk <pf@artcom-gmbh.de>.
Fred Drake <fdrake@acm.org>
parents: 10723
diff changeset
88 \seemodule{quopri}{Encode and decode MIME quoted-printable files.}
145c0073d785 Added "See also" section; from Peter Funk <pf@artcom-gmbh.de>.
Fred Drake <fdrake@acm.org>
parents: 10723
diff changeset
89 \end{seealso}