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>--set-param header:param=value</option>
93 <option>-Bbeit mask</option>
96 <option>-O dest_dir</option>
99 <option>-o output_file</option>
101 <arg choice="opt">input_file
102 <arg choice="opt">output_file</arg>
109 <title>DESCRIPTION</title>
111 Mail users, especially in non-English countries, often find that mail
112 messages arrived in different formats, with different content types, in
113 different encodings and charsets. Usually it is good because it allows to
114 use an appropriate format/encoding/whatever. Sometimes, though, some
115 unification is desirable. For example, one may want to put mail messages
116 into an archive, make HTML indices, run search indexer, etc. In such
117 situations converting messages to text in one character set and skipping
118 some binary attachments is much desirable.
122 Here is the solution - mimedecode.py!
126 This is a program to decode MIME messages. The program expects one input
127 file (either on command line or on stdin) which is treated as an RFC822
128 message, and decodes to stdout or an output file. If the file is not an
129 RFC822 message it is just copied to the output one-to-one. If the file is a
130 simple RFC822 message it is decoded as one part. If it is a MIME message
131 with multiple parts ("attachments") all parts are decoded. Decoding can be
132 controlled by command-line options.
136 First, for every part the program removes headers and parameters listed with
137 -r and -R options. Then, Subject and Content-Disposition headers (and all
138 headers listed with -d and -p options) are examined. If any of those exists,
139 they are decoded according to RFC2047. Content-Disposition header is not
140 decoded - only its "filename" parameter. Encoded header parameters violate
141 the RFC, but widely deployed anyway by ignorant coders who never even heard
142 about RFCs. Correct parameter encoding specified by RFC2231. This program
143 decodes RFC2231-encoded parameters, too.
147 Then the body of the message (or the current part) is decoded. Decoding
148 starts with looking at header Content-Transfer-Encoding. If the header
149 specifies non-8bit encoding (usually base64 or quoted-printable), the body
150 converted to 8bit. Then, if its content type is multipart (multipart/related
151 or multipart/mixed, e.g) every part is recursively decoded. If it is not
152 multipart, mailcap database is consulted to find a way to convert the body
153 to plain text. (I have no idea how mailcap can be configured on OSes other
154 than POSIX, please don't ask me; real OS users can consult my example at
155 <ulink url="http://phdru.name/Software/dotfiles/mailcap.html">http://phdru.name/Software/dotfiles/mailcap.html</ulink>).
156 The decoding process uses the first copiousoutput filter it can find. If
157 there are no filters the body just passed as is.
161 Then Content-Type header is consulted for charset. If it is not equal to the
162 current locale charset and recoding is allowed the body text is recoded.
163 Finally message headers and the body are flushed to stdout.
169 Please be warned that in the following options asterisk is a shell
170 metacharacter and should be escaped or quoted. Either write -d \*,-h1,-h2
171 or -d '*,-h1,-h2' or such.
176 <title>OPTIONS</title>
183 Print brief usage help and exit.
190 <term>--version</term>
193 Print version and exit.
202 Recode different character sets in message bodies to the current
203 default charset; this is the default.
212 Do not recode character sets in message bodies.
218 <term>-f charset</term>
221 Force this charset to be the current default charset instead of
228 <term>-H hostname</term>
229 <term>--host=hostname</term>
232 Use this hostname in X-MIME-Autoconverted headers instead of the
239 <term>-d header1[,header2,header3...]</term>
242 Add the header(s) to a list of headers to decode; initially the
243 list contains headers "From", "To", "Cc", "Reply-To",
244 "Mail-Followup-To" and "Subject".
250 <term>-d *[,-header1,-header2,-header3...]</term>
253 This variant completely changes headers decoding. First, the list of
254 headers to decode is cleared. Then all the headers are decoded
255 except the given list of exceptions (headers listed with '-'). In
256 this mode it would be meaningless to give more than one -d options
257 but the program doesn't enforce it.
266 Clear the list of headers to decode (make it empty).
272 <term>-p header1[,header2,header3,...]:param1[,param2,param3,...]</term>
275 Add the parameters(s) to a list of headers parameters to decode;
276 the parameters will be decoded only for the given header(s).
277 Initially the list contains header "Content-Type", parameter "name";
278 and header "Content-Disposition", parameter "filename".
284 <term>-p *[,-header1,-header2,-header3,...]:param1[,param2,param3,...]</term>
287 Add the parameters(s) to a list of headers parameters to decode;
288 the parameters will be decoded for all headers except the given
295 <term>-p header1[,header2,header3,...]:*[,-param1,-param2,-param3,...]</term>
298 Decode all parameters except listed for the given list of headers.
304 <term>-p *[,-header1,-header2,-header3,...]:*[,-param1,-param2,-param3,...]</term>
307 Decode all parameters except listed for all headers (except listed).
316 Clear the list of headers parameters to decode (make it empty).
322 <term>-r header1[,header2,header3...]</term>
325 Add the header(s) to a list of headers to remove completely;
326 initially the list is empty.
332 <term>-r *[,-header1,-header2,-header3...]</term>
335 Remove all headers except listed.
341 <term>-R header1[,header2,header3,...]:param1[,param2,param3,...]</term>
344 Add the parameters(s) to a list of headers parameters to remove;
345 the parameters will be decoded only for the given header(s).
346 Initially the list is empty.
352 <term>-R *[,-header1,-header2,-header3,...]:param1[,param2,param3,...]</term>
356 <term>-R header1[,header2,header3,...]:*[,-param1,-param2,-param3,...]</term>
360 <term>-R *[,-header1,-header2,-header3,...]:*[,-param1,-param2,-param3,...]</term>
363 Remove listed parameters (or all parameters except listed) frome
364 these headers (or from all headers except listed).
370 <term>--set-header header:value</term>
373 The program sets or changes value for the header to the given value
374 (only at the top-level message).
380 <term>--set-param header:param=value</term>
383 The program sets or changes value for the header's parameter to the
384 given value (only at the top-level message). The header must exist.
393 Append mask to the list of binary content types; if the message to
394 decode has a part of this type the program will pass the part as is,
395 without any additional processing.
404 Append mask to the list of binary content types that will be not
405 content-transfer-decoded (will be left as base64 or such).
414 Append mask to the list of error content types; if the message to
415 decode has a part of this type the program fails with ValueError.
424 Append mask to the list of content types to ignore; if the message to
425 decode has a part of this type the program will not pass it, instead
426 a line "Message body of type `%s' skipped." will be issued.
435 Append mask to the list of content types to convert to text; if the
436 message to decode has a part of this type the program will consult
437 mailcap database, find first copiousoutput filter and convert the
444 <term>-O dest_dir</term>
447 Set destination directory for the output files. Default is current
454 <term>-o output_file</term>
457 Set the output file. Uses destination directory from option -O.
458 Also useful in case of redirected stdin:
459 <programlisting language="sh">mimedecode.py -o output_file < input_file
460 cat input_file | mimedecode.py -o output_file</programlisting>
467 The 5 list options (-Bbeit) require more explanation. They allow a user to
468 control body decoding with great flexibility. Think about said mail archive;
469 for example, its maintainer wants to put there only texts, convert
470 Postscript/PDF to text, pass HTML and images as is, and ignore everything
476 mimedecode.py -t application/postscript -t application/pdf -b text/html
477 -b 'image/*' -i '*/*'
482 When the program decodes a message (non-MIME or a non-multipart subpart of a
483 MIME message), it consults Content-Type header. The content type is searched
484 in all 4 lists, in order "text-binary-ignore-error". If found, appropriate
485 action performed. If not found, the program search the same lists for
486 "type/*" mask (the type of "text/html" is just "text"). If found,
487 appropriate action performed. If not found, the program search the same
488 lists for "*/*" mask. If found, appropriate action performed. If not found,
489 the program uses default action, which is to decode everything to text (if
490 mailcap specifies a filter).
494 Initially all 4 lists are empty, so without any additional parameters
495 the program always uses the default decoding.
501 <title>ENVIRONMENT</title>
503 <varlistentry><term>LANG</term></varlistentry>
504 <varlistentry><term>LC_ALL</term></varlistentry>
505 <varlistentry><term>LC_CTYPE</term></varlistentry>
508 Define current locale settings. Used to determine current default charset (if
509 your Python is properly installed and configured).
517 The program may produce incorrect MIME message. The purpose of the program
518 is to decode whatever it is possible to decode, not to produce absolutely
519 correct MIME output. The incorrect parts are obvious - decoded
520 From/To/Cc/Reply-To/Mail-Followup-To/Subject headers and filenames. Other
521 than that output is correct MIME message. The program does not try to guess
522 whether the headers are correct. For example, if a message header states
523 that charset is iso8859-5, but the body is actually in utf-8 the program
524 will recode the message with the wrong charset.
530 <title>AUTHOR</title>
532 <firstname>Oleg</firstname>
533 <surname>Broytman</surname>
534 <email>phd@phdru.name</email>
540 <title>COPYRIGHT</title>
542 Copyright (C) 2001-2014 PhiloSoft Design.
548 <title>LICENSE</title>
556 <title>NO WARRANTIES</title>
558 This program is distributed in the hope that it will be useful, but WITHOUT
559 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
560 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
567 <title>SEE ALSO</title>
569 mimedecode.py home page:
570 <ulink url="http://phdru.name/Software/Python/#mimedecode">http://phdru.name/Software/Python/#mimedecode</ulink>