Mercurial > public > weighmail

comparison README.txt @ 12:b63cce680bd3

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