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