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 header1[,header2,header3,...]:param1[,param2,param3,...]</option>
60 <option>-p *[,-header1,-header2,-header3,...]:param1[,param2,param3,...]</option>
63 <option>-p header1[,header2,header3,...]:*[,-param1,-param2,-param3,...]</option>
66 <option>-p *[,-header1,-header2,-header3,...]:*[,-param1,-param2,-param3,...]</option>
69 <option>-r header1[,header2,header3...]</option>
72 <option>-r *[,-header1,-header2,-header3...]</option>
75 <option>-R header1[,header2,header3,...]:param1[,param2,param3,...]</option>
78 <option>-R *[,-header1,-header2,-header3,...]:param1[,param2,param3,...]</option>
81 <option>-R header1[,header2,header3,...]:*[,-param1,-param2,-param3,...]</option>
84 <option>-R *[,-header1,-header2,-header3,...]:*[,-param1,-param2,-param3,...]</option>
87 <option>-beit mask</option>
90 <option>-o output_file</option>
92 <arg choice="opt">input_file
93 <arg choice="opt">output_file</arg>
100 <title>DESCRIPTION</title>
102 Mail users, especially in non-English countries, often find that mail
103 messages arrived in different formats, with different content types, in
104 different encodings and charsets. Usually it is good because it allows to
105 use an appropriate format/encoding/whatever. Sometimes, though, some
106 unification is desirable. For example, one may want to put mail messages
107 into an archive, make HTML indices, run search indexer, etc. In such
108 situations converting messages to text in one character set and skipping
109 some binary attachments is much desirable.
113 Here is the solution - mimedecode.py!
117 This is a program to decode MIME messages. The program expects one input
118 file (either on command line or on stdin) which is treated as an RFC822
119 message, and decodes to stdout or an output file. If the file is not an
120 RFC822 message it is just copied to the output one-to-one. If the file is a
121 simple RFC822 message it is decoded as one part. If it is a MIME message
122 with multiple parts ("attachments") all parts are decoded. Decoding can be
123 controlled by command-line options.
127 First, for every part the program removes headers and parameters listed with
128 -r and -R options. Then, Subject and Content-Disposition headers (and all
129 headers listed with -d and -p options) are examined. If any of those exists,
130 they are decoded according to RFC2047. Content-Disposition header is not
131 decoded - only its "filename" parameter. Encoded header parameters violate
132 the RFC, but widely deployed anyway by ignorant coders who never even heard
133 about RFCs. Correct parameter encoding specified by RFC2231. This program
134 decodes RFC2231-encoded parameters, too.
138 Then the body of the message (or the current part) is decoded. Decoding
139 starts with looking at header Content-Transfer-Encoding. If the header
140 specifies non-8bit encoding (usually base64 or quoted-printable), the body
141 converted to 8bit. Then, if its content type is multipart (multipart/related
142 or multipart/mixed, e.g) every part is recursively decoded. If it is not
143 multipart, mailcap database is consulted to find a way to convert the body
144 to plain text. (I have no idea how mailcap can be configured on OSes other
145 than POSIX, please don't ask me; real OS users can consult my example at
146 <ulink url="http://phdru.name/Software/dotfiles/mailcap.html">http://phdru.name/Software/dotfiles/mailcap.html</ulink>).
147 The decoding process uses the first copiousoutput filter it can find. If
148 there are no filters the body just passed as is.
152 Then Content-Type header is consulted for charset. If it is not equal to the
153 current locale charset and recoding is allowed the body text is recoded.
154 Finally message headers and the body are flushed to stdout.
160 Please be warned that in the following options asterisk is a shell
161 metacharacter and should be escaped or quoted. Either write -d \*,-h1,-h2
162 or -d '*,-h1,-h2' or such.
167 <title>OPTIONS</title>
174 Print brief usage help and exit.
181 <term>--version</term>
184 Print version and exit.
193 Recode different character sets in message bodies to the current
194 default charset; this is the default.
203 Do not recode character sets in message bodies.
209 <term>-f charset</term>
212 Force this charset to be the current default charset instead of
219 <term>-H hostname</term>
220 <term>--host=hostname</term>
223 Use this hostname in X-MIME-Autoconverted headers instead of the
230 <term>-d header1[,header2,header3...]</term>
233 Add the header(s) to a list of headers to decode; initially the
234 list contains headers "From", "To", "Cc", "Reply-To",
235 "Mail-Followup-To" and "Subject".
241 <term>-d *[,-header1,-header2,-header3...]</term>
244 This variant completely changes headers decoding. First, the list of
245 headers to decode is cleared. Then all the headers are decoded
246 except the given list of exceptions (headers listed with '-'). In
247 this mode it would be meaningless to give more than one -d options
248 but the program doesn't enforce it.
257 Clear the list of headers to decode (make it empty).
263 <term>-p header1[,header2,header3,...]:param1[,param2,param3,...]</term>
266 Add the parameters(s) to a list of headers parameters to decode;
267 the parameters will be decoded only for the given header(s).
268 Initially the list contains header "Content-Type", parameter "name";
269 and header "Content-Disposition", parameter "filename".
275 <term>-p *[,-header1,-header2,-header3,...]:param1[,param2,param3,...]</term>
278 Add the parameters(s) to a list of headers parameters to decode;
279 the parameters will be decoded for all headers except the given
286 <term>-p header1[,header2,header3,...]:*[,-param1,-param2,-param3,...]</term>
289 Decode all parameters except listed for the given list of headers.
295 <term>-p *[,-header1,-header2,-header3,...]:*[,-param1,-param2,-param3,...]</term>
298 Decode all parameters except listed for all headers (except listed).
307 Clear the list of headers parameters to decode (make it empty).
313 <term>-r header1[,header2,header3...]</term>
316 Add the header(s) to a list of headers to remove completely;
317 initially the list is empty.
323 <term>-r *[,-header1,-header2,-header3...]</term>
326 Remove all headers except listed.
332 <term>-R header1[,header2,header3,...]:param1[,param2,param3,...]</term>
335 Add the parameters(s) to a list of headers parameters to remove;
336 the parameters will be decoded only for the given header(s).
337 Initially the list is empty.
343 <term>-R *[,-header1,-header2,-header3,...]:param1[,param2,param3,...]</term>
347 <term>-R header1[,header2,header3,...]:*[,-param1,-param2,-param3,...]</term>
351 <term>-R *[,-header1,-header2,-header3,...]:*[,-param1,-param2,-param3,...]</term>
354 Remove listed parameters (or all parameters except listed) frome
355 these headers (or from all headers except listed).
364 Append mask to the list of binary content types; if the message to
365 decode has a part of this type the program will pass the part as is,
366 without any additional processing.
375 Append mask to the list of error content types; if the message to
376 decode has a part of this type the program fails with ValueError.
385 Append mask to the list of content types to ignore; if the message to
386 decode has a part of this type the program will not pass it, instead
387 a line "Message body of type `%s' skipped." will be issued.
396 Append mask to the list of content types to convert to text; if the
397 message to decode has a part of this type the program will consult
398 mailcap database, find first copiousoutput filter and convert the
405 <term>-o output_file</term>
408 Useful to set the output file in case of redirected stdin:
409 <programlisting language="sh">mimedecode.py -o output_file < input_file
410 cat input_file | mimedecode.py -o output_file</programlisting>
417 The 4 list options (-beit) require more explanation. They allow a user to
418 control body decoding with great flexibility. Think about said mail archive;
419 for example, its maintainer wants to put there only texts, convert
420 Postscript/PDF to text, pass HTML and images as is, and ignore everything
426 mimedecode.py -t application/postscript -t application/pdf -b text/html
427 -b 'image/*' -i '*/*'
432 When the program decodes a message (non-MIME or a non-multipart subpart of a
433 MIME message), it consults Content-Type header. The content type is searched
434 in all 4 lists, in order "text-binary-ignore-error". If found, appropriate
435 action performed. If not found, the program search the same lists for
436 "type/*" mask (the type of "text/html" is just "text"). If found,
437 appropriate action performed. If not found, the program search the same
438 lists for "*/*" mask. If found, appropriate action performed. If not found,
439 the program uses default action, which is to decode everything to text (if
440 mailcap specifies a filter).
444 Initially all 4 lists are empty, so without any additional parameters
445 the program always uses the default decoding.
451 <title>ENVIRONMENT</title>
453 <varlistentry><term>LANG</term></varlistentry>
454 <varlistentry><term>LC_ALL</term></varlistentry>
455 <varlistentry><term>LC_CTYPE</term></varlistentry>
458 Define current locale settings. Used to determine current default charset (if
459 your Python is properly installed and configured).
467 The program may produce incorrect MIME message. The purpose of the program
468 is to decode whatever it is possible to decode, not to produce absolutely
469 correct MIME output. The incorrect parts are obvious - decoded
470 From/To/Cc/Reply-To/Mail-Followup-To/Subject headers and filenames. Other
471 than that output is correct MIME message. The program does not try to guess
472 whether the headers are correct. For example, if a message header states
473 that charset is iso8859-5, but the body is actually in utf-8 the program
474 will recode the message with the wrong charset.
480 <title>AUTHOR</title>
482 <firstname>Oleg</firstname>
483 <surname>Broytman</surname>
484 <email>phd@phdru.name</email>
490 <title>COPYRIGHT</title>
492 Copyright (C) 2001-2014 PhiloSoft Design.
498 <title>LICENSE</title>
506 <title>NO WARRANTIES</title>
508 This program is distributed in the hope that it will be useful, but WITHOUT
509 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
510 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
517 <title>SEE ALSO</title>
519 mimedecode.py home page:
520 <ulink url="http://phdru.name/Software/Python/#mimedecode">http://phdru.name/Software/Python/#mimedecode</ulink>