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>-beit mask</option>
66 <option>-o output_file</option>
68 <arg choice="opt">input_file
69 <arg choice="opt">output_file</arg>
76 <title>DESCRIPTION</title>
78 Mail users, especially in non-English countries, often find that mail
79 messages arrived in different formats, with different content types, in
80 different encodings and charsets. Usually it is good because it allows to
81 use an appropriate format/encoding/whatever. Sometimes, though, some
82 unification is desirable. For example, one may want to put mail messages
83 into an archive, make HTML indices, run search indexer, etc. In such
84 situations converting messages to text in one character set and skipping
85 some binary attachments is much desirable.
89 Here is the solution - mimedecode.py!
93 This is a program to decode MIME messages. The program expects one input
94 file (either on command line or on stdin) which is treated as an RFC822
95 message, and decodes to stdout or an output file. If the file is not an
96 RFC822 message it is just copied to the output one-to-one. If the file is a
97 simple RFC822 message it is decoded as one part. If it is a MIME message
98 with multiple parts ("attachments") all parts are decoded. Decoding can be
99 controlled by command-line options.
103 First, Subject and Content-Disposition headers are examined. If any of those
104 exists, it is decoded according to RFC2047. Content-Disposition header is
105 not decoded - only its "filename" parameter. Encoded header parameters
106 violate the RFC, but widely deployed anyway by ignorant coders who never
107 even heard about RFCs. Correct parameter encoding specified by RFC2231. This
108 program decodes RFC2231-encoded parameters, too.
112 Then the body of the message (or the current part) is decoded. Decoding
113 starts with looking at header Content-Transfer-Encoding. If the header
114 specifies non-8bit encoding (usually base64 or quoted-printable), the body
115 converted to 8bit. Then, if its content type is multipart (multipart/related
116 or multipart/mixed, e.g) every part is recursively decoded. If it is not
117 multipart, mailcap database is consulted to find a way to convert the body
118 to plain text. (I have no idea how mailcap can be configured on OSes other
119 than POSIX, please don't ask me; real OS users can consult my example at
120 <ulink url="http://phdru.name/Software/dotfiles/mailcap.html">http://phdru.name/Software/dotfiles/mailcap.html</ulink>).
121 The decoding process uses the first copiousoutput filter it can find. If
122 there are no filters the body just passed as is.
126 Then Content-Type header is consulted for charset. If it is not equal to the
127 current locale charset and recoding is allowed the body text is recoded.
128 Finally message headers and the body are flushed to stdout.
134 <title>OPTIONS</title>
141 Print brief usage help and exit.
148 <term>--version</term>
151 Print version and exit.
160 Recode different character sets in message bodies to the current
161 default charset; this is the default.
170 Do not recode character sets in message bodies.
176 <term>-f charset</term>
179 Force this charset to be the current default charset instead of
186 <term>-H hostname</term>
187 <term>--host=hostname</term>
190 Use this hostname in X-MIME-Autoconverted headers instead of the
197 <term>-d header</term>
200 Add the header to a list of headers to decode; initially the list
201 contains headers "From", "To", "Cc", "Reply-To", "Mail-Followup-To"
211 Clear the list of headers to decode (make it empty).
217 <term>-p header:param</term>
220 Add the pair (header, param) to a list of headers parameters to
221 decode; initially the list contains header "Content-Type",
222 parameter "name" and header "Content-Disposition", parameter
232 Clear the list of headers parameters to decode (make it empty).
238 <term>-r header</term>
241 Add the header to a list of headers to remove completely; initially
248 <term>-R header:param</term>
251 Add the pair (header, param) to a list of headers parameters to
252 remove; initially the list is empty.
261 Append mask to the list of binary content types; if the message to
262 decode has a part of this type the program will pass the part as is,
263 without any additional processing.
272 Append mask to the list of error content types; if the message to
273 decode has a part of this type the program fails with ValueError.
282 Append mask to the list of content types to ignore; if the message to
283 decode has a part of this type the program will not pass it, instead
284 a line "Message body of type `%s' skipped." will be issued.
293 Append mask to the list of content types to convert to text; if the
294 message to decode has a part of this type the program will consult
295 mailcap database, find first copiousoutput filter and convert the
302 <term>-o output_file</term>
305 Useful to set the output file in case of redirected stdin:
306 <programlisting language="sh">mimedecode.py -o output_file < input_file
307 cat input_file | mimedecode.py -o output_file</programlisting>
314 The 4 list options (-beit) require more explanation. They allow a user to
315 control body decoding with great flexibility. Think about said mail archive;
316 for example, its maintainer wants to put there only texts, convert
317 Postscript/PDF to text, pass HTML and images as is, and ignore everything
323 mimedecode.py -t application/postscript -t application/pdf -b text/html
324 -b 'image/*' -i '*/*'
329 When the program decodes a message (non-MIME or a non-multipart subpart of a
330 MIME message), it consults Content-Type header. The content type is searched
331 in all 4 lists, in order "text-binary-ignore-error". If found, appropriate
332 action performed. If not found, the program search the same lists for
333 "type/*" mask (the type of "text/html" is just "text"). If found,
334 appropriate action performed. If not found, the program search the same
335 lists for "*/*" mask. If found, appropriate action performed. If not found,
336 the program uses default action, which is to decode everything to text (if
337 mailcap specifies a filter).
341 Initially all 4 lists are empty, so without any additional parameters
342 the program always uses the default decoding.
348 <title>ENVIRONMENT</title>
350 <varlistentry><term>LANG</term></varlistentry>
351 <varlistentry><term>LC_ALL</term></varlistentry>
352 <varlistentry><term>LC_CTYPE</term></varlistentry>
355 Define current locale settings. Used to determine current default charset (if
356 your Python is properly installed and configured).
364 The program may produce incorrect MIME message. The purpose of the program
365 is to decode whatever it is possible to decode, not to produce absolutely
366 correct MIME output. The incorrect parts are obvious - decoded
367 From/To/Cc/Reply-To/Mail-Followup-To/Subject headers and filenames. Other
368 than that output is correct MIME message. The program does not try to guess
369 whether the headers are correct. For example, if a message header states
370 that charset is iso8859-5, but the body is actually in utf-8 the program
371 will recode the message with the wrong charset.
377 <title>AUTHOR</title>
379 <firstname>Oleg</firstname>
380 <surname>Broytman</surname>
381 <email>phd@phdru.name</email>
387 <title>COPYRIGHT</title>
389 Copyright (C) 2001-2014 PhiloSoft Design.
395 <title>LICENSE</title>
403 <title>NO WARRANTIES</title>
405 This program is distributed in the hope that it will be useful, but WITHOUT
406 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
407 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
414 <title>SEE ALSO</title>
416 mimedecode.py home page:
417 <ulink url="http://phdru.name/Software/Python/#mimedecode">http://phdru.name/Software/Python/#mimedecode</ulink>