Make it even easier to integrate with cron

Author: xolox

README.rst

@@ -25,6 +25,7 @@ defined by my verboselogs_ package: if you install both `coloredlogs` and
 
 .. contents::
    :local:
+   :depth: 1
 
 Format of log messages
 ----------------------
@@ -80,24 +81,49 @@ Colored output from cron
 When `coloredlogs` is used in a cron_ job, the output that's e-mailed to you by
 cron won't contain any ANSI escape sequences because `coloredlogs` realizes
 that it's not attached to an interactive terminal. If you'd like to have colors
-e-mailed to you by cron there's a simple way to set it up::
+e-mailed to you by cron there are two ways to make it happen:
+
+.. contents::
+   :local:
+
+You can use this feature without using `coloredlogs` in your Python modules,
+but please note that only normal text, bold text and text with one of the
+foreground colors black, red, green, yellow, blue, magenta, cyan and white
+(these are the portable ANSI color codes) are supported.
+
+Modifying your crontab
+~~~~~~~~~~~~~~~~~~~~~~
+
+Here's an example of a minimal crontab::
 
     MAILTO="your-email-address@here"
     CONTENT_TYPE="text/html"
     * * * * * root coloredlogs --to-html your-command
 
 The ``coloredlogs`` program is installed when you install the `coloredlogs`
-package. When you execute ``coloredlogs --to-html your-command`` it runs
+Python package. When you execute ``coloredlogs --to-html your-command`` it runs
 ``your-command`` under the external program ``script`` (you need to have this
 installed). This makes ``your-command`` think that it's attached to an
 interactive terminal which means it will output ANSI escape sequences which
 will then be converted to HTML by the ``coloredlogs`` program. Yes, this is a
 bit convoluted, but it works great :-)
 
-You can use this feature without using `coloredlogs` in your Python modules,
-but please note that only normal text, bold text and text with one of the
-foreground colors black, red, green, yellow, blue, magenta, cyan and white
-(these are the portable ANSI color codes) are supported.
+Modifying your Python code
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ColoredCronMailer_ class provides a context manager that automatically
+enables HTML output when the ``$CONTENT_TYPE`` variable has been correctly set
+in the crontab.
+
+This requires my capturer_ package which you can install using ``pip install
+'coloredlogs[cron]'``. The ``[cron]`` extra will pull in capturer_ 2.4 or newer
+which is required to capture the output while silencing it - otherwise you'd
+get duplicate output in the emails sent by ``cron``.
+
+The context manager can also be used to retroactively silence output that has
+already been produced, this can be useful to avoid spammy cron jobs that have
+nothing useful to do but still email their output to the system administrator
+every few minutes :-).
 
 Contact
 -------
@@ -116,14 +142,16 @@ This software is licensed under the `MIT license`_.
 
 
 .. External references:
-.. _ANSI escape sequences: http://en.wikipedia.org/wiki/ANSI_escape_code#Colors
+.. _ANSI escape sequences: https://en.wikipedia.org/wiki/ANSI_escape_code#Colors
+.. _capturer: https://pypi.python.org/pypi/capturer
 .. _Colorama: https://pypi.python.org/pypi/colorama
-.. _ColoredFormatter: http://coloredlogs.readthedocs.io/en/latest/#coloredlogs.ColoredFormatter
+.. _ColoredCronMailer: https://coloredlogs.readthedocs.io/en/latest/#coloredlogs.converter.ColoredCronMailer
+.. _ColoredFormatter: https://coloredlogs.readthedocs.io/en/latest/#coloredlogs.ColoredFormatter
 .. _cron: https://en.wikipedia.org/wiki/Cron
 .. _GitHub: https://github.com/xolox/python-coloredlogs
-.. _logging.Formatter: http://docs.python.org/2/library/logging.html#logging.Formatter
+.. _logging.Formatter: https://docs.python.org/2/library/logging.html#logging.Formatter
 .. _logging: https://docs.python.org/2/library/logging.html
-.. _MIT license: http://en.wikipedia.org/wiki/MIT_License
+.. _MIT license: https://en.wikipedia.org/wiki/MIT_License
 .. _online documentation: https://coloredlogs.readthedocs.io/
 .. _[email protected]: [email protected]
 .. _PyPI: https://pypi.python.org/pypi/coloredlogs

coloredlogs/__init__.py

@@ -1,7 +1,7 @@
 # Colored terminal output for Python's logging module.
 #
 # Author: Peter Odding <[email protected]>
-# Last Change: May 17, 2017
+# Last Change: May 18, 2017
 # URL: https://coloredlogs.readthedocs.io
 
 """
@@ -25,7 +25,7 @@
 The :mod:`~coloredlogs.install()` function creates a :class:`ColoredFormatter`
 that injects `ANSI escape sequences`_ into the log output.
 
-.. _ANSI escape sequences: http://en.wikipedia.org/wiki/ANSI_escape_code#Colors
+.. _ANSI escape sequences: https://en.wikipedia.org/wiki/ANSI_escape_code#Colors
 
 Environment variables
 =====================

coloredlogs/converter.py

@@ -1,7 +1,7 @@
 # Program to convert text with ANSI escape sequences to HTML.
 #
 # Author: Peter Odding <[email protected]>
-# Last Change: May 17, 2017
+# Last Change: May 18, 2017
 # URL: https://coloredlogs.readthedocs.io
 
 """Convert text with ANSI escape sequences to HTML."""
@@ -15,7 +15,7 @@
 import tempfile
 
 # External dependencies.
-from humanfriendly.terminal import ANSI_CSI, clean_terminal_output
+from humanfriendly.terminal import ANSI_CSI, clean_terminal_output, output
 
 # Portable color codes from http://en.wikipedia.org/wiki/ANSI_escape_code#Colors.
 EIGHT_COLOR_PALETTE = (
@@ -198,3 +198,61 @@ def html_encode(text):
     text = text.replace('>', '&gt;')
     text = text.replace('"', '&quot;')
     return text
+
+
+class ColoredCronMailer(object):
+
+    """
+    Easy to use integration between :mod:`coloredlogs` and the UNIX ``cron`` daemon.
+
+    By using :class:`ColoredCronMailer` as a context manager in the command
+    line interface of your Python program you make it trivially easy for users
+    of your program to opt in to HTML output under ``cron``: The only thing the
+    user needs to do is set ``CONTENT_TYPE="text/html"`` in their crontab!
+
+    Under the hood this requires quite a bit of magic and I must admit that I
+    developed this code simply because I was curious whether it could even be
+    done :-). It requires my :mod:`capturer` package which you can install
+    using ``pip install 'coloredlogs[cron]'``. The ``[cron]`` extra will pull
+    in the :mod:`capturer` 2.4 or newer which is required to capture the output
+    while silencing it - otherwise you'd get duplicate output in the emails
+    sent by ``cron``.
+    """
+
+    def __init__(self):
+        """Initialize output capturing when running under ``cron`` with the correct configuration."""
+        self.is_enabled = 'text/html' in os.environ.get('CONTENT_TYPE', 'text/plain')
+        self.is_silent = False
+        if self.is_enabled:
+            # We import capturer here so that the coloredlogs[cron] extra
+            # isn't required to use the other functions in this module.
+            from capturer import CaptureOutput
+            self.capturer = CaptureOutput(merged=True, relay=False)
+
+    def __enter__(self):
+        """Start capturing output (when applicable)."""
+        if self.is_enabled:
+            self.capturer.__enter__()
+        return self
+
+    def __exit__(self, exc_type=None, exc_value=None, traceback=None):
+        """Stop capturing output and convert the output to HTML (when applicable)."""
+        if self.is_enabled:
+            if not self.is_silent:
+                # Only call output() when we captured something useful.
+                text = self.capturer.get_text()
+                if text and not text.isspace():
+                    output(convert(text))
+            self.capturer.__exit__(exc_type, exc_value, traceback)
+
+    def silence(self):
+        """
+        Tell :func:`__exit__()` to swallow all output (things will be silent).
+
+        This can be useful when a Python program is written in such a way that
+        it has already produced output by the time it becomes apparent that
+        nothing useful can be done (say in a cron job that runs every few
+        minutes :-p). By calling :func:`silence()` the output can be swallowed
+        retroactively, avoiding useless emails from ``cron``.
+        """
+        self.is_silent = True

docs/conf.py

@@ -1,7 +1,7 @@
 # Colored terminal output for Python's logging module.
 #
 # Author: Peter Odding <[email protected]>
-# Last Change: March 10, 2017
+# Last Change: May 18, 2017
 # URL: https://coloredlogs.readthedocs.io
 
 """Sphinx documentation configuration for the `coloredlogs` package."""
@@ -69,14 +69,15 @@
 # From: http://twistedmatrix.com/trac/ticket/4582.
 intersphinx_mapping = dict(
     python=('https://docs.python.org/2', None),
+    capturer=('https://capturer.readthedocs.io/en/latest', None),
     humanfriendly=('https://humanfriendly.readthedocs.io/en/latest', None),
 )
 
 # -- Options for HTML output ---------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'classic'
+html_theme = 'nature'
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'coloredlogsdoc'

setup.py

@@ -1,9 +1,9 @@
 #!/usr/bin/env python
 
 # Setup script for the `coloredlogs' package.
-
+#
 # Author: Peter Odding <[email protected]>
-# Last Change: April 17, 2017
+# Last Change: May 18, 2017
 # URL: https://coloredlogs.readthedocs.io
 
 """
@@ -54,7 +54,7 @@ def get_install_requires():
 
 def get_extras_require():
     """Add conditional dependencies for Windows (when creating wheel distributions)."""
-    extras_require = {}
+    extras_require = dict(cron='capturer>=2.4')
     if have_environment_marker_support():
         expression = ':sys_platform == "win32"'
         extras_require[expression] = 'colorama'