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>--set-header header:value</option>
90 <option>-beit mask</option>
93 <option>-o output_file</option>
95 <arg choice="opt">input_file
96 <arg choice="opt">output_file</arg>
103 <title>DESCRIPTION</title>
105 Mail users, especially in non-English countries, often find that mail
106 messages arrived in different formats, with different content types, in
107 different encodings and charsets. Usually it is good because it allows to
108 use an appropriate format/encoding/whatever. Sometimes, though, some
109 unification is desirable. For example, one may want to put mail messages
110 into an archive, make HTML indices, run search indexer, etc. In such
111 situations converting messages to text in one character set and skipping
112 some binary attachments is much desirable.
116 Here is the solution - mimedecode.py!
120 This is a program to decode MIME messages. The program expects one input
121 file (either on command line or on stdin) which is treated as an RFC822
122 message, and decodes to stdout or an output file. If the file is not an
123 RFC822 message it is just copied to the output one-to-one. If the file is a
124 simple RFC822 message it is decoded as one part. If it is a MIME message
125 with multiple parts ("attachments") all parts are decoded. Decoding can be
126 controlled by command-line options.
130 First, for every part the program removes headers and parameters listed with
131 -r and -R options. Then, Subject and Content-Disposition headers (and all
132 headers listed with -d and -p options) are examined. If any of those exists,
133 they are decoded according to RFC2047. Content-Disposition header is not
134 decoded - only its "filename" parameter. Encoded header parameters violate
135 the RFC, but widely deployed anyway by ignorant coders who never even heard
136 about RFCs. Correct parameter encoding specified by RFC2231. This program
137 decodes RFC2231-encoded parameters, too.
141 Then the body of the message (or the current part) is decoded. Decoding
142 starts with looking at header Content-Transfer-Encoding. If the header
143 specifies non-8bit encoding (usually base64 or quoted-printable), the body
144 converted to 8bit. Then, if its content type is multipart (multipart/related
145 or multipart/mixed, e.g) every part is recursively decoded. If it is not
146 multipart, mailcap database is consulted to find a way to convert the body
147 to plain text. (I have no idea how mailcap can be configured on OSes other
148 than POSIX, please don't ask me; real OS users can consult my example at
149 <ulink url="http://phdru.name/Software/dotfiles/mailcap.html">http://phdru.name/Software/dotfiles/mailcap.html</ulink>).
150 The decoding process uses the first copiousoutput filter it can find. If
151 there are no filters the body just passed as is.
155 Then Content-Type header is consulted for charset. If it is not equal to the
156 current locale charset and recoding is allowed the body text is recoded.
157 Finally message headers and the body are flushed to stdout.
163 Please be warned that in the following options asterisk is a shell
164 metacharacter and should be escaped or quoted. Either write -d \*,-h1,-h2
165 or -d '*,-h1,-h2' or such.
170 <title>OPTIONS</title>
177 Print brief usage help and exit.
184 <term>--version</term>
187 Print version and exit.
196 Recode different character sets in message bodies to the current
197 default charset; this is the default.
206 Do not recode character sets in message bodies.
212 <term>-f charset</term>
215 Force this charset to be the current default charset instead of
222 <term>-H hostname</term>
223 <term>--host=hostname</term>
226 Use this hostname in X-MIME-Autoconverted headers instead of the
233 <term>-d header1[,header2,header3...]</term>
236 Add the header(s) to a list of headers to decode; initially the
237 list contains headers "From", "To", "Cc", "Reply-To",
238 "Mail-Followup-To" and "Subject".
244 <term>-d *[,-header1,-header2,-header3...]</term>
247 This variant completely changes headers decoding. First, the list of
248 headers to decode is cleared. Then all the headers are decoded
249 except the given list of exceptions (headers listed with '-'). In
250 this mode it would be meaningless to give more than one -d options
251 but the program doesn't enforce it.
260 Clear the list of headers to decode (make it empty).
266 <term>-p header1[,header2,header3,...]:param1[,param2,param3,...]</term>
269 Add the parameters(s) to a list of headers parameters to decode;
270 the parameters will be decoded only for the given header(s).
271 Initially the list contains header "Content-Type", parameter "name";
272 and header "Content-Disposition", parameter "filename".
278 <term>-p *[,-header1,-header2,-header3,...]:param1[,param2,param3,...]</term>
281 Add the parameters(s) to a list of headers parameters to decode;
282 the parameters will be decoded for all headers except the given
289 <term>-p header1[,header2,header3,...]:*[,-param1,-param2,-param3,...]</term>
292 Decode all parameters except listed for the given list of headers.
298 <term>-p *[,-header1,-header2,-header3,...]:*[,-param1,-param2,-param3,...]</term>
301 Decode all parameters except listed for all headers (except listed).
310 Clear the list of headers parameters to decode (make it empty).
316 <term>-r header1[,header2,header3...]</term>
319 Add the header(s) to a list of headers to remove completely;
320 initially the list is empty.
326 <term>-r *[,-header1,-header2,-header3...]</term>
329 Remove all headers except listed.
335 <term>-R header1[,header2,header3,...]:param1[,param2,param3,...]</term>
338 Add the parameters(s) to a list of headers parameters to remove;
339 the parameters will be decoded only for the given header(s).
340 Initially the list is empty.
346 <term>-R *[,-header1,-header2,-header3,...]:param1[,param2,param3,...]</term>
350 <term>-R header1[,header2,header3,...]:*[,-param1,-param2,-param3,...]</term>
354 <term>-R *[,-header1,-header2,-header3,...]:*[,-param1,-param2,-param3,...]</term>
357 Remove listed parameters (or all parameters except listed) frome
358 these headers (or from all headers except listed).
364 <term>--set-header header:value</term>
367 The program sets or changes value for the header to the given value
368 (only at the top-level message).
377 Append mask to the list of binary content types; if the message to
378 decode has a part of this type the program will pass the part as is,
379 without any additional processing.
388 Append mask to the list of error content types; if the message to
389 decode has a part of this type the program fails with ValueError.
398 Append mask to the list of content types to ignore; if the message to
399 decode has a part of this type the program will not pass it, instead
400 a line "Message body of type `%s' skipped." will be issued.
409 Append mask to the list of content types to convert to text; if the
410 message to decode has a part of this type the program will consult
411 mailcap database, find first copiousoutput filter and convert the
418 <term>-o output_file</term>
421 Useful to set the output file in case of redirected stdin:
422 <programlisting language="sh">mimedecode.py -o output_file < input_file
423 cat input_file | mimedecode.py -o output_file</programlisting>
430 The 4 list options (-beit) require more explanation. They allow a user to
431 control body decoding with great flexibility. Think about said mail archive;
432 for example, its maintainer wants to put there only texts, convert
433 Postscript/PDF to text, pass HTML and images as is, and ignore everything
439 mimedecode.py -t application/postscript -t application/pdf -b text/html
440 -b 'image/*' -i '*/*'
445 When the program decodes a message (non-MIME or a non-multipart subpart of a
446 MIME message), it consults Content-Type header. The content type is searched
447 in all 4 lists, in order "text-binary-ignore-error". If found, appropriate
448 action performed. If not found, the program search the same lists for
449 "type/*" mask (the type of "text/html" is just "text"). If found,
450 appropriate action performed. If not found, the program search the same
451 lists for "*/*" mask. If found, appropriate action performed. If not found,
452 the program uses default action, which is to decode everything to text (if
453 mailcap specifies a filter).
457 Initially all 4 lists are empty, so without any additional parameters
458 the program always uses the default decoding.
464 <title>ENVIRONMENT</title>
466 <varlistentry><term>LANG</term></varlistentry>
467 <varlistentry><term>LC_ALL</term></varlistentry>
468 <varlistentry><term>LC_CTYPE</term></varlistentry>
471 Define current locale settings. Used to determine current default charset (if
472 your Python is properly installed and configured).
480 The program may produce incorrect MIME message. The purpose of the program
481 is to decode whatever it is possible to decode, not to produce absolutely
482 correct MIME output. The incorrect parts are obvious - decoded
483 From/To/Cc/Reply-To/Mail-Followup-To/Subject headers and filenames. Other
484 than that output is correct MIME message. The program does not try to guess
485 whether the headers are correct. For example, if a message header states
486 that charset is iso8859-5, but the body is actually in utf-8 the program
487 will recode the message with the wrong charset.
493 <title>AUTHOR</title>
495 <firstname>Oleg</firstname>
496 <surname>Broytman</surname>
497 <email>phd@phdru.name</email>
503 <title>COPYRIGHT</title>
505 Copyright (C) 2001-2014 PhiloSoft Design.
511 <title>LICENSE</title>
519 <title>NO WARRANTIES</title>
521 This program is distributed in the hope that it will be useful, but WITHOUT
522 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
523 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
530 <title>SEE ALSO</title>
532 mimedecode.py home page:
533 <ulink url="http://phdru.name/Software/Python/#mimedecode">http://phdru.name/Software/Python/#mimedecode</ulink>