Merge pull request #24 from outini/master

PyMailq released to v0.9.0

CHANGES

@@ -4,6 +4,14 @@ pymailq - Simple mail queue management
 Contact: Denis Pompilio (jawa) <[email protected]>
 https://github.com/outini/pymailq
 
+=== v0.9.0 07/09/2017 ===
+    * [bug] Fixing wrong usage for command inspect
+    * Auto-decoding encoded mail subjects
+    * Better encoding support for python2.7 and python3+
+    * Mail.show() method now display every mail headers
+    * Implementation of store auto loading
+    * Added Debian binary packages
+
 === v0.8.0 28/08/2017 ===
     * [bug] Fixing handling of modifiers completion
     * [bug] Fixing parse_error message retention

README.rst

@@ -1,17 +1,21 @@
-|PythonPIP|_ |PythonSupport|_ |License|_ |Codacy|_ |Coverage|_ |Travis|_
+|PythonPIP|_ |PythonSupport|_ |License|_ |Codacy|_ |Coverage|_ |RTFD|_ |Travis|_
 
 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/.
+| A full content documentation, is online at https://pymailq.readthedocs.io/en/latest/
 |
 | 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.
+|
+| This project also provides a shell-like to interact with Postfix mails queue.
+| It provide simple means to view the queue content, filter mails on criterias
+| like Sender or delivery errors and lead administrative operations.
 
 Installation
 ------------
@@ -25,28 +29,141 @@ Install pymailq module from sources::
     python setup.py install
 
 A SPEC file is also provided for RPM builds (currently tested only on Fedora),
-thanks to Nils Ratusznik (https://github.com/ahpnils).
+thanks to Nils Ratusznik (https://github.com/ahpnils). Debian binary packages
+are also available.
 
 Requirements
 ------------
 
 This module actually support the following Python versions:
 
-  * *Python 2.7*
-  * *Python 3*
+*  *Python 2.7*
+*  *Python 3+*
 
 A shell is provided for interactive administration. Based on Python *cmd*
-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
+module, using Python compiled with *readline* support is highly recommended
+to access shell's full features.
+
+Using the shell
+---------------
+
+Mails queue summary::
+
+    ~$ pqshell --summary
+
+    ====================== Mail queue summary ========================
+    Total mails in queue: 1773
+    Total queue size: 40.2 MB
+
+    Mails by accepted date:
+        last 24h:          939
+        1 to 4 days ago:   326
+        older than 4 days: 173
+
+    ----- Mails by status ----------    ----- Mails by size ----------
+    Active      2                       Average size      23.239 KB
+    Hold        896                     Maximum size    1305.029 KB
+    Deferred    875                     Minimum size       0.517 KB
+
+    ----- Unique senders -----------    ----- Unique recipients ------
+    Senders     156                     Recipients          1003
+    Domains     141                     Domains              240
+
+    ----- Top senders ------------------------------------------------
+    228    [email protected]
+    195    [email protected]
+    116    MAILER-DAEMON
+    105    [email protected]
+    61     [email protected]
+
+    ----- Top sender domains -----------------------------------------
+    228    domain-1.tld
+    195    domain-4.tld
+    105    domain-2.tld
+    75     domain-0.tld
+    61     domain-3.tld
+
+    ----- Top recipients ---------------------------------------------
+    29     [email protected]
+    28     [email protected]
+    23     [email protected]
+    20     [email protected]
+    20     [email protected]
+
+    ----- Top recipient domains --------------------------------------
+    697    domain-7.tld
+    455    domain-5.tld
+    37     domain-6.tld
+    37     domain-9.tld
+    34     domain-8.tld
+
+Using the shell in interactive mode::
+
+    ~$ pqshell
+    Welcome to PyMailq shell.
+    PyMailq (sel:0)> store load
+    500 mails loaded from queue
+    PyMailq (sel:500)> show selected limit 5
+    2017-09-02 17:54:34 B04C91183774 [deferred] [email protected] (425B)
+    2017-09-02 17:54:34 B21D71183681 [deferred] [email protected] (435B)
+    2017-09-02 17:54:34 B422D11836AB [deferred] [email protected] (2416B)
+    2017-09-02 17:54:34 B21631183753 [deferred] [email protected] (425B)
+    2017-09-02 17:54:34 F2A7E1183789 [deferred] [email protected] (2416B)
+    ...Preview of first 5 (495 more)...
+    PyMailq (sel:500)> show selected limit 5 long
+    2017-09-02 17:54:34 B04C91183774 [deferred] [email protected] (425B)
+      Rcpt: [email protected]
+       Err: Test error message
+    2017-09-02 17:54:34 B21D71183681 [deferred] [email protected] (435B)
+      Rcpt: [email protected]
+       Err: Test error message
+    2017-09-02 17:54:34 B422D11836AB [deferred] [email protected] (2416B)
+      Rcpt: [email protected]
+       Err: mail transport unavailable
+    2017-09-02 17:54:34 B21631183753 [deferred] [email protected] (425B)
+      Rcpt: [email protected]
+       Err: mail transport unavailable
+    2017-09-02 17:54:34 F2A7E1183789 [deferred] [email protected] (2416B)
+      Rcpt: [email protected]
+       Err: mail transport unavailable
+    ...Preview of first 5 (495 more)...
+    PyMailq (sel:500)> select error "Test error message"
+    PyMailq (sel:16)> show selected rankby sender
+    sender                                    count
+    ================================================
+    [email protected]                  7
+    [email protected]                  3
+    [email protected]                  2
+    [email protected]                  1
+    [email protected]                  1
+    [email protected]                  1
+    [email protected]                  1
+    PyMailq (sel:16)> select sender [email protected]
+    PyMailq (sel:7)> super hold
+    postsuper: Placed on hold: 7 messages
+    PyMailq (sel:7)> select reset
+    Selector resetted with store content (500 mails)
+    PyMailq (sel:500)> show selected rankby status
+    status                                    count
+    ================================================
+    deferred                                  493
+    hold                                      7
+    PyMailq (sel:500)> exit
+    Exiting shell... Bye.
+
+Packaging
+---------
+
+Binary packages for some linux distribution are available. See the *packaging*
+directory for more information.
 
 License
 -------
 
 "GNU GENERAL PUBLIC LICENSE" (Version 2) *(see LICENSE file)*
 
 
-.. |PythonPIP| image:: https://badge.fury.io/py/pymailq.svg
+.. |PythonPIP| image:: https://img.shields.io/pypi/v/pymailq.svg
 .. _PythonPIP: https://pypi.python.org/pypi/pymailq/
 .. |PythonSupport| image:: https://img.shields.io/badge/python-2.7,%203.4,%203.5,%203.6-blue.svg
 .. _PythonSupport: https://github.com/outini/pymailq/
@@ -56,6 +173,8 @@ License
 .. _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
+.. |RTFD| image:: https://readthedocs.org/projects/pymailq/badge/?version=latest
+.. _RTFD: http://pymailq.readthedocs.io/en/latest/?badge=latest
 .. |Travis| image:: https://travis-ci.org/outini/pymailq.svg?branch=master
 .. _Travis: https://travis-ci.org/outini/pymailq
 

VERSION

@@ -1 +1 @@
-0.8.0
+0.9.0

bin/pqshell

@@ -1,5 +1,6 @@
 #! /usr/bin/env python
 
+# coding: utf-8
 #
 #    Postfix queue control python tool (pymailq)
 #
@@ -28,7 +29,12 @@ from pymailq import shell, store
 SUMMARY = """
 ====================== Mail queue summary ========================
 Total mails in queue: {total_mails}
-Total queue size in MB: {total_mails_size:.3}
+Total queue size: {total_mails_size:.3} MB
+
+Mails by accepted date:
+    last 24h:           {mails_by_age[last_24h]}
+    1 to 4 days ago:    {mails_by_age[1_to_4_days_ago]}
+    older than 4 days:  {mails_by_age[older_than_4_days]}
 
 ----- Mails by status ----------    ----- Mails by size ----------
 Active      {active_mails:<18}      Average size  {average_mail_size:10.3f} KB
@@ -53,9 +59,9 @@ Domains     {u_s_domains:<17}       Domains       {u_r_domains:>10}
 """
 
 
-def main():
+def main(store_auto_load=True):
     """main function"""
-    cli = shell.PyMailqShell()
+    cli = shell.PyMailqShell(store_auto_load=store_auto_load)
     cli.cmdloop_nointerrupt()
 
 
@@ -72,6 +78,9 @@ if __name__ == "__main__":
     parser.add_argument('--summary', dest='summary', action='store_const',
                         const=True, default=False,
                         help='summarize the mails queue content')
+    parser.add_argument('--no-auto-load', dest='noautoload',
+                        action='store_const', const=True, default=False,
+                        help='deactivate store auto load at shell startup')
 
     args = parser.parse_args()
 
@@ -109,4 +118,6 @@ if __name__ == "__main__":
         print(SUMMARY.format(**data))
         exit()
 
-    main()
+    auto_load = False if args.noautoload else True
+
+    main(store_auto_load=auto_load)

docs/conf.py

@@ -11,7 +11,10 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys, os
+import sys
+import os
+
+
 sys.path.insert(0, os.path.abspath("../pymailq"))
 sys.path.insert(0, os.path.abspath(".."))
 
@@ -94,7 +97,11 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'haiku'
+on_rtd = os.environ.get('READTHEDOCS') == 'True'
+if on_rtd:
+    html_theme = 'default'
+else:
+    html_theme = 'haiku'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

docs/pqshell.rst

@@ -13,7 +13,7 @@ SYNOPSIS
 
 ::
 
-    pqshell [-h] [--version] [--debug] [--config CFG_FILE] [--summary]
+    pqshell [OPTION]...
 
 FEATURES
 ********
@@ -31,6 +31,7 @@ OPTIONS
     --debug              activate shell debug and timing info
     --config CFG_FILE    specify a configuration file for PyMailq
     --summary            show mails queue summary and exit
+    --no-auto-load       deactivate store auto load at shell startup
 
 SHELL COMMANDS
 **************
@@ -110,6 +111,11 @@ select
             Select mails from sender.
 
             Usage: ``select sender <sender> [exact]``
+
+        **recipient**
+            Select mails to recipient.
+
+            Usage: ``select recipient <recipient> [exact]``
 
         **size**
             Select mails by size in Bytes. Signs - and + are supported, if not

docs/selector.rst

@@ -12,12 +12,13 @@ structures from the :mod:`store` module.
     The :class:`~selector.MailSelector` instance provides the following methods:
 
         .. automethod:: selector.MailSelector.filter_registration
-        .. automethod:: selector.MailSelector.reset()
-        .. automethod:: selector.MailSelector.replay_filters()
-        .. automethod:: selector.MailSelector.get_mails_by_qids(qids)
-        .. automethod:: selector.MailSelector.lookup_qids(qids)
-        .. automethod:: selector.MailSelector.lookup_status(status)
-        .. automethod:: selector.MailSelector.lookup_sender(sender[, partial])
-        .. automethod:: selector.MailSelector.lookup_error(error_msg)
-        .. automethod:: selector.MailSelector.lookup_date([start[, stop]])
-        .. automethod:: selector.MailSelector.lookup_size([smin[, smax]])
+        .. automethod:: selector.MailSelector.reset
+        .. automethod:: selector.MailSelector.replay_filters
+        .. automethod:: selector.MailSelector.get_mails_by_qids
+        .. automethod:: selector.MailSelector.lookup_qids
+        .. automethod:: selector.MailSelector.lookup_status
+        .. automethod:: selector.MailSelector.lookup_sender
+        .. automethod:: selector.MailSelector.lookup_recipient
+        .. automethod:: selector.MailSelector.lookup_error
+        .. automethod:: selector.MailSelector.lookup_date
+        .. automethod:: selector.MailSelector.lookup_size

helpers/make_deb_package.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+
+PACKAGING_DIR="packaging"
+
+requirements="
+debhelper
+devscripts
+build-essential
+python-support
+python-all
+python3-all
+"
+
+change_file="pymailq_*.changes"
+packages="python-pymailq python3-pymailq"
+
+# Checking requirements
+dpkg_output=$(dpkg -l $requirements)
+grep -q '^un' <<< "$dpkg_output" && {
+    read -p "Missing packages, May I install those? (yes|no) " answer
+    [ "$answer" == "yes" ] || {
+        echo "Build of debian package aborted."
+        exit 1
+    }
+    sudo apt-get install -qq $requirements
+}
+
+[ -d "$PACKAGING_DIR" ] || { echo "Packaging directory not found."; exit 2; }
+cd "$PACKAGING_DIR"
+
+# Preparing build directory
+[ -d build ] && { echo "Cleaning build directory."; rm -r build; }
+echo "Preparing build directory."
+mkdir build && cp -a debian build/ &&
+[ -d build ] || { echo "Fail to prepare build directory."; exit 2; }
+
+# Building binary package
+(cd build && dpkg-buildpackage -us -uc -b) || {
+    echo "Failed to build package."
+    exit 2
+}
+
+# Verify your build
+echo "Running lintian and inspecting package content."
+lintian -IviE --display-experimental --pedantic -L ">=wishlist" \
+        --color auto --show-overrides --checksums $change_file
+
+echo "Showing packages infos and content."
+for pkg in $packages; do
+    dpkg-deb -I ${pkg}_*.deb
+    dpkg-deb -c ${pkg}_*.deb
+done

helpers/make_manpages.sh

@@ -0,0 +1,7 @@
+#! /bin/bash
+
+DOCS_DIR="docs"
+MAN_DIR="man"
+
+(cd "$DOCS_DIR" && make man)
+cp "$DOCS_DIR/_build/man/"* "$MAN_DIR/"