1 <?xml version="1.0" standalone="no"?>
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1//EN"
3 "http://www.oasis-open.org/docbook/xml/4.1/docbook.dtd">
5 <refentry id="mimedecode.py">
8 <refentrytitle>mimedecode.py</refentrytitle>
9 <manvolnum>1</manvolnum>
13 <refname>mimedecode.py</refname>
14 <refpurpose>decode MIME message</refpurpose>
19 <command>mimedecode.py</command>
21 <option>-h|--help</option>
24 <option>-V|--version</option>
27 <option>-cCDP</option>
30 <option>-f charset</option>
33 <option>-d header</option>
36 <option>-p header:param</option>
39 <option>-beit mask</option>
42 <option>-o output_file</option>
44 <arg choice="opt">input_file
45 <arg choice="opt">output_file</arg>
52 <title>DESCRIPTION</title>
54 Mail users, especially in non-English countries, often find that mail
55 messages arrived in different formats, with different content types, in
56 different encodings and charsets. Usually it is good because it allows to use
57 an appropriate format/encoding/whatever. Sometimes, though, some unification is
58 desirable. For example, one may want to put mail messages into an archive,
59 make HTML indices, run search indexer, etc. In such situations converting
60 messages to text in one character set and skipping some binary attachments is
65 Here is the solution - mimedecode.py!
69 It is a program to decode MIME messages. The program expects one input file
70 (either on the command line or on stdin) which is treated as an RFC822 message,
71 and decoded to stdout. If the file is not an RFC822 message it is just piped to
72 stdout as is. If the file is a simple RFC822 message it is just decoded as one
73 part. If it is a MIME message with multiple parts ("attachments") all parts are
74 decoded recursively. Decoding can be controlled by the command-line options.
78 First, Subject and Content-Disposition headers are examined. If any of those
79 exists, it is decoded according to RFC2047. Content-Disposition header is not
80 decoded - only its "filename" parameter. Encoded header parameters violate
81 the RFC, but widely deployed anyway, especially in the M$ Ophice GUI (often
82 referred as "Windoze") world, where programmers are often ignorant lamers who
83 never even heard about RFCs. Correct parameter encoding specified by RFC2231.
84 This program decodes RFC2231-encoded parameters, too.
88 Then the body of the message (or the current part) is decoded. Decoding
89 starts with looking at header Content-Transfer-Encoding. If the header
90 specifies non-8bit encoding (usually base64 or quoted-printable), the body
91 converted to 8bit. Then, if its content type is multipart (multipart/related or
92 multipart/mixed, e.g) every part is recursively decoded. If it is not
93 multipart, mailcap database is consulted to find a way to convert the body to
94 plain text. (I have no idea how mailcap could be configured on said M$ Ophice
95 GUI, please don't ask me; real OS users can consult my example at
96 http://phdru.name/Software/dotfiles/mailcap.html). The decoding process uses
97 first copiousoutput filter it can find. If there is no any filter the body just
102 Then Content-Type header consulted for charset. If it is not equal to
103 current default charset the body text recoded. Finally message headers and body
110 <title>OPTIONS</title>
117 Print brief usage help and exit.
124 <term>--version</term>
127 Print version and exit.
136 Recode different character sets in message body to current default
137 charset; this is the default.
146 Do not recode character sets in message body.
152 <term>-f charset</term>
155 Force this charset to be the current default charset instead of
156 sys.getdefaultencoding().
162 <term>-d header</term>
165 Add the header to a list of headers to decode; initially the list
166 contains headers "From" and "Subject".
175 Clear the list of headers to decode (make it empty).
181 <term>-p header:param</term>
184 Add the (header, param) pair to a list of headers' parameters to
185 decode; initially the list contains header "Content-Disposition",
186 parameter "filename".
195 Clear the list of headers' parameters to decode (make it empty).
204 Append mask to the list of binary content types; if the message to
205 decode has a part of this type the program will pass the part as is,
206 without any additional processing.
215 Append mask to the list of error content types; if the message to
216 decode has a part of this type the program will raise ValueError.
225 Append mask to the list of content types to ignore; if the message to
226 decode has a part of this type the program will not pass it, instead
227 a line "Message body of type `%s' skipped." will be issued.
236 Append mask to the list of content types to convert to text; if the
237 message to decode has a part of this type the program will consult
238 mailcap database, find first copiousoutput filter and convert the
245 <term>-o output_file</term>
248 Useful to set the output file in case of redirected stdin:
249 <programlisting language="sh">mimedecode.py -o output_file < input_file
250 cat input_file | mimedecode.py -o output_file</programlisting>
257 The last 4 options (-beit) require more explanation. They allow a user
258 to control body decoding with great flexibility. Think about said mail
259 archive; for example, its maintainer wants to put there only texts, convert
260 Postscript/PDF to text, pass HTML and images as is, and ignore everything
265 <code language="shell">
266 mimedecode.py -t application/postscript -t application/pdf -b text/html
267 -b 'image/*' -i '*/*'
272 When the program decodes a message (or its part), it consults
273 Content-Type header. The content type is searched in all 4 lists, in order
274 "text-binary-ignore-error". If found, appropriate action performed. If not
275 found, the program search the same lists for "type/*" mask (the type of
276 "text/html" is just "text"). If found, appropriate action performed. If not
277 found, the program search the same lists for "*/*" mask. If found,
278 appropriate action performed. If not found, the program uses default
279 action, which is to decode everything to text (if mailcap specifies
284 Initially all 4 lists are empty, so without any additional parameters
285 the program always uses the default decoding.
291 <title>ENVIRONMENT</title>
296 Define current locale settings. Used to determine current default
297 charset (if your Python is properly installed and configured).
305 The program may produce incorrect MIME message. The purpose of the program
306 is to decode whatever it is possible to decode, not to produce absolutely
307 correct MIME output. The incorrect parts are obvious - decoded Subject headers
308 and filenames. Other than that output is correct MIME message. The program does
309 not try to guess whether the headers are correct. For example, if a message
310 header states that charset is iso8859-5, but the body is actually in koi8-r -
311 the program will recode the message to the wrong charset.
317 <title>AUTHOR</title>
319 Oleg Broytman <phd@phdru.name>
325 <title>COPYRIGHT</title>
327 Copyright (C) 2001-2014 PhiloSoft Design
333 <title>LICENSE</title>
341 <title>NO WARRANTIES</title>
343 This program is distributed in the hope that it will be useful, but WITHOUT
344 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
345 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
352 <title>SEE ALSO</title>
354 mimedecode.py home page: http://phdru.name/Software/Python/#mimedecode