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>-beit mask</option>
63 <option>-o output_file</option>
65 <arg choice="opt">input_file
66 <arg choice="opt">output_file</arg>
73 <title>DESCRIPTION</title>
75 Mail users, especially in non-English countries, often find that mail
76 messages arrived in different formats, with different content types, in
77 different encodings and charsets. Usually it is good because it allows to use
78 an appropriate format/encoding/whatever. Sometimes, though, some unification is
79 desirable. For example, one may want to put mail messages into an archive,
80 make HTML indices, run search indexer, etc. In such situations converting
81 messages to text in one character set and skipping some binary attachments is
86 Here is the solution - mimedecode.py!
90 This is a program to decode MIME messages. The program expects one input
91 file (either on command line or on stdin) which is treated as an RFC822
92 message, and decodes to stdout or an output file. If the file is not an RFC822
93 message it is just copied to the output one-to-one. If the file is a simple
94 RFC822 message it is decoded as one part. If it is a MIME message with multiple
95 parts ("attachments") all parts are decoded. Decoding can be controlled by
100 First, Subject and Content-Disposition headers are examined. If any of those
101 exists, it is decoded according to RFC2047. Content-Disposition header is
102 not decoded - only its "filename" parameter. Encoded header parameters
103 violate the RFC, but widely deployed anyway by ignorant coders who never
104 even heard about RFCs. Correct parameter encoding specified by RFC2231. This
105 program decodes RFC2231-encoded parameters, too.
109 Then the body of the message (or the current part) is decoded. Decoding
110 starts with looking at header Content-Transfer-Encoding. If the header
111 specifies non-8bit encoding (usually base64 or quoted-printable), the body
112 converted to 8bit. Then, if its content type is multipart (multipart/related
113 or multipart/mixed, e.g) every part is recursively decoded. If it is not
114 multipart, mailcap database is consulted to find a way to convert the body
115 to plain text. (I have no idea how mailcap can be configured on OSes other
116 than POSIX, please don't ask me; real OS users can consult my example at
117 <ulink url="http://phdru.name/Software/dotfiles/mailcap.html">http://phdru.name/Software/dotfiles/mailcap.html</ulink>).
118 The decoding process uses the first copiousoutput filter it can find. If
119 there are no filters the body just passed as is.
123 Then Content-Type header is consulted for charset. If it is not equal to the
124 current locale charset and recoding is allowed the body text is recoded.
125 Finally message headers and the body are flushed to stdout.
131 <title>OPTIONS</title>
138 Print brief usage help and exit.
145 <term>--version</term>
148 Print version and exit.
157 Recode different character sets in message bodies to the current
158 default charset; this is the default.
167 Do not recode character sets in message bodies.
173 <term>-f charset</term>
176 Force this charset to be the current default charset instead of
183 <term>-H hostname</term>
184 <term>--host=hostname</term>
187 Use this hostname in X-MIME-Autoconverted headers instead of the
194 <term>-d header</term>
197 Add the header to a list of headers to decode; initially the list
198 contains headers "From", "To", "Cc", "Reply-To", "Mail-Followup-To"
208 Clear the list of headers to decode (make it empty).
214 <term>-p header:param</term>
217 Add the pair (header, param) to a list of headers' parameters to
218 decode; initially the list contains header "Content-Type",
219 parameter "name" and header "Content-Disposition", parameter
229 Clear the list of headers' parameters to decode (make it empty).
235 <term>-r header</term>
238 Add the header to a list of headers to remove completely; initially
248 Append mask to the list of binary content types; if the message to
249 decode has a part of this type the program will pass the part as is,
250 without any additional processing.
259 Append mask to the list of error content types; if the message to
260 decode has a part of this type the program fails with ValueError.
269 Append mask to the list of content types to ignore; if the message to
270 decode has a part of this type the program will not pass it, instead
271 a line "Message body of type `%s' skipped." will be issued.
280 Append mask to the list of content types to convert to text; if the
281 message to decode has a part of this type the program will consult
282 mailcap database, find first copiousoutput filter and convert the
289 <term>-o output_file</term>
292 Useful to set the output file in case of redirected stdin:
293 <programlisting language="sh">mimedecode.py -o output_file < input_file
294 cat input_file | mimedecode.py -o output_file</programlisting>
301 The 4 list options (-beit) require more explanation. They allow a user
302 to control body decoding with great flexibility. Think about said mail
303 archive; for example, its maintainer wants to put there only texts, convert
304 Postscript/PDF to text, pass HTML and images as is, and ignore everything
310 mimedecode.py -t application/postscript -t application/pdf -b text/html
311 -b 'image/*' -i '*/*'
316 When the program decodes a message (non-MIME or a non-multipart subpart of a
317 MIME message), it consults Content-Type header. The content type is searched
318 in all 4 lists, in order "text-binary-ignore-error". If found, appropriate
319 action performed. If not found, the program search the same lists for
320 "type/*" mask (the type of "text/html" is just "text"). If found,
321 appropriate action performed. If not found, the program search the same
322 lists for "*/*" mask. If found, appropriate action performed. If not found,
323 the program uses default action, which is to decode everything to text (if
324 mailcap specifies a filter).
328 Initially all 4 lists are empty, so without any additional parameters
329 the program always uses the default decoding.
335 <title>ENVIRONMENT</title>
337 <varlistentry><term>LANG</term></varlistentry>
338 <varlistentry><term>LC_ALL</term></varlistentry>
339 <varlistentry><term>LC_CTYPE</term></varlistentry>
342 Define current locale settings. Used to determine current default charset (if
343 your Python is properly installed and configured).
351 The program may produce incorrect MIME message. The purpose of the program
352 is to decode whatever it is possible to decode, not to produce absolutely
353 correct MIME output. The incorrect parts are obvious - decoded
354 From/To/Cc/Reply-To/Mail-Followup-To/Subject headers and filenames. Other
355 than that output is correct MIME message. The program does not try to guess
356 whether the headers are correct. For example, if a message header states
357 that charset is iso8859-5, but the body is actually in utf-8 the program
358 will recode the message with the wrong charset.
364 <title>AUTHOR</title>
366 <firstname>Oleg</firstname>
367 <surname>Broytman</surname>
368 <email>phd@phdru.name</email>
374 <title>COPYRIGHT</title>
376 Copyright (C) 2001-2014 PhiloSoft Design.
382 <title>LICENSE</title>
390 <title>NO WARRANTIES</title>
392 This program is distributed in the hope that it will be useful, but WITHOUT
393 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
394 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
401 <title>SEE ALSO</title>
403 mimedecode.py home page:
404 <ulink url="http://phdru.name/Software/Python/#mimedecode">http://phdru.name/Software/Python/#mimedecode</ulink>