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>-H|--host=hostname</option>
48 <option>-f charset</option>
51 <option>-d header</option>
54 <option>-p header:param</option>
57 <option>-beit mask</option>
60 <option>-o output_file</option>
62 <arg choice="opt">input_file
63 <arg choice="opt">output_file</arg>
70 <title>DESCRIPTION</title>
72 Mail users, especially in non-English countries, often find that mail
73 messages arrived in different formats, with different content types, in
74 different encodings and charsets. Usually it is good because it allows to use
75 an appropriate format/encoding/whatever. Sometimes, though, some unification is
76 desirable. For example, one may want to put mail messages into an archive,
77 make HTML indices, run search indexer, etc. In such situations converting
78 messages to text in one character set and skipping some binary attachments is
83 Here is the solution - mimedecode.py!
87 This is a program to decode MIME messages. The program expects one input
88 file (either on command line or on stdin) which is treated as an RFC822
89 message, and decodes to stdout or an output file. If the file is not an RFC822
90 message it is just copied to the output one-to-one. If the file is a simple
91 RFC822 message it is decoded as one part. If it is a MIME message with multiple
92 parts ("attachments") all parts are decoded. Decoding can be controlled by
97 First, Subject and Content-Disposition headers are examined. If any of those
98 exists, it is decoded according to RFC2047. Content-Disposition header is
99 not decoded - only its "filename" parameter. Encoded header parameters
100 violate the RFC, but widely deployed anyway by ignorant coders who never
101 even heard about RFCs. Correct parameter encoding specified by RFC2231. This
102 program decodes RFC2231-encoded parameters, too.
106 Then the body of the message (or the current part) is decoded. Decoding
107 starts with looking at header Content-Transfer-Encoding. If the header
108 specifies non-8bit encoding (usually base64 or quoted-printable), the body
109 converted to 8bit. Then, if its content type is multipart (multipart/related
110 or multipart/mixed, e.g) every part is recursively decoded. If it is not
111 multipart, mailcap database is consulted to find a way to convert the body
112 to plain text. (I have no idea how mailcap can be configured on OSes other
113 than POSIX, please don't ask me; real OS users can consult my example at
114 <ulink url="http://phdru.name/Software/dotfiles/mailcap.html">http://phdru.name/Software/dotfiles/mailcap.html</ulink>).
115 The decoding process uses the first copiousoutput filter it can find. If
116 there is no any filter the body just passed as is.
120 Then Content-Type header is consulted for charset. If it is not equal to the
121 current locale charset the body text is recoded. Finally message headers and
122 the body are flushed to stdout.
128 <title>OPTIONS</title>
135 Print brief usage help and exit.
142 <term>--version</term>
145 Print version and exit.
154 Recode different character sets in message body to current default
155 charset; this is the default.
164 Do not recode character sets in message body.
170 <term>-H hostname</term>
171 <term>--host=hostname</term>
174 Use this hostname in X-MIME-Autoconverted headers instead of the
181 <term>-f charset</term>
184 Force this charset to be the current default charset instead of
191 <term>-d header</term>
194 Add the header to a list of headers to decode; initially the list
195 contains headers "From", "To" and "Subject".
204 Clear the list of headers to decode (make it empty).
210 <term>-p header:param</term>
213 Add the pair (header, param) to a list of headers' parameters to
214 decode; initially the list contains header "Content-Type",
215 parameter "name" and header "Content-Disposition", parameter
225 Clear the list of headers' parameters to decode (make it empty).
234 Append mask to the list of binary content types; if the message to
235 decode has a part of this type the program will pass the part as is,
236 without any additional processing.
245 Append mask to the list of error content types; if the message to
246 decode has a part of this type the program fails with ValueError.
255 Append mask to the list of content types to ignore; if the message to
256 decode has a part of this type the program will not pass it, instead
257 a line "Message body of type `%s' skipped." will be issued.
266 Append mask to the list of content types to convert to text; if the
267 message to decode has a part of this type the program will consult
268 mailcap database, find first copiousoutput filter and convert the
275 <term>-o output_file</term>
278 Useful to set the output file in case of redirected stdin:
279 <programlisting language="sh">mimedecode.py -o output_file < input_file
280 cat input_file | mimedecode.py -o output_file</programlisting>
287 The 4 list options (-beit) require more explanation. They allow a user
288 to control body decoding with great flexibility. Think about said mail
289 archive; for example, its maintainer wants to put there only texts, convert
290 Postscript/PDF to text, pass HTML and images as is, and ignore everything
296 mimedecode.py -t application/postscript -t application/pdf -b text/html
297 -b 'image/*' -i '*/*'
302 When the program decodes a message (non-MIME or a non-multipart subpart of a
303 MIME message), it consults Content-Type header. The content type is searched
304 in all 4 lists, in order "text-binary-ignore-error". If found, appropriate
305 action performed. If not found, the program search the same lists for
306 "type/*" mask (the type of "text/html" is just "text"). If found,
307 appropriate action performed. If not found, the program search the same
308 lists for "*/*" mask. If found, appropriate action performed. If not found,
309 the program uses default action, which is to decode everything to text (if
310 mailcap specifies a filter).
314 Initially all 4 lists are empty, so without any additional parameters
315 the program always uses the default decoding.
321 <title>ENVIRONMENT</title>
323 <varlistentry><term>LANG</term></varlistentry>
324 <varlistentry><term>LC_ALL</term></varlistentry>
325 <varlistentry><term>LC_CTYPE</term></varlistentry>
328 Define current locale settings. Used to determine current default charset (if
329 your Python is properly installed and configured).
337 The program may produce incorrect MIME message. The purpose of the program
338 is to decode whatever it is possible to decode, not to produce absolutely
339 correct MIME output. The incorrect parts are obvious - decoded Subject headers
340 and filenames. Other than that output is correct MIME message. The program does
341 not try to guess whether the headers are correct. For example, if a message
342 header states that charset is iso8859-5, but the body is actually in utf-8
343 the program will recode the message with the wrong charset.
349 <title>AUTHOR</title>
351 <firstname>Oleg</firstname>
352 <surname>Broytman</surname>
353 <email>phd@phdru.name</email>
359 <title>COPYRIGHT</title>
361 Copyright (C) 2001-2014 PhiloSoft Design.
367 <title>LICENSE</title>
375 <title>NO WARRANTIES</title>
377 This program is distributed in the hope that it will be useful, but WITHOUT
378 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
379 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
386 <title>SEE ALSO</title>
388 mimedecode.py home page:
389 <ulink url="http://phdru.name/Software/Python/#mimedecode">http://phdru.name/Software/Python/#mimedecode</ulink>