1 <?xml version="1.0" standalone="no"?>
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "file:///usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd">
5 <refentry id="mimedecode.py">
8 <title>mimedecode.py</title>
9 <productname>mimedecode.docbook</productname>
11 <firstname>Oleg</firstname>
12 <surname>Broytman</surname>
13 <email>phd@phdru.name</email>
17 <year>2001-2014</year>
18 <holder>PhiloSoft Design.</holder>
23 <refentrytitle>mimedecode.py</refentrytitle>
24 <manvolnum>1</manvolnum>
28 <refname>mimedecode.py</refname>
29 <refpurpose>decode MIME message</refpurpose>
34 <command>mimedecode.py</command>
36 <option>-h|--help</option>
39 <option>-V|--version</option>
42 <option>-cCDP</option>
45 <option>-f charset</option>
48 <option>-H|--host=hostname</option>
51 <option>-d header</option>
54 <option>-p header:param</option>
57 <option>-r header</option>
60 <option>-R header:param</option>
63 <option>--remove-params=header</option>
66 <option>-beit mask</option>
69 <option>-o output_file</option>
71 <arg choice="opt">input_file
72 <arg choice="opt">output_file</arg>
79 <title>DESCRIPTION</title>
81 Mail users, especially in non-English countries, often find that mail
82 messages arrived in different formats, with different content types, in
83 different encodings and charsets. Usually it is good because it allows to
84 use an appropriate format/encoding/whatever. Sometimes, though, some
85 unification is desirable. For example, one may want to put mail messages
86 into an archive, make HTML indices, run search indexer, etc. In such
87 situations converting messages to text in one character set and skipping
88 some binary attachments is much desirable.
92 Here is the solution - mimedecode.py!
96 This is a program to decode MIME messages. The program expects one input
97 file (either on command line or on stdin) which is treated as an RFC822
98 message, and decodes to stdout or an output file. If the file is not an
99 RFC822 message it is just copied to the output one-to-one. If the file is a
100 simple RFC822 message it is decoded as one part. If it is a MIME message
101 with multiple parts ("attachments") all parts are decoded. Decoding can be
102 controlled by command-line options.
106 First, for every part the program removes headers and parameters listed with
107 -r and -R options. Then, Subject and Content-Disposition headers (and all
108 headers listed with -d and -p options) are examined. If any of those exists,
109 they are decoded according to RFC2047. Content-Disposition header is not
110 decoded - only its "filename" parameter. Encoded header parameters violate
111 the RFC, but widely deployed anyway by ignorant coders who never even heard
112 about RFCs. Correct parameter encoding specified by RFC2231. This program
113 decodes RFC2231-encoded parameters, too.
117 Then the body of the message (or the current part) is decoded. Decoding
118 starts with looking at header Content-Transfer-Encoding. If the header
119 specifies non-8bit encoding (usually base64 or quoted-printable), the body
120 converted to 8bit. Then, if its content type is multipart (multipart/related
121 or multipart/mixed, e.g) every part is recursively decoded. If it is not
122 multipart, mailcap database is consulted to find a way to convert the body
123 to plain text. (I have no idea how mailcap can be configured on OSes other
124 than POSIX, please don't ask me; real OS users can consult my example at
125 <ulink url="http://phdru.name/Software/dotfiles/mailcap.html">http://phdru.name/Software/dotfiles/mailcap.html</ulink>).
126 The decoding process uses the first copiousoutput filter it can find. If
127 there are no filters the body just passed as is.
131 Then Content-Type header is consulted for charset. If it is not equal to the
132 current locale charset and recoding is allowed the body text is recoded.
133 Finally message headers and the body are flushed to stdout.
139 <title>OPTIONS</title>
146 Print brief usage help and exit.
153 <term>--version</term>
156 Print version and exit.
165 Recode different character sets in message bodies to the current
166 default charset; this is the default.
175 Do not recode character sets in message bodies.
181 <term>-f charset</term>
184 Force this charset to be the current default charset instead of
191 <term>-H hostname</term>
192 <term>--host=hostname</term>
195 Use this hostname in X-MIME-Autoconverted headers instead of the
202 <term>-d header</term>
205 Add the header to a list of headers to decode; initially the list
206 contains headers "From", "To", "Cc", "Reply-To", "Mail-Followup-To"
216 Clear the list of headers to decode (make it empty).
222 <term>-p header:param</term>
225 Add the pair (header, param) to a list of headers parameters to
226 decode; initially the list contains header "Content-Type",
227 parameter "name" and header "Content-Disposition", parameter
237 Clear the list of headers parameters to decode (make it empty).
243 <term>-r header</term>
246 Add the header to a list of headers to remove completely; initially
253 <term>-R header:param</term>
256 Add the pair (header, param) to a list of headers parameters to
257 remove; initially the list is empty.
263 <term>--remove-params=header</term>
266 Add the header to a list of headers from which all parameters will
267 be removed; initially the list is empty.
276 Append mask to the list of binary content types; if the message to
277 decode has a part of this type the program will pass the part as is,
278 without any additional processing.
287 Append mask to the list of error content types; if the message to
288 decode has a part of this type the program fails with ValueError.
297 Append mask to the list of content types to ignore; if the message to
298 decode has a part of this type the program will not pass it, instead
299 a line "Message body of type `%s' skipped." will be issued.
308 Append mask to the list of content types to convert to text; if the
309 message to decode has a part of this type the program will consult
310 mailcap database, find first copiousoutput filter and convert the
317 <term>-o output_file</term>
320 Useful to set the output file in case of redirected stdin:
321 <programlisting language="sh">mimedecode.py -o output_file < input_file
322 cat input_file | mimedecode.py -o output_file</programlisting>
329 The 4 list options (-beit) require more explanation. They allow a user to
330 control body decoding with great flexibility. Think about said mail archive;
331 for example, its maintainer wants to put there only texts, convert
332 Postscript/PDF to text, pass HTML and images as is, and ignore everything
338 mimedecode.py -t application/postscript -t application/pdf -b text/html
339 -b 'image/*' -i '*/*'
344 When the program decodes a message (non-MIME or a non-multipart subpart of a
345 MIME message), it consults Content-Type header. The content type is searched
346 in all 4 lists, in order "text-binary-ignore-error". If found, appropriate
347 action performed. If not found, the program search the same lists for
348 "type/*" mask (the type of "text/html" is just "text"). If found,
349 appropriate action performed. If not found, the program search the same
350 lists for "*/*" mask. If found, appropriate action performed. If not found,
351 the program uses default action, which is to decode everything to text (if
352 mailcap specifies a filter).
356 Initially all 4 lists are empty, so without any additional parameters
357 the program always uses the default decoding.
363 <title>ENVIRONMENT</title>
365 <varlistentry><term>LANG</term></varlistentry>
366 <varlistentry><term>LC_ALL</term></varlistentry>
367 <varlistentry><term>LC_CTYPE</term></varlistentry>
370 Define current locale settings. Used to determine current default charset (if
371 your Python is properly installed and configured).
379 The program may produce incorrect MIME message. The purpose of the program
380 is to decode whatever it is possible to decode, not to produce absolutely
381 correct MIME output. The incorrect parts are obvious - decoded
382 From/To/Cc/Reply-To/Mail-Followup-To/Subject headers and filenames. Other
383 than that output is correct MIME message. The program does not try to guess
384 whether the headers are correct. For example, if a message header states
385 that charset is iso8859-5, but the body is actually in utf-8 the program
386 will recode the message with the wrong charset.
392 <title>AUTHOR</title>
394 <firstname>Oleg</firstname>
395 <surname>Broytman</surname>
396 <email>phd@phdru.name</email>
402 <title>COPYRIGHT</title>
404 Copyright (C) 2001-2014 PhiloSoft Design.
410 <title>LICENSE</title>
418 <title>NO WARRANTIES</title>
420 This program is distributed in the hope that it will be useful, but WITHOUT
421 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
422 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
429 <title>SEE ALSO</title>
431 mimedecode.py home page:
432 <ulink url="http://phdru.name/Software/Python/#mimedecode">http://phdru.name/Software/Python/#mimedecode</ulink>