|
bgneal@8
|
1 =========
|
|
bgneal@8
|
2 weighmail
|
|
bgneal@8
|
3 =========
|
|
bgneal@8
|
4 An application to label your Gmail messages according to size
|
|
bgneal@8
|
5 -------------------------------------------------------------
|
|
bgneal@8
|
6
|
|
bgneal@8
|
7 :Author: Brian Neal <bgneal@gmail.com>
|
|
bgneal@8
|
8 :Version: 0.1.0
|
|
bgneal@12
|
9 :Date: May 20, 2012
|
|
bgneal@8
|
10 :Home Page: https://bitbucket.org/bgneal/weighmail/
|
|
bgneal@12
|
11 :License: New BSD License (see LICENSE.txt)
|
|
bgneal@8
|
12 :Support: https://bitbucket.org/bgneal/weighmail/issues
|
|
bgneal@8
|
13
|
|
bgneal@8
|
14
|
|
bgneal@8
|
15 Overview
|
|
bgneal@8
|
16 --------
|
|
bgneal@8
|
17
|
|
bgneal@8
|
18 ``weighmail`` is a program that analyzes your Gmail and applies labels to your
|
|
bgneal@8
|
19 messages according to their size. This is useful if you are close to reaching
|
|
bgneal@8
|
20 your quota as it allows you to quickly identify large messages. You have
|
|
bgneal@8
|
21 complete control over the rules used to create the labels.
|
|
bgneal@8
|
22
|
|
bgneal@8
|
23
|
|
bgneal@8
|
24 Installation
|
|
bgneal@8
|
25 ------------
|
|
bgneal@8
|
26
|
|
bgneal@8
|
27 ``weighmail`` can be installed using Pip_::
|
|
bgneal@8
|
28
|
|
bgneal@14
|
29 $ pip install weighmail
|
|
bgneal@8
|
30
|
|
bgneal@8
|
31 Alternatively you can download a tarball and install with::
|
|
bgneal@8
|
32
|
|
bgneal@8
|
33 $ python setup.py install
|
|
bgneal@8
|
34
|
|
bgneal@8
|
35 ``weighmail`` depends on the IMAPClient_ library. This library is automatically
|
|
bgneal@8
|
36 installed if you use Pip_.
|
|
bgneal@8
|
37
|
|
bgneal@8
|
38 Gmail Notes
|
|
bgneal@8
|
39 -----------
|
|
bgneal@8
|
40
|
|
bgneal@8
|
41 In case it isn't clear, ``weighmail`` works with Gmail_. You must have a Gmail
|
|
bgneal@8
|
42 account with `IMAP support turned on`_. Please go into your settings and verify
|
|
bgneal@8
|
43 IMAP support is turned on before proceeding.
|
|
bgneal@8
|
44
|
|
bgneal@8
|
45 If you are using `two-step verification`_ on your Gmail account (**and you
|
|
bgneal@8
|
46 really should be**), you `need to generate an application specific password`_
|
|
bgneal@8
|
47 for ``weighmail`` to use. In this case you will use an application specific
|
|
bgneal@8
|
48 password instead of your normal password when running ``weighmail``.
|
|
bgneal@8
|
49
|
|
bgneal@8
|
50
|
|
bgneal@8
|
51 Usage
|
|
bgneal@8
|
52 -----
|
|
bgneal@8
|
53
|
|
bgneal@8
|
54 ``weighmail`` can accept options from a configuration file and/or the
|
|
bgneal@8
|
55 command-line. Command-line arguments always take precedence over options found
|
|
bgneal@8
|
56 in the configuration file.
|
|
bgneal@8
|
57
|
|
bgneal@8
|
58 Command-Line Arguments
|
|
bgneal@8
|
59 ~~~~~~~~~~~~~~~~~~~~~~
|
|
bgneal@8
|
60
|
|
bgneal@8
|
61 ``weighmail`` takes a fair number of arguments on the command-line. Most of
|
|
bgneal@8
|
62 these can be omitted however, as they all have sensible defaults. In fact, the
|
|
bgneal@8
|
63 simplest way to run ``weighmail`` is as follows::
|
|
bgneal@8
|
64
|
|
bgneal@8
|
65 $ weighmail --labels big:1MB-5MB huge:5MB-10MB enormous:10MB-
|
|
bgneal@8
|
66
|
|
bgneal@8
|
67 This example demonstrates:
|
|
bgneal@8
|
68
|
|
bgneal@8
|
69 * A *big* label will be applied to messages between 1 and 5 Megabytes
|
|
bgneal@8
|
70 * A *huge* label will be applied to messages between 5 and 10 Megabytes
|
|
bgneal@8
|
71 * An *enormous* label will be applied to messages 10 MB and bigger
|
|
bgneal@8
|
72 * Since no ``user`` or ``password`` options were supplied on the command-line,
|
|
bgneal@8
|
73 ``weighmail`` will interactively prompt for them. Neither will be echoed out
|
|
bgneal@8
|
74 for privacy reasons.
|
|
bgneal@8
|
75
|
|
bgneal@8
|
76 To see a list of all command-line options::
|
|
bgneal@8
|
77
|
|
bgneal@8
|
78 $ weighmail --help
|
|
bgneal@8
|
79
|
|
bgneal@8
|
80 Some notes on the options follows.
|
|
bgneal@8
|
81
|
|
bgneal@8
|
82 * The ``--config`` option is used to specify a configuration file that
|
|
bgneal@8
|
83 ``weighmail`` will read for options. Any options supplied on the command-line
|
|
bgneal@8
|
84 will override any options from this file. In particular, if you specify any
|
|
bgneal@8
|
85 label rules on the command-line, all label rules in the configuration file
|
|
bgneal@8
|
86 will be ignored.
|
|
bgneal@8
|
87 * The ``--folder`` option can be used to specify which Gmail label to search for
|
|
bgneal@8
|
88 messages. This defaults to your *All Mail* label.
|
|
bgneal@8
|
89 * The ``--user`` and ``--password`` options are used to specify which Gmail
|
|
bgneal@8
|
90 account to log into. If these are not supplied, and also omitted from a config
|
|
bgneal@8
|
91 file (or if no config file is being used), ``weighmail`` will prompt you for
|
|
bgneal@8
|
92 these options.
|
|
bgneal@8
|
93 * The ``--labels`` argument is how you specify the rules for labeling your
|
|
bgneal@8
|
94 messages. See the sub-section below for more detail on this syntax.
|
|
bgneal@8
|
95 * The ``--host``, ``--port``, and ``--nossl`` arguments are for advanced use
|
|
bgneal@8
|
96 only, and may in fact not work. The defaults should work for most people, and
|
|
bgneal@8
|
97 will connect you to ``imap.gmail.com`` port 993 using SSL.
|
|
bgneal@8
|
98
|
|
bgneal@8
|
99 The --labels argument syntax
|
|
bgneal@8
|
100 ++++++++++++++++++++++++++++
|
|
bgneal@8
|
101
|
|
bgneal@8
|
102 To specify label rules on the command-line, use the following syntax::
|
|
bgneal@8
|
103
|
|
bgneal@8
|
104 $ weighmail --labels name:min-max [name:min-max] ...
|
|
bgneal@8
|
105
|
|
bgneal@8
|
106 Where:
|
|
bgneal@8
|
107
|
|
bgneal@8
|
108 * *name* is the name of the label. Note that Gmail labels cannot have spaces in
|
|
bgneal@8
|
109 them.
|
|
bgneal@8
|
110 * *min* and *max* specify the message size range in bytes. Either one, but not
|
|
bgneal@8
|
111 both, may be omitted (but the dash must remain). You may use the suffixes
|
|
bgneal@8
|
112 ``KB``, ``MB``, or ``GB`` to indicate kilobytes, Megabytes, or Gigabytes,
|
|
bgneal@8
|
113 respectively.
|
|
bgneal@8
|
114
|
|
bgneal@8
|
115 Another example::
|
|
bgneal@8
|
116
|
|
bgneal@8
|
117 $ weighmail --labels normal:-2MB big:2MB-7MB huge:7MB-
|
|
bgneal@8
|
118
|
|
bgneal@8
|
119 In all these examples the label ranges do not overlap. This does not have to be
|
|
bgneal@8
|
120 the case; overlapping ranges may be defined if desired.
|
|
bgneal@8
|
121
|
|
bgneal@8
|
122
|
|
bgneal@8
|
123 Configuration File
|
|
bgneal@8
|
124 ~~~~~~~~~~~~~~~~~~
|
|
bgneal@8
|
125
|
|
bgneal@8
|
126 If you specify the ``--config=filename`` option on the command-line,
|
|
bgneal@8
|
127 ``weighmail`` will parse this file for options. Please see the included
|
|
bgneal@8
|
128 `sample-weighmail.ini` file for the syntax and option descriptions.
|
|
bgneal@8
|
129
|
|
bgneal@8
|
130 Again, note that command-line arguments take precedence over options found in
|
|
bgneal@8
|
131 the configuration file. If you specify *any* label rules on the command-line,
|
|
bgneal@8
|
132 *all* label rules in the configuration file are ignored.
|
|
bgneal@8
|
133
|
|
bgneal@8
|
134
|
|
bgneal@8
|
135 Thanks
|
|
bgneal@8
|
136 ~~~~~~
|
|
bgneal@8
|
137
|
|
bgneal@8
|
138 A big thank-you to Menno Smits, the author of the IMAPClient_ library. This
|
|
bgneal@8
|
139 application would have been considerably more complicated if the awesome
|
|
bgneal@8
|
140 IMAPClient library did not exist.
|
|
bgneal@8
|
141
|
|
bgneal@8
|
142
|
|
bgneal@8
|
143 .. _Pip: http://pypi.python.org/pypi/pip
|
|
bgneal@8
|
144 .. _Gmail: http://mail.google.com/
|
|
bgneal@8
|
145 .. _IMAP support turned on: http://support.google.com/mail/bin/answer.py?hl=en&answer=77695
|
|
bgneal@8
|
146 .. _two-step verification: http://support.google.com/accounts/bin/answer.py?hl=en&answer=180744
|
|
bgneal@8
|
147 .. _need to generate an application specific password: http://support.google.com/accounts/bin/answer.py?hl=en&answer=185833&topic=1056283&ctx=topic
|
|
bgneal@8
|
148 .. _IMAPClient: http://pypi.python.org/pypi/IMAPClient/
|
