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 header1[,header2,header3...]</option>
54 <option>-d *[,-header1,-header2,-header3...]</option>
57 <option>-p header:param</option>
60 <option>-r header</option>
63 <option>-R header:param</option>
66 <option>--remove-params=header</option>
69 <option>-beit mask</option>
72 <option>-o output_file</option>
74 <arg choice="opt">input_file
75 <arg choice="opt">output_file</arg>
82 <title>DESCRIPTION</title>
84 Mail users, especially in non-English countries, often find that mail
85 messages arrived in different formats, with different content types, in
86 different encodings and charsets. Usually it is good because it allows to
87 use an appropriate format/encoding/whatever. Sometimes, though, some
88 unification is desirable. For example, one may want to put mail messages
89 into an archive, make HTML indices, run search indexer, etc. In such
90 situations converting messages to text in one character set and skipping
91 some binary attachments is much desirable.
95 Here is the solution - mimedecode.py!
99 This is a program to decode MIME messages. The program expects one input
100 file (either on command line or on stdin) which is treated as an RFC822
101 message, and decodes to stdout or an output file. If the file is not an
102 RFC822 message it is just copied to the output one-to-one. If the file is a
103 simple RFC822 message it is decoded as one part. If it is a MIME message
104 with multiple parts ("attachments") all parts are decoded. Decoding can be
105 controlled by command-line options.
109 First, for every part the program removes headers and parameters listed with
110 -r and -R options. Then, Subject and Content-Disposition headers (and all
111 headers listed with -d and -p options) are examined. If any of those exists,
112 they are decoded according to RFC2047. Content-Disposition header is not
113 decoded - only its "filename" parameter. Encoded header parameters violate
114 the RFC, but widely deployed anyway by ignorant coders who never even heard
115 about RFCs. Correct parameter encoding specified by RFC2231. This program
116 decodes RFC2231-encoded parameters, too.
120 Then the body of the message (or the current part) is decoded. Decoding
121 starts with looking at header Content-Transfer-Encoding. If the header
122 specifies non-8bit encoding (usually base64 or quoted-printable), the body
123 converted to 8bit. Then, if its content type is multipart (multipart/related
124 or multipart/mixed, e.g) every part is recursively decoded. If it is not
125 multipart, mailcap database is consulted to find a way to convert the body
126 to plain text. (I have no idea how mailcap can be configured on OSes other
127 than POSIX, please don't ask me; real OS users can consult my example at
128 <ulink url="http://phdru.name/Software/dotfiles/mailcap.html">http://phdru.name/Software/dotfiles/mailcap.html</ulink>).
129 The decoding process uses the first copiousoutput filter it can find. If
130 there are no filters the body just passed as is.
134 Then Content-Type header is consulted for charset. If it is not equal to the
135 current locale charset and recoding is allowed the body text is recoded.
136 Finally message headers and the body are flushed to stdout.
142 <title>OPTIONS</title>
149 Print brief usage help and exit.
156 <term>--version</term>
159 Print version and exit.
168 Recode different character sets in message bodies to the current
169 default charset; this is the default.
178 Do not recode character sets in message bodies.
184 <term>-f charset</term>
187 Force this charset to be the current default charset instead of
194 <term>-H hostname</term>
195 <term>--host=hostname</term>
198 Use this hostname in X-MIME-Autoconverted headers instead of the
205 <term>-d header1[,header2,header3...]</term>
208 Add the header(s) to a list of headers to decode; initially the
209 list contains headers "From", "To", "Cc", "Reply-To",
210 "Mail-Followup-To" and "Subject".
216 <term>-d *[,-header1,-header2,-header3...]</term>
219 This variant completely changes headers decoding. First, the list of
220 headers to decode is cleared. Then all the headers are decoded
221 except the given list of exceptions (headers listed with '-'). In
222 this mode it would be meaningless to give more than one -d options
223 but the program doesn't enforce it.
227 Please be warned that the asterisk is a shell metacharacter and
228 should be escaped or quoted. Either write -d \*,-h1,-h2 or -d
238 Clear the list of headers to decode (make it empty).
244 <term>-p header:param</term>
247 Add the pair (header, param) to a list of headers parameters to
248 decode; initially the list contains header "Content-Type",
249 parameter "name" and header "Content-Disposition", parameter
259 Clear the list of headers parameters to decode (make it empty).
265 <term>-r header</term>
268 Add the header to a list of headers to remove completely; initially
275 <term>-R header:param</term>
278 Add the pair (header, param) to a list of headers parameters to
279 remove; initially the list is empty.
285 <term>--remove-params=header</term>
288 Add the header to a list of headers from which all parameters will
289 be removed; initially the list is empty.
298 Append mask to the list of binary content types; if the message to
299 decode has a part of this type the program will pass the part as is,
300 without any additional processing.
309 Append mask to the list of error content types; if the message to
310 decode has a part of this type the program fails with ValueError.
319 Append mask to the list of content types to ignore; if the message to
320 decode has a part of this type the program will not pass it, instead
321 a line "Message body of type `%s' skipped." will be issued.
330 Append mask to the list of content types to convert to text; if the
331 message to decode has a part of this type the program will consult
332 mailcap database, find first copiousoutput filter and convert the
339 <term>-o output_file</term>
342 Useful to set the output file in case of redirected stdin:
343 <programlisting language="sh">mimedecode.py -o output_file < input_file
344 cat input_file | mimedecode.py -o output_file</programlisting>
351 The 4 list options (-beit) require more explanation. They allow a user to
352 control body decoding with great flexibility. Think about said mail archive;
353 for example, its maintainer wants to put there only texts, convert
354 Postscript/PDF to text, pass HTML and images as is, and ignore everything
360 mimedecode.py -t application/postscript -t application/pdf -b text/html
361 -b 'image/*' -i '*/*'
366 When the program decodes a message (non-MIME or a non-multipart subpart of a
367 MIME message), it consults Content-Type header. The content type is searched
368 in all 4 lists, in order "text-binary-ignore-error". If found, appropriate
369 action performed. If not found, the program search the same lists for
370 "type/*" mask (the type of "text/html" is just "text"). If found,
371 appropriate action performed. If not found, the program search the same
372 lists for "*/*" mask. If found, appropriate action performed. If not found,
373 the program uses default action, which is to decode everything to text (if
374 mailcap specifies a filter).
378 Initially all 4 lists are empty, so without any additional parameters
379 the program always uses the default decoding.
385 <title>ENVIRONMENT</title>
387 <varlistentry><term>LANG</term></varlistentry>
388 <varlistentry><term>LC_ALL</term></varlistentry>
389 <varlistentry><term>LC_CTYPE</term></varlistentry>
392 Define current locale settings. Used to determine current default charset (if
393 your Python is properly installed and configured).
401 The program may produce incorrect MIME message. The purpose of the program
402 is to decode whatever it is possible to decode, not to produce absolutely
403 correct MIME output. The incorrect parts are obvious - decoded
404 From/To/Cc/Reply-To/Mail-Followup-To/Subject headers and filenames. Other
405 than that output is correct MIME message. The program does not try to guess
406 whether the headers are correct. For example, if a message header states
407 that charset is iso8859-5, but the body is actually in utf-8 the program
408 will recode the message with the wrong charset.
414 <title>AUTHOR</title>
416 <firstname>Oleg</firstname>
417 <surname>Broytman</surname>
418 <email>phd@phdru.name</email>
424 <title>COPYRIGHT</title>
426 Copyright (C) 2001-2014 PhiloSoft Design.
432 <title>LICENSE</title>
440 <title>NO WARRANTIES</title>
442 This program is distributed in the hope that it will be useful, but WITHOUT
443 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
444 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
451 <title>SEE ALSO</title>
453 mimedecode.py home page:
454 <ulink url="http://phdru.name/Software/Python/#mimedecode">http://phdru.name/Software/Python/#mimedecode</ulink>