PyMailq released to v0.6.0

.coveragerc

@@ -0,0 +1,8 @@
+[report]
+exclude_lines =
+    pragma: no cover
+
+[run]
+omit =
+    */.local/share/virtualenvs/*
+    tests/*

.gitignore

@@ -20,6 +20,7 @@ var/
 *.egg-info/
 .installed.cfg
 *.egg
+MANIFEST
 
 # Installer logs
 pip-log.txt
@@ -39,18 +40,10 @@ coverage.xml
 # Sphinx documentation
 .buildinfo
 docs/_build/
-
-# gh_pages workdir for parallel checkout
-# created using the following cmd from the repo root:
-#   mkdir docs/gh_pages
-#   sh /usr/share/doc/git/contrib/workdir/git-new-workdir . docs/gh_pages/html
-#
-# Building the docs (from the docs dir):
-#   make html && make man
-#   rsync -nacv --delete --exclude '.git*' \
-#                        --exclude '.buildinfo' \
-#                        --exclude '.nojekyll' _build/html/ gh_pages/html/
 docs/gh_pages/
 
 # Vim swap files
 .*.swp
+
+# pycharm project
+.idea

CHANGES

@@ -1,9 +1,20 @@
 pymailq - Simple mail queue management
-=========================================
+======================================
 
 Contact: Denis Pompilio (jawa) <[email protected]>
 https://github.com/outini/pymailq
 
+== v0.6.0 16/08/2017 ===
+    * Pqshell now have usage and options
+    * Pqshell can now show pymailq package version
+    * Pqshell can now be started in debug mode
+    * Improved shell completion with suggests and modifiers
+    * Implentation of the "mails by date" selector
+    * Reworked postsuper commands handling
+    * Better pep8 support
+    * Unit testing for python2.7 and python3
+    * Using code coverage
+
 == v0.5.3 19/10/2014 ===
     * Complete support for python2.7 and python3
     * Project renamed to PyMailq

README.rst

@@ -1,26 +1,31 @@
-pymailq - Simple Postfix queue management
-==========================================
-
-* *Author:* Denis 'jawa' Pompilio <[email protected]>
-* *Contact:* Denis 'jawa' Pompilio <[email protected]>
-* *Sources:* https://github.com/outini/pymailq/
-
-A full content documentation, is online at http://outini.github.io/pymailq/.
+|PythonPIP|_ |PythonSupport|_ |License|_ |Codacy|_ |Coverage|_
 
-The pymailq module makes it easy to view and control Postfix mails queue. It
-provide several classes to store, view and interact with mail queue using
-Postfix command line tools. This module is provided for automation and
-monitoring developments.
+pymailq - Simple Postfix queue management
+=========================================
+
+| **Contact:** Denis 'jawa' Pompilio <[email protected]>
+| **Sources:** https://github.com/outini/pymailq/
+|
+| A full content documentation, is online at http://outini.github.io/pymailq/.
+|
+| The pymailq module makes it easy to view and control Postfix mails queue. It
+| provide several classes to store, view and interact with mail queue using
+| Postfix command line tools. This module is provided for automation and
+| monitoring developments.
 
 Installation
 ------------
 
-Install pymailq module::
+Install pymailq module from https://pypi.python.org::
+
+    pip install pymailq
+
+Install pymailq module from sources::
 
     python setup.py install
 
-A SPECS file is also provided for RPM builds, thanks to Nils Ratusznik
-<[email protected]> (*https://github.com/ahpnils*).
+A SPEC file is also provided for RPM builds (currently tested only on Fedora),
+thanks to Nils Ratusznik (https://github.com/ahpnils).
 
 Requirements
 ------------
@@ -35,22 +40,19 @@ module, *readline* is highly recommended to access shell's full features. A
 full documentation on shell's usage is available at
 http://outini.github.io/pymailq/pqshell.html
 
-**Used Python modules:**
-
-  * **os** *(https://docs.python.org/2/library/os.html)*
-  * **sys** *(https://docs.python.org/2/library/sys.html)*
-  * **datetime** *(https://docs.python.org/2/library/datetime.html)*
-  * **functools** *(https://docs.python.org/2/library/functools.html)*
-  * **subprocess** *(https://docs.python.org/2/library/subprocess.html)*
-  * **gc** *(https://docs.python.org/2/library/gc.html)*
-  * **re** *(https://docs.python.org/2/library/re.html)*
-  * **cmd** *(https://docs.python.org/2/library/cmd.html)*
-  * **shlex** *(https://docs.python.org/2/library/shlex.html)*
-  * **email** *(https://docs.python.org/2/library/email.html)*
-  * **collections.Counter**
-    *(https://docs.python.org/2/library/collections.html#collections.Counter)*
-
 License
 -------
 
 "GNU GENERAL PUBLIC LICENSE" (Version 2) *(see LICENSE file)*
+
+
+.. |PythonPIP| image:: https://badge.fury.io/py/pymailq.svg
+.. _PythonPIP: https://pypi.python.org/pypi/pymailq/
+.. |PythonSupport| image:: https://img.shields.io/badge/python-2.7,%203.4-blue.svg
+.. _PythonSupport: https://github.com/outini/pymailq/
+.. |License| image:: https://img.shields.io/badge/license-GPLv2-green.svg
+.. _License: https://github.com/outini/pymailq/
+.. |Codacy| image:: https://api.codacy.com/project/badge/Grade/8444a0f124fe463d86a91d80a2a52e7c
+.. _Codacy: https://www.codacy.com/app/outini/pymailq
+.. |Coverage| image:: https://api.codacy.com/project/badge/Coverage/8444a0f124fe463d86a91d80a2a52e7c
+.. _Coverage: https://www.codacy.com/app/outini/pymailq

VERSION

@@ -1 +1 @@
-0.5.3
+0.6.0

bin/pqshell

@@ -1,4 +1,4 @@
-#! /usr/bin/env python2.7
+#! /usr/bin/env python
 
 #
 #    Postfix queue control python tool (pymailq)
@@ -20,118 +20,34 @@
 #    You should have received a copy of the GNU General Public License
 #    along with this program; if not, see <http://www.gnu.org/licenses/>.
 
-import sys
-from datetime import datetime, timedelta
-from pymailq import store, control, selector, shell
+import argparse
+import pymailq
+from pymailq import shell
 
 
-def list_preview(datas, limit = 5):
-    """Return at most "limit" elements of datas list"""
-    if len(datas) > limit:
-        overhead = len(datas) - limit
-        print(" ... Preview of first %s (%s more) ..." % (limit, overhead))
-        return datas[:limit]
-    else:
-        return datas
-
-def tests(source = None):
-    """This is here for tests purpose, no administrative operations are made.
-
-    The pymailq.QueueControl object must be tested with specific code snippet:
-    >>> import pymailq
-    >>> selector = MailSelector(PostqueueStore())
-    >>> selector.lookup_sender("MAILER-DAEMON")
-    >>> qcontrol = QueueControl()
-    >>> print("\n".join(qcontrol.hold_messages(selector.mails)))
-    >>> print("\n".join(qcontrol.release_messages(selector.mails)))
-    >>> print("\n".join(qcontrol.requeue_messages(selector.mails)))
-    """
-    import pymailq  # import pymailq to set debug on
-    pymailq.DEBUG = True
-
-    pstore = store.PostqueueStore()
-
-    #print("Loading postfix queue store (from spool)")
-    #pstore.load(method = "spool")
-    #print("Loaded %d mails" % (len(pstore.mails)))
-
-    print("Loading postfix queue store (using postqueue)")
-    pstore.load(filename = source)
-    print("Loaded %d mails" % (len(pstore.mails)))
-
-    select = selector.MailSelector(pstore)
-
-    sender = "MAILER-DAEMON"
-    print("Looking for mails from '%s'" % (sender))
-    for mail in list_preview(select.lookup_sender(sender = sender)):
-        print("%s: [%s] %s: %s (%d errors)" % (mail.date, mail.qid, mail.sender,
-                                               ", ".join(mail.recipients),
-                                               len(mail.errors)))
-
-    errormsg = "Connection timed out"
-    print("\nLooking for '%s' error message" % (errormsg))
-    for mail in list_preview(select.lookup_error(error_msg = errormsg)):
-        print("%s: %s (%d errors)" % (mail.date, mail.sender,
-                                      len(mail.errors)))
-
-    stop_date = datetime.now() - timedelta(days=5)
-    print("\nLooking for mails older than %s" % (stop_date))
-    for mail in list_preview(select.lookup_date(stop = stop_date)):
-        print("%s: *%s* %s (%d errors)" % (mail.date, mail.status,
-                                           mail.sender, len(mail.errors)))
-
-    print("\nProceeding to selector reset (%s mails)" % (len(select.mails)))
-    select.reset()
-    print("Selector resetted (%s mails)" % (len(select.mails)))
-
-    status = "active"
-    print("\nLooking for mails with postqueue status: %s" % (status))
-    for mail in list_preview(select.lookup_status(status = status)):
-        print("%s: %s (%d recipients)" % (mail.date, mail.sender,
-                                          len(mail.recipients)))
-
-    print("\nReplaying filters")
-    select.replay_filters()
-    print("Found %s mails" % (len(select.mails)))
-
-    print("\nLooking for fat mails (>100000B)")
-    for mail in list_preview(select.lookup_size(smin = 100000)):
-        print("%s: [%s] %s (%dB)" % (mail.date, mail.qid,
-                                     mail.sender, mail.size))
-
-    print("\nLooking for multiple recipients mails")
-    mrcpt = [ mail for mail in pstore.mails if len(mail.recipients) > 1 ]
-    for mail in list_preview(mrcpt):
-        print("%s: [%s] %s (%dB): %d recipients" % (mail.date, mail.qid,
-                                                    mail.sender, mail.size,
-                                                    len(mail.recipients)))
-
-    target = pstore.mails[-1]
-    print("\nDumping last mail from queue (%s)" % (target.qid))
-    target.parse()
-    datas = target.dump()
-    print("Postqueue infos:")
-    for k,v in datas['postqueue'].items():
-        print("    %s: %s" % (k,v))
-    print("Headers infos:")
-    for k,v in datas['headers'].items():
-        print("    %s: %s" % (k,v))
-
-    sys.exit(0)
-
 def main():
     """main function"""
     cli = shell.PyMailqShell()
     cli.cmdloop_nointerrupt()
 
 
 if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description='Postfix queue control shell')
+    parser.add_argument('--version', dest='version', action='store_const',
+                        const=True, default=False,
+                        help='show shell version')
+    parser.add_argument('--debug', dest='debug', action='store_const',
+                        const=True, default=False,
+                        help='show shell debug and timing info')
+
+    args = parser.parse_args()
+
+    if args.version:
+        print("Shell version: %s" % pymailq.VERSION)
+        exit()
+
+    if args.debug:
+        print("Setting shell in debug mode.")
+        pymailq.DEBUG = True
 
-    # Looking for "tests", shell is the default action
-    if len(sys.argv) >= 2 and sys.argv[1] == "tests":
-        source = None
-        if len(sys.argv) >= 3:
-            source = sys.argv[2]  # load mails queue from file
-        tests(source)
-    else:
-        main()
+    main()

docs/docs.requirements.txt

@@ -0,0 +1 @@
+Sphinx

docs/index.rst

@@ -14,6 +14,7 @@ monitoring.
 The :mod:`pymailq` package defines the following attribute:
 
     .. autodata:: DEBUG
+    .. autodata:: VERSION
 
 The :mod:`pymailq` package defines the following decorators:
 

docs/pqshell.rst

@@ -68,7 +68,14 @@ select
         **date**
             Select mails by date.
 
-            Usage: ``select date X [Y]``
+            Usage: ``select date <DATESPEC>``
+
+            Where `<DATESPEC>` can be::
+
+                YYYY-MM-DD (exact date)
+                YYYY-MM-DD..YYYY-MM-DD (within a date range (included))
+                +YYYY-MM-DD (after a date (included))
+                -YYYY-MM-DD (before a date (included))
 
         **error**
             Select mails by error message. Specified error message can be