jc-debug 1.0.2__tar.gz → 1.0.4__tar.gz

{jc_debug-1.0.2 → jc_debug-1.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jc-debug
-Version: 1.0.2
+Version: 1.0.4
 Summary: Makes debugging to the console both simpler and much more powerful.
 Author-email: Jeff Clough <jeff@cloughcottage.com>
 License: MIT License
@@ -42,8 +42,8 @@ Dynamic: license-file
 
 # debug
 
-This debug module a class named DebugChannel, instances of which are
-useful for adding temporary or conditional debug output to CLI scripts.
+This debug module a class named DebugChannel, instances of which are useful for
+adding temporary or conditional debug output to CLI scripts.
 
 The minimal boilerplate is pretty simple:
 
@@ -53,9 +53,9 @@ from debug import DebugChannel
 dc=DebugChannel(True)
 ```
 
-By default, DebugChannels are created disabled (the write no output), so
-the `True` above enables `dc` during its instantiation so it needn't be
-enabled later.
+By default, DebugChannels are created disabled (the write no output), so the
+`True` above enables `dc` during its instantiation so it needn't be enabled
+later.
 
 A more common way of handling this is ...
 
@@ -73,18 +73,18 @@ dc.enable(opt.debug)
 ...
 ```
 
-This enables the `dc` DebugChannel instance only if --debug is given on
-the script's command line.
+This enables the `dc` DebugChannel instance only if --debug is given on the
+script's command line.
 
 By default, output is sent to stdandard error and formatted as:
 
     '{label}: [{pid}] {basename}:{line}:{function}: {indent}{message}\n'
 
-There are several variables you can include in DebugChannel's output.
-See the DebugChannel docs below for a list.
+There are several variables you can include in DebugChannel's output. See the
+DebugChannel docs below for a list.
 
-So, for example, if you want to see how your variables are behaving in a
-loop, you might do something like this:
+So, for example, if you want to see how your variables are behaving in a loop,
+you might do something like this:
 
 ```python
 from debug import DebugChannel
@@ -96,15 +96,15 @@ dc=DebugChannel(
 
 dc("Entering loop ...").indent()
 for i in range(5):
-    dc(f"i={i}").indent()
+    dc(f"{i=}").indent()
     for j in range(3):
-        dc(f"j={j}")
+        dc(f"{j=}")
     dc.undent()("Done with j loop.")
 dc.undent()("Done with i loop.")
 ```
 
-That gives you this necely indented output. The indent() and undent()
-methods are one thing that makes DebugChannels so nice to work with.
+That gives you this necely indented output. The indent() and undent() methods
+are one thing that makes DebugChannels so nice to work with.
 
     DC:   8: Entering loop ...
     DC:  10:   i=0
@@ -134,8 +134,8 @@ methods are one thing that makes DebugChannels so nice to work with.
     DC:  13:   Done with j loop.
     DC:  14: Done with i loop.
 
-That's a simple example, but you might be starting to get an idea of
-how versatile DebugChannel instances can be.
+That's a simple example, but you might be starting to get an idea of how
+versatile DebugChannel instances can be.
 
 A DebugChannel can also be used as a function decorator:
 
@@ -163,9 +163,9 @@ example2("First test",3)
 example2("Second test",2)
 ```
 
-This causes entry into and exit from the decorated function to be
-recorded in the given DebugChannel's output. If you put that into a file
-named foo.py and then run "python3 -m foo", you'll get this:
+This causes entry into and exit from the decorated function to be recorded in
+the given DebugChannel's output. If you put that into a file named foo.py and
+then run "python3 -m foo", you'll get this:
 
 ```
 DC: __main__: example2('First test',3) ...
@@ -189,6 +189,54 @@ DC: example2:     example1(...) returns None after 23µs.
 DC: __main__: example2(...) returns None after 423ms.
 ```
 
+When outputting a data structure, it's nice to be a little structured about it.
+So if you send a list, tuple, dict, or set to a DebugChannel instance as the
+whole message, it will be formatted one item at a time in the output.
+
+```python
+from debug import DebugChannel
+
+dc=DebugChannel(True,fmt="{label}: {line:3}: {indent}{message}\n")
+
+l="this is a test".split()
+s=set(l)
+d=dict(zip('abcd',l))
+
+dc(l,'l')
+dc(s,'s')
+dc(d,'d')
+```
+
+Notice the first parameter is a data structure, and the second is the name of that data structure. This idiom creates output like this:
+
+```python
+DC:  12: l:
+DC:  12: [
+DC:  12:     'this',
+DC:  12:     'is',
+DC:  12:     'a',
+DC:  12:     'test'
+DC:  12: ]
+DC:  13: s:
+DC:  13: {
+DC:  13:     'a',
+DC:  13:     'is',
+DC:  13:     'test',
+DC:  13:     'this'
+DC:  13: }
+DC:  14: d:
+DC:  14: {
+DC:  14:     'a': 'this',
+DC:  14:     'b': 'is',
+DC:  14:     'c': 'a',
+DC:  14:     'd': 'test'
+DC:  14: }
+```
+
+Notice sets are output in alphabetical order (according to their repr()
+values). Since sets are unordered by nature, this makes them easier to inspect
+visually without misrepresenting their contents.
+
 That's a very general start. See DebugChannel's class docs for more.
 
 <a id="debug.DebugChannel"></a>
@@ -240,8 +288,8 @@ line number reported in its output are something helpful to the
 caller. For instance, the source line shouldn't be anything in this
 DebugChannel class.
 
-Use the ignoreModule() method to tell the DebugChannel object ignore
-other modules, and optionally, specific functions within that
+Use the ignoreModule() method to tell the DebugChannel object to
+ignore other modules, and optionally, specific functions within that
 module.
 
 <a id="debug.DebugChannel.__init__"></a>
@@ -457,11 +505,11 @@ supported.
 #### \_\_call\_\_
 
 ```python
-def __call__(arg, *args, **kwargs)
+def __call__(*args, **kwargs)
 ```
 
 If this DebugChannel instance is simply being called, this
-method is a very simple wrapper around the write(...) emthod. If
+method is a very simple wrapper around the write(...) method. If
 it is being used as a function decorator, that function entry
 and exit are recorded to the DebugChannel, and this becomes a
 more featuresome wrapper around the write(...) method.
@@ -482,13 +530,12 @@ output stream.
 #### write
 
 ```python
-def write(message)
+def write(message, var=None)
 ```
 
 If this debug instance is enabled, write the given message
-using the our current format. In any case, return this
-DebugChannel instance so further operations can be performed on
-it. E.g.:
+using the our current format. Return this DebugChannel instance
+so further operations can be performed on it. E.g.:
 
 ```python
 debug=DebugChannel(opt.debug)

{jc_debug-1.0.2 → jc_debug-1.0.4}/README.md

@@ -2,8 +2,8 @@
 
 # debug
 
-This debug module a class named DebugChannel, instances of which are
-useful for adding temporary or conditional debug output to CLI scripts.
+This debug module a class named DebugChannel, instances of which are useful for
+adding temporary or conditional debug output to CLI scripts.
 
 The minimal boilerplate is pretty simple:
 
@@ -13,9 +13,9 @@ from debug import DebugChannel
 dc=DebugChannel(True)
 ```
 
-By default, DebugChannels are created disabled (the write no output), so
-the `True` above enables `dc` during its instantiation so it needn't be
-enabled later.
+By default, DebugChannels are created disabled (the write no output), so the
+`True` above enables `dc` during its instantiation so it needn't be enabled
+later.
 
 A more common way of handling this is ...
 
@@ -33,18 +33,18 @@ dc.enable(opt.debug)
 ...
 ```
 
-This enables the `dc` DebugChannel instance only if --debug is given on
-the script's command line.
+This enables the `dc` DebugChannel instance only if --debug is given on the
+script's command line.
 
 By default, output is sent to stdandard error and formatted as:
 
     '{label}: [{pid}] {basename}:{line}:{function}: {indent}{message}\n'
 
-There are several variables you can include in DebugChannel's output.
-See the DebugChannel docs below for a list.
+There are several variables you can include in DebugChannel's output. See the
+DebugChannel docs below for a list.
 
-So, for example, if you want to see how your variables are behaving in a
-loop, you might do something like this:
+So, for example, if you want to see how your variables are behaving in a loop,
+you might do something like this:
 
 ```python
 from debug import DebugChannel
@@ -56,15 +56,15 @@ dc=DebugChannel(
 
 dc("Entering loop ...").indent()
 for i in range(5):
-    dc(f"i={i}").indent()
+    dc(f"{i=}").indent()
     for j in range(3):
-        dc(f"j={j}")
+        dc(f"{j=}")
     dc.undent()("Done with j loop.")
 dc.undent()("Done with i loop.")
 ```
 
-That gives you this necely indented output. The indent() and undent()
-methods are one thing that makes DebugChannels so nice to work with.
+That gives you this necely indented output. The indent() and undent() methods
+are one thing that makes DebugChannels so nice to work with.
 
     DC:   8: Entering loop ...
     DC:  10:   i=0
@@ -94,8 +94,8 @@ methods are one thing that makes DebugChannels so nice to work with.
     DC:  13:   Done with j loop.
     DC:  14: Done with i loop.
 
-That's a simple example, but you might be starting to get an idea of
-how versatile DebugChannel instances can be.
+That's a simple example, but you might be starting to get an idea of how
+versatile DebugChannel instances can be.
 
 A DebugChannel can also be used as a function decorator:
 
@@ -123,9 +123,9 @@ example2("First test",3)
 example2("Second test",2)
 ```
 
-This causes entry into and exit from the decorated function to be
-recorded in the given DebugChannel's output. If you put that into a file
-named foo.py and then run "python3 -m foo", you'll get this:
+This causes entry into and exit from the decorated function to be recorded in
+the given DebugChannel's output. If you put that into a file named foo.py and
+then run "python3 -m foo", you'll get this:
 
 ```
 DC: __main__: example2('First test',3) ...
@@ -149,6 +149,54 @@ DC: example2:     example1(...) returns None after 23µs.
 DC: __main__: example2(...) returns None after 423ms.
 ```
 
+When outputting a data structure, it's nice to be a little structured about it.
+So if you send a list, tuple, dict, or set to a DebugChannel instance as the
+whole message, it will be formatted one item at a time in the output.
+
+```python
+from debug import DebugChannel
+
+dc=DebugChannel(True,fmt="{label}: {line:3}: {indent}{message}\n")
+
+l="this is a test".split()
+s=set(l)
+d=dict(zip('abcd',l))
+
+dc(l,'l')
+dc(s,'s')
+dc(d,'d')
+```
+
+Notice the first parameter is a data structure, and the second is the name of that data structure. This idiom creates output like this:
+
+```python
+DC:  12: l:
+DC:  12: [
+DC:  12:     'this',
+DC:  12:     'is',
+DC:  12:     'a',
+DC:  12:     'test'
+DC:  12: ]
+DC:  13: s:
+DC:  13: {
+DC:  13:     'a',
+DC:  13:     'is',
+DC:  13:     'test',
+DC:  13:     'this'
+DC:  13: }
+DC:  14: d:
+DC:  14: {
+DC:  14:     'a': 'this',
+DC:  14:     'b': 'is',
+DC:  14:     'c': 'a',
+DC:  14:     'd': 'test'
+DC:  14: }
+```
+
+Notice sets are output in alphabetical order (according to their repr()
+values). Since sets are unordered by nature, this makes them easier to inspect
+visually without misrepresenting their contents.
+
 That's a very general start. See DebugChannel's class docs for more.
 
 <a id="debug.DebugChannel"></a>
@@ -200,8 +248,8 @@ line number reported in its output are something helpful to the
 caller. For instance, the source line shouldn't be anything in this
 DebugChannel class.
 
-Use the ignoreModule() method to tell the DebugChannel object ignore
-other modules, and optionally, specific functions within that
+Use the ignoreModule() method to tell the DebugChannel object to
+ignore other modules, and optionally, specific functions within that
 module.
 
 <a id="debug.DebugChannel.__init__"></a>
@@ -417,11 +465,11 @@ supported.
 #### \_\_call\_\_
 
 ```python
-def __call__(arg, *args, **kwargs)
+def __call__(*args, **kwargs)
 ```
 
 If this DebugChannel instance is simply being called, this
-method is a very simple wrapper around the write(...) emthod. If
+method is a very simple wrapper around the write(...) method. If
 it is being used as a function decorator, that function entry
 and exit are recorded to the DebugChannel, and this becomes a
 more featuresome wrapper around the write(...) method.
@@ -442,13 +490,12 @@ output stream.
 #### write
 
 ```python
-def write(message)
+def write(message, var=None)
 ```
 
 If this debug instance is enabled, write the given message
-using the our current format. In any case, return this
-DebugChannel instance so further operations can be performed on
-it. E.g.:
+using the our current format. Return this DebugChannel instance
+so further operations can be performed on it. E.g.:
 
 ```python
 debug=DebugChannel(opt.debug)

{jc_debug-1.0.2 → jc_debug-1.0.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "jc-debug"
-version = "1.0.2"  # Consider using a proper versioning scheme
+version = "1.0.4"  # Consider using a proper versioning scheme
 authors = [
   { name="Jeff Clough", email="jeff@cloughcottage.com" },
 ]

{jc_debug-1.0.2 → jc_debug-1.0.4}/src/debug/__init__.py

@@ -155,7 +155,7 @@ __all__ = [
     "DebugChannel",
     "line_iter",
 ]
-__version__ = "1.0.2"
+__version__ = "1.0.4"
 
 import inspect, os, sys, traceback
 
@@ -397,7 +397,7 @@ class DebugChannel:
 
         return self.write(seq)
 
-    def __call__(self, arg, *args, **kwargs):
+    def __call__(self, *args, **kwargs):
         """If this DebugChannel instance is simply being called, this
         method is a very simple wrapper around the write(...) emthod. If
         it is being used as a function decorator, that function entry
@@ -406,6 +406,7 @@ class DebugChannel:
 
         lines = inspect.stack(context=2)[1].code_context
         if lines and any(l.lstrip().startswith("@") for l in lines):
+            arg=args[0]
             # We're being called as a decorator.
             def f(*args, **kwargs):
                 # Record how this function is being called.
@@ -453,7 +454,7 @@ class DebugChannel:
             return f
 
         # This DebugChannel instance is being called as if it were a function.
-        return self.write(arg)
+        return self.write(*args)
 
     def writeTraceback(self, exc):
         """Write the given exception with traceback information to our
@@ -463,11 +464,14 @@ class DebugChannel:
             for line in traceback.format_exception(exc):
                 self.write(line.rstrip())
 
-    def write(self, message):
+    def write(self, message, var=None):
         """If this debug instance is enabled, write the given message
-        using the our current format. In any case, return this
-        DebugChannel instance so further operations can be performed on
-        it. E.g.:
+        using the our current format. If the var argument is given and
+        message is of type list, tuple, set, or dict, then var is
+        treated as the caller's name for the `message` parameter.
+
+        In any case, return this DebugChannel instance so further
+        operations can be performed on it. E.g.:
 
         ```python
         debug=DebugChannel(opt.debug)
@@ -494,88 +498,106 @@ class DebugChannel:
         If message is a dictionary, each key/value pair is written out
         as "key: value" to its own log line."""
 
-        if self.enabled:
-            # Update our formatted date and time if necessary.
-            t = int(get_time())  # Let's truncate at whole seconds.
-            if self._t != t:
-                t = self.time_tupler(t)
-                self._t = t
-                self.date = strftime(self.date_fmt, t)
-                self.time = strftime(self.time_fmt, t)
-            # Set local variables for date and time so they're available for output.
-            date = self.date
-            time = self.time
-            # Find the first non-ignored stack frame whence we were called.
-            pathname, basename, line = None, None, None
-            for i, frame in enumerate(inspect.stack()):
-                # This is for debugging debug.py. It turns out Python 3.6 has a bug in
-                # inspect.stack() that can return outrageous values for frame.index.
-                # (So I'm asking for only one line of context, and I've stopped using the
-                # frame's untrustworthy index value.)
-                #       print(f"""{i}:
-                #   frame:        {frame.frame!r}
-                #   filename:     {frame.filename!r}
-                #   lineno:       {frame.lineno!r}
-                #   function:     {frame.function!r}
-                #   code_context: {frame.code_context!r}
-                #   index:        {frame.index!r}""")
-                p = os.path.normpath(frame.filename)
-                if p not in self.ignore:
+        if not self.enabled:
+            return self
+
+        # Update our formatted date and time if necessary.
+        t = int(get_time())  # Let's truncate at whole seconds.
+        if self._t != t:
+            t = self.time_tupler(t)
+            self._t = t
+            self.date = strftime(self.date_fmt, t)
+            self.time = strftime(self.time_fmt, t)
+        # Set local variables for date and time so they're available for output.
+        date = self.date
+        time = self.time
+        # Find the first non-ignored stack frame whence we were called. Bail out
+        # if the calling code is to be ignored for debugging purposes.
+        pathname, basename, line = None, None, None
+        for i, frame in enumerate(inspect.stack()):
+            # This is for debugging debug.py. It turns out Python 3.6 has a bug in
+            # inspect.stack() that can return outrageous values for frame.index.
+            # (So I'm asking for only one line of context, and I've stopped using the
+            # frame's untrustworthy index value.)
+            #       print(f"""{i}:
+            #   frame:        {frame.frame!r}
+            #   filename:     {frame.filename!r}
+            #   lineno:       {frame.lineno!r}
+            #   function:     {frame.function!r}
+            #   code_context: {frame.code_context!r}
+            #   index:        {frame.index!r}""")
+            p = os.path.normpath(frame.filename)
+            if p not in self.ignore:
+                break
+                if frame.function not in self.ignore[p]:
                     break
-                    if frame.function not in self.ignore[p]:
-                        break
-            # Set some local variables so they'll be available to our callback
-            # function and for formatting.
-            pid = self.pid
-            pathname = os.path.normpath(frame.filename)
-            basename = os.path.basename(pathname)
-            line = frame.lineno
-            function = frame.function
-            if str(function) == "<module>":
-                function = "__main__"
-            code = frame.code_context
-            if code:
-                code = code[0].rstrip()
+        # Set some local variables so they'll be available to our callback
+        # function and for formatting.
+        pid = self.pid
+        pathname = os.path.normpath(frame.filename)
+        basename = os.path.basename(pathname)
+        line = frame.lineno
+        function = frame.function
+        if str(function) == "<module>":
+            function = "__main__"
+        code = frame.code_context
+        if code:
+            code = code[0].rstrip()
+        else:
+            code = None
+        indent = self.indstr * self.indlev
+        label = self.label
+
+        # If our caller provided a callback function, call that now.
+        if self.callback:
+            if not self.callback(**locals()):
+                return self  # Return without writing any output.
+
+        # Format our message and write it to the debug stream.
+        if isinstance(message, (list, set, tuple)):
+            if isinstance(message, tuple):
+                left, right = "()"
+            elif isinstance(message, set):
+                left, right = "{}"
+                message=sorted(list(message),key=lambda val:repr(val))
             else:
-                code = None
-            indent = self.indstr * self.indlev
-            label = self.label
-
-            # If our caller provided a callback function, call that now.
-            if self.callback:
-                if not self.callback(**locals()):
-                    return self  # Return without writing any output.
-
-            # Format our message and write it to the debug stream.
-            if isinstance(message, (list, tuple)):
-                if isinstance(message, tuple):
-                    left, right = "()"
-                else:
-                    left, right = "[]"
-                messages = message
-                message = left
+                left, right = "[]"
+            messages = message
+            if var:
+                message = f"{var} ({len(messages)}):"
                 self.stream.write(self.fmt.format(**locals()))
-                for message in messages:
-                    message = self.indstr + repr(message)
-                    self.stream.write(self.fmt.format(**locals()))
-                message = right
+            message = left
+            self.stream.write(self.fmt.format(**locals()))
+            for i in range(len(messages)):
+                m = messages[i]
+                message = f"{self.indstr}{m!r}"
+                if i<len(messages)-1:
+                    message+=','
                 self.stream.write(self.fmt.format(**locals()))
-            elif isinstance(message, dict):
-                messages = dict(message)
-                message = "{"
+            message = right
+            self.stream.write(self.fmt.format(**locals()))
+        elif isinstance(message, dict):
+            messages = dict(message)
+            if var:
+                message = f"{var} ({len(messages)}):"
                 self.stream.write(self.fmt.format(**locals()))
-                for k in messages.keys():
-                    message = f"{self.indstr}{k!r}: {messages[k]!r}"
-                    self.stream.write(self.fmt.format(**locals()))
-                message = "}"
+            message = "{"
+            self.stream.write(self.fmt.format(**locals()))
+            for i,(k,v) in enumerate(messages.items()):
+                message = f"{self.indstr}{k!r}: {v!r}"
+                if i<len(messages)-1:
+                    message+=','
                 self.stream.write(self.fmt.format(**locals()))
-            elif isinstance(message, str) and os.linesep in message:
-                messages = message
-                for message in line_iter(messages):
-                    self.stream.write(self.fmt.format(**locals()))
-            else:
+            message = "}"
+            self.stream.write(self.fmt.format(**locals()))
+        elif isinstance(message, str) and os.linesep in message:
+            # Handle multiline strings here.
+            messages = message
+            for message in line_iter(messages):
                 self.stream.write(self.fmt.format(**locals()))
-            self.stream.flush()
+        else:
+            self.stream.write(self.fmt.format(**locals()))
+        self.stream.flush()
 
         # The caller can call other DebugChannel methods on our return value.
         return self

{jc_debug-1.0.2 → jc_debug-1.0.4}/src/jc_debug.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jc-debug
-Version: 1.0.2
+Version: 1.0.4
 Summary: Makes debugging to the console both simpler and much more powerful.
 Author-email: Jeff Clough <jeff@cloughcottage.com>
 License: MIT License
@@ -42,8 +42,8 @@ Dynamic: license-file
 
 # debug
 
-This debug module a class named DebugChannel, instances of which are
-useful for adding temporary or conditional debug output to CLI scripts.
+This debug module a class named DebugChannel, instances of which are useful for
+adding temporary or conditional debug output to CLI scripts.
 
 The minimal boilerplate is pretty simple:
 
@@ -53,9 +53,9 @@ from debug import DebugChannel
 dc=DebugChannel(True)
 ```
 
-By default, DebugChannels are created disabled (the write no output), so
-the `True` above enables `dc` during its instantiation so it needn't be
-enabled later.
+By default, DebugChannels are created disabled (the write no output), so the
+`True` above enables `dc` during its instantiation so it needn't be enabled
+later.
 
 A more common way of handling this is ...
 
@@ -73,18 +73,18 @@ dc.enable(opt.debug)
 ...
 ```
 
-This enables the `dc` DebugChannel instance only if --debug is given on
-the script's command line.
+This enables the `dc` DebugChannel instance only if --debug is given on the
+script's command line.
 
 By default, output is sent to stdandard error and formatted as:
 
     '{label}: [{pid}] {basename}:{line}:{function}: {indent}{message}\n'
 
-There are several variables you can include in DebugChannel's output.
-See the DebugChannel docs below for a list.
+There are several variables you can include in DebugChannel's output. See the
+DebugChannel docs below for a list.
 
-So, for example, if you want to see how your variables are behaving in a
-loop, you might do something like this:
+So, for example, if you want to see how your variables are behaving in a loop,
+you might do something like this:
 
 ```python
 from debug import DebugChannel
@@ -96,15 +96,15 @@ dc=DebugChannel(
 
 dc("Entering loop ...").indent()
 for i in range(5):
-    dc(f"i={i}").indent()
+    dc(f"{i=}").indent()
     for j in range(3):
-        dc(f"j={j}")
+        dc(f"{j=}")
     dc.undent()("Done with j loop.")
 dc.undent()("Done with i loop.")
 ```
 
-That gives you this necely indented output. The indent() and undent()
-methods are one thing that makes DebugChannels so nice to work with.
+That gives you this necely indented output. The indent() and undent() methods
+are one thing that makes DebugChannels so nice to work with.
 
     DC:   8: Entering loop ...
     DC:  10:   i=0
@@ -134,8 +134,8 @@ methods are one thing that makes DebugChannels so nice to work with.
     DC:  13:   Done with j loop.
     DC:  14: Done with i loop.
 
-That's a simple example, but you might be starting to get an idea of
-how versatile DebugChannel instances can be.
+That's a simple example, but you might be starting to get an idea of how
+versatile DebugChannel instances can be.
 
 A DebugChannel can also be used as a function decorator:
 
@@ -163,9 +163,9 @@ example2("First test",3)
 example2("Second test",2)
 ```
 
-This causes entry into and exit from the decorated function to be
-recorded in the given DebugChannel's output. If you put that into a file
-named foo.py and then run "python3 -m foo", you'll get this:
+This causes entry into and exit from the decorated function to be recorded in
+the given DebugChannel's output. If you put that into a file named foo.py and
+then run "python3 -m foo", you'll get this:
 
 ```
 DC: __main__: example2('First test',3) ...
@@ -189,6 +189,54 @@ DC: example2:     example1(...) returns None after 23µs.
 DC: __main__: example2(...) returns None after 423ms.
 ```
 
+When outputting a data structure, it's nice to be a little structured about it.
+So if you send a list, tuple, dict, or set to a DebugChannel instance as the
+whole message, it will be formatted one item at a time in the output.
+
+```python
+from debug import DebugChannel
+
+dc=DebugChannel(True,fmt="{label}: {line:3}: {indent}{message}\n")
+
+l="this is a test".split()
+s=set(l)
+d=dict(zip('abcd',l))
+
+dc(l,'l')
+dc(s,'s')
+dc(d,'d')
+```
+
+Notice the first parameter is a data structure, and the second is the name of that data structure. This idiom creates output like this:
+
+```python
+DC:  12: l:
+DC:  12: [
+DC:  12:     'this',
+DC:  12:     'is',
+DC:  12:     'a',
+DC:  12:     'test'
+DC:  12: ]
+DC:  13: s:
+DC:  13: {
+DC:  13:     'a',
+DC:  13:     'is',
+DC:  13:     'test',
+DC:  13:     'this'
+DC:  13: }
+DC:  14: d:
+DC:  14: {
+DC:  14:     'a': 'this',
+DC:  14:     'b': 'is',
+DC:  14:     'c': 'a',
+DC:  14:     'd': 'test'
+DC:  14: }
+```
+
+Notice sets are output in alphabetical order (according to their repr()
+values). Since sets are unordered by nature, this makes them easier to inspect
+visually without misrepresenting their contents.
+
 That's a very general start. See DebugChannel's class docs for more.
 
 <a id="debug.DebugChannel"></a>
@@ -240,8 +288,8 @@ line number reported in its output are something helpful to the
 caller. For instance, the source line shouldn't be anything in this
 DebugChannel class.
 
-Use the ignoreModule() method to tell the DebugChannel object ignore
-other modules, and optionally, specific functions within that
+Use the ignoreModule() method to tell the DebugChannel object to
+ignore other modules, and optionally, specific functions within that
 module.
 
 <a id="debug.DebugChannel.__init__"></a>
@@ -457,11 +505,11 @@ supported.
 #### \_\_call\_\_
 
 ```python
-def __call__(arg, *args, **kwargs)
+def __call__(*args, **kwargs)
 ```
 
 If this DebugChannel instance is simply being called, this
-method is a very simple wrapper around the write(...) emthod. If
+method is a very simple wrapper around the write(...) method. If
 it is being used as a function decorator, that function entry
 and exit are recorded to the DebugChannel, and this becomes a
 more featuresome wrapper around the write(...) method.
@@ -482,13 +530,12 @@ output stream.
 #### write
 
 ```python
-def write(message)
+def write(message, var=None)
 ```
 
 If this debug instance is enabled, write the given message
-using the our current format. In any case, return this
-DebugChannel instance so further operations can be performed on
-it. E.g.:
+using the our current format. Return this DebugChannel instance
+so further operations can be performed on it. E.g.:
 
 ```python
 debug=DebugChannel(opt.debug)

{jc_debug-1.0.2 → jc_debug-1.0.4}/tests/test_operations.py

@@ -92,8 +92,8 @@ DC: test_basics:     Message 2
         dc(('a',2,True))
         assert outstr()=="""\
 DC: test_basics: (
-DC: test_basics:     'a'
-DC: test_basics:     2
+DC: test_basics:     'a',
+DC: test_basics:     2,
 DC: test_basics:     True
 DC: test_basics: )
 """
@@ -102,18 +102,28 @@ DC: test_basics: )
         dc(['a',2,True])
         assert outstr()=="""\
 DC: test_basics: [
-DC: test_basics:     'a'
-DC: test_basics:     2
+DC: test_basics:     'a',
+DC: test_basics:     2,
 DC: test_basics:     True
 DC: test_basics: ]
+"""
+
+        # Test set output.
+        dc(set(['a',2,True]))
+        assert outstr()=="""\
+DC: test_basics: {
+DC: test_basics:     'a',
+DC: test_basics:     2,
+DC: test_basics:     True
+DC: test_basics: }
 """
 
         # Test dictionary output.
         dc({'a':1,2:'b','c':True})
         assert outstr()=="""\
 DC: test_basics: {
-DC: test_basics:     'a': 1
-DC: test_basics:     2: 'b'
+DC: test_basics:     'a': 1,
+DC: test_basics:     2: 'b',
 DC: test_basics:     'c': True
 DC: test_basics: }
 """