fix the debug functions so that the messages end up once in stdout an…

…d the logfile.

Add exit option to done().
Document the idea of overriding characteristics of predefined informants by setting their attributes.
Improve the description of logfile argument.

README.rst

@@ -344,16 +344,15 @@ ppp:
         >>> c = (2, 3)
         >>> d = {'a': a, 'b': b, 'c': c}
         >>> ppp(a, b, c)
-        DEBUG: <doctest README.rst[52]>:1, __main__:
-            1 this is a test (2, 3)
+        DEBUG: <doctest README.rst[52]>, 1, __main__: 1 this is a test (2, 3)
 
 ddd:
     This function is pretty prints all of both the unnamed and named arguments.
 
     .. code:: python
 
         >>> ddd(a, b, c=c, d=d)
-        DEBUG: <doctest README.rst[53]>:1, __main__:
+        DEBUG: <doctest README.rst[53]>, 1, __main__:
             1
             'this is a test'
             c = (2, 3)
@@ -374,7 +373,7 @@ vvv:
     .. code:: python
 
         >>> vvv(b, d)
-        DEBUG: <doctest README.rst[54]>:1, __main__:
+        DEBUG: <doctest README.rst[54]>, 1, __main__:
             b = 'this is a test'
             d = {
                 'a': 1,

doc/releases.rst

@@ -20,3 +20,5 @@ Releases
     | Version: 1.12.4
     | Released: 2018-04-29
 
+    - Added aaa() debug function
+    - Added exit argument to done()

doc/user.rst

@@ -184,6 +184,18 @@ informants using :class:`inform.InformantFactory`.
 All of the informants except :ref:`panic` and :ref:`debug` do not produce any 
 output if *mute* is set.
 
+If you do not care for the default behavior for the predefined informants, you 
+can customize them by overriding their attributes. For example, in many cases 
+you might prefer that normal program output is not logged, either because it is 
+voluminous or because it is sensitive. In that case you can simple override the 
+*log* attributes for the *display* and *output* informants like so:
+
+.. code-block:: python
+
+   from inform import display, output
+   display.log = False
+   output.log = False
+
 
 .. _log:
 
@@ -1187,15 +1199,11 @@ method has the side effect of updating the state of the integrator.
     >>> for t in range(1, 3):
     ...    vout = 0.7*aaa(int2=int2.update(aaa(int1=int1.update(vin-vout))))
     ...    display('vout = {}'.format(vout))
-    DEBUG: <doctest user.rst[130]>:2, __main__:
-        int1: 2
-    DEBUG: <doctest user.rst[130]>:2, __main__:
-        int2: 2
+    myprog DEBUG: <doctest user.rst[130]>, 2, __main__: int1: 2
+    myprog DEBUG: <doctest user.rst[130]>, 2, __main__: int2: 2
     vout = 1.4
-    DEBUG: <doctest user.rst[130]>:2, __main__:
-        int1: 1.6
-    DEBUG: <doctest user.rst[130]>:2, __main__:
-        int2: 3.6
+    myprog DEBUG: <doctest user.rst[130]>, 2, __main__: int1: 1.6
+    myprog DEBUG: <doctest user.rst[130]>, 2, __main__: int2: 3.6
     vout = 2.52
 
 
@@ -1216,7 +1224,7 @@ ddd
     >>> c = (2, 3)
     >>> d = {'a': a, 'b': b, 'c': c}
     >>> ddd(a, b, c, d)
-    DEBUG: <doctest user.rst[136]>:1, __main__:
+    myprog DEBUG: <doctest user.rst[136]>, 1, __main__:
         1
         'this is a test'
         (2, 3)
@@ -1232,7 +1240,7 @@ If you give named arguments, the name is prepended to its value:
 
     >>> from inform import ddd
     >>> ddd(a=a, b=b, c=c, d=d, s='hey now!')
-    DEBUG: <doctest user.rst[138]>:1, __main__:
+    myprog DEBUG: <doctest user.rst[138]>, 1, __main__:
         a = 1
         b = 'this is a test'
         c = (2, 3)
@@ -1256,7 +1264,7 @@ argument itself.
     ...         ddd(self=self)
 
     >>> contact = Info(email='ted@ledbelly.com', name='Ted Ledbelly')
-    DEBUG: <doctest user.rst[140]>:4, __main__.Info.__init__():
+    myprog DEBUG: <doctest user.rst[140]>, 4, __main__.Info.__init__():
         self = Info object containing {
             'email': 'ted@ledbelly.com',
             'name': 'Ted Ledbelly',
@@ -1286,8 +1294,7 @@ good way of confirming that a line of code has been reached.
     >>> c = (2, 3)
     >>> d = {'a': a, 'b': b, 'c': c}
     >>> ppp(a, b, c)
-    DEBUG: <doctest user.rst[147]>:1, __main__:
-        1 this is a test (2, 3)
+    myprog DEBUG: <doctest user.rst[147]>, 1, __main__: 1 this is a test (2, 3)
 
 
 .. _sss desc:
@@ -1331,7 +1338,7 @@ variables on the argument list and only those variables are printed.
     >>> from inform import vvv
 
     >>> vvv(b, d)
-    DEBUG: <doctest user.rst[149]>:1, __main__:
+    myprog DEBUG: <doctest user.rst[149]>, 1, __main__:
         b = 'this is a test'
         d = {
             'a': 1,
@@ -1349,7 +1356,7 @@ shown.
 
     >>> aa = 1
     >>> vvv(a)
-    DEBUG: <doctest user.rst[152]>:1, __main__:
+    myprog DEBUG: <doctest user.rst[152]>, 1, __main__:
         a = 1
         aa = 1
         vin = 1

inform/inform.py

@@ -731,7 +731,7 @@ def _debug(frame_depth, args, kwargs):
         body = _join(args, kwargs)
         header += ':\n' if body else '.'
         message = highlight_header(header) + highlight_body(indent(body))
-        print(message, **kwargs)
+        debug(body, culprit=(fname, lineno, name))
 
     finally:
         # Failing to explicitly delete the frame can lead to long-lived
@@ -1031,6 +1031,7 @@ def _notify_user(self, informer):
     output=True,
     log=True,
     header_color='magenta',
+    message_color='blue',
 )
 warn = InformantFactory(
     severity='warning',
@@ -1106,11 +1107,11 @@ class Inform:
             the user as to what is going on. This can help place errors and
             warnings in context so that they are easier to understand.
 
-        logfile (string or stream or bool):
-            May be a string, in which case it is taken to be the path of the
-            logfile.  May be *True*, in which case ./.<prog_name>.log is used.
-            May be an open stream.  Or it may be *False*, in which case no log
-            file is created.
+        logfile (path, string, stream, bool):
+            May be a pathlib path or a string, in which case it is taken to be
+            the path of the logfile.  May be *True*, in which case
+            ./.<prog_name>.log is used.  May be an open stream.  Or it may be
+            *False*, in which case no log file is created.
 
         prog_name (string):
             The program name. Is appended to the message headers and used to
@@ -1296,10 +1297,10 @@ def set_logfile(self, logfile, encoding='utf-8'):
 
         Args:
             logfile:
-                May be a string, in which case it is taken to be the path of the
-                logfile.  May be *True*, in which case ./.<prog_name>.log is
-                used.  May be an open stream.  Or it may be *False*, in which
-                case no log file is created.
+                May be a pathlib path. May be a string, in which case it is
+                taken to be the path of the logfile.  May be *True*, in which
+                case ./.<prog_name>.log is used.  May be an open stream.  Or it
+                may be *False*, in which case no log file is created.
             encoding (string):
                 The encoding to use when writing the file.
         """
@@ -1476,8 +1477,14 @@ def _show_msg(self, header, culprit, message, multiline, options):
             print(': '.join(cull([header, culprit, message])), **options)
 
     # done {{{2
-    def done(self):
-        "Terminate the program with normal exit status."
+    def done(self, exit=True):
+        """Terminate the program with normal exit status.
+
+        Args:
+            exit (bool):
+                If False, all preparations for termination are done, but
+                sys.exit() is not called.
+        """
         if self.termination_callback:
             self.termination_callback()
         if self.prog_name:
@@ -1487,7 +1494,10 @@ def done(self):
         if self.logfile:
             self.logfile.close()
             self.logfile = None
-        sys.exit()
+        if exit:
+            sys.exit()
+        else:
+            return
 
     # terminate {{{2
     def terminate(self, status=None):

tests/test_inform.py

@@ -156,52 +156,53 @@ def test_cartwheel():
         ''').strip().format(expected=expected)
 
 def test_pardon():
-    try:
-        raise Error('hey now!', culprit='nutz', extra='foo')
-        assert False
-    except Error as err:
-        assert err.get_message() == 'hey now!'
-        assert err.get_culprit() == 'nutz'
-        assert err.extra == 'foo'
-        assert str(err) == 'nutz: hey now!'
-        assert errors_accrued() == 0  # errors don't accrue until reported
-
-    try:
-        raise Error('hey now!', culprit=('nutz',  'crunch'), extra='foo')
-        assert False
-    except Error as err:
-        assert err.get_message() == 'hey now!'
-        assert err.get_culprit() == 'nutz, crunch'
-        assert err.extra == 'foo'
-        assert str(err) == 'nutz, crunch: hey now!'
-        assert err.get_message() == 'hey now!'
-        assert err.get_message('{extra}, {}') == 'foo, hey now!'
-        assert err.render() == 'nutz, crunch: hey now!'
-        assert err.render('{extra}, {}') == 'nutz, crunch: foo, hey now!'
-        assert errors_accrued() == 0  # errors don't accrue until reported
-        try:
-            err.terminate()
-            assert False
-        except SystemExit:
-            assert True
-
-        try:
-            done()
-            assert False
-        except SystemExit:
-            assert True
-
+    with messenger() as (msg, stdout, stderr, logfile):
         try:
-            terminate()
+            raise Error('hey now!', culprit='nutz', extra='foo')
             assert False
-        except SystemExit:
-            assert True
+        except Error as err:
+            assert err.get_message() == 'hey now!'
+            assert err.get_culprit() == 'nutz'
+            assert err.extra == 'foo'
+            assert str(err) == 'nutz: hey now!'
+            assert errors_accrued() == 0  # errors don't accrue until reported
 
         try:
-            terminate_if_errors()
+            raise Error('hey now!', culprit=('nutz',  'crunch'), extra='foo')
             assert False
-        except SystemExit:
-            assert True
+        except Error as err:
+            assert err.get_message() == 'hey now!'
+            assert err.get_culprit() == 'nutz, crunch'
+            assert err.extra == 'foo'
+            assert str(err) == 'nutz, crunch: hey now!'
+            assert err.get_message() == 'hey now!'
+            assert err.get_message('{extra}, {}') == 'foo, hey now!'
+            assert err.render() == 'nutz, crunch: hey now!'
+            assert err.render('{extra}, {}') == 'nutz, crunch: foo, hey now!'
+            assert errors_accrued() == 0  # errors don't accrue until reported
+            try:
+                err.terminate()
+                assert False
+            except SystemExit:
+                assert True
+
+            try:
+                done()
+                assert False
+            except SystemExit:
+                assert True
+
+            try:
+                terminate()
+                assert False
+            except SystemExit:
+                assert True
+
+            try:
+                terminate_if_errors()
+                assert False
+            except SystemExit:
+                assert True
 
 def test_possess():
     with messenger(stream_policy='header') as (msg, stdout, stderr, logfile):

tests/test_utilities.py

@@ -21,13 +21,14 @@ def X(arg):
         return arg
 
 def test_debug(capsys):
+    Inform(colorscheme=None, prog_name=False)
     a='a'
     b='b'
     c='c'
     ddd(a, b, c)
     captured = capsys.readouterr()
     assert captured[0] == dedent("""
-        DEBUG: test_utilities.py:27, test_utilities.test_debug():
+        DEBUG: test_utilities.py, 28, test_utilities.test_debug():
             'a'
             'b'
             'c'
@@ -36,7 +37,7 @@ def test_debug(capsys):
     ddd(a=a, b=b, c=c)
     captured = capsys.readouterr()
     assert captured[0] == dedent("""
-        DEBUG: test_utilities.py:36, test_utilities.test_debug():
+        DEBUG: test_utilities.py, 37, test_utilities.test_debug():
             a = 'a'
             b = 'b'
             c = 'c'
@@ -45,22 +46,21 @@ def test_debug(capsys):
     ppp(a, b, c)
     captured = capsys.readouterr()
     assert captured[0] == dedent("""
-        DEBUG: test_utilities.py:45, test_utilities.test_debug():
-            a b c
+        DEBUG: test_utilities.py, 46, test_utilities.test_debug(): a b c
     """).lstrip()
 
     vvv(a, b, c)
     captured = capsys.readouterr()
     assert captured[0] == dedent("""
-        DEBUG: test_utilities.py:52, test_utilities.test_debug():
+        DEBUG: test_utilities.py, 52, test_utilities.test_debug():
             a = 'a'
             b = 'b'
             c = 'c'
     """).lstrip()
 
     sss()
     captured = capsys.readouterr()
-    assert captured[0].split('\n')[0] == "DEBUG: test_utilities.py:61, test_utilities.test_debug():"
+    assert captured[0].split('\n')[0] == "DEBUG: test_utilities.py, 61, test_utilities.test_debug():"
 
 def test_indent():
     text=dedent('''