Jonathan Eunice committed 4976e51

ready to publish

  • Participants
  • Parent commits d4a268c

Comments (0)

Files changed (4)

 will turn on location reporting. This can also be set on call-by-call basis.
 ``show`` is built atop the `options <>`_ module
 for configuration management, and also the output management of
-`say <>`_. All ``say`` options work in show.
-See that module for additional detail.
+`say <>`_. All ``say`` options work in show. If you
+``show()`` a literal string, it will be iterpolated as it would be in ``say``::
+    show("{n} iterations, still running")
+yields something like::
+    14312 iterations, still running
+    s = '{n} iterations'
+    show(s)
+    s: '{n} iterations'
+See ``say`` `say <>`_ for additional detail on its
 Showing Collections
+The goal of ``show`` is to provide the most useful information possible,
+in the quickest and simplest way. Not requiring programmers to explicitly
+restate values and names in print statements is the start, but the module also
+provides some additional functions that provide a bit more semantic value.
+For example, ``say.items()`` is designed to make printing collections easy.
+It shows not just the values, but also the cardinality (i.e., length) of the
+    nums = list(range(4))
+    show.items(nums)
+    nums (4 items): [0, 1, 2, 3]
 Showing Object Properties
 an object, and isn't used in the technical sense of Python properties.)
 Properties will be listed alphabetically, but with those starting with underscores
 (``_``), usually indicating "private" data, sorted after those that are
-conventionally considered public.
+conventionally considered public. 
 If ``x`` has real ``@property`` members, those too displayed. However, other class
 attributes that ``x`` rightfully inherits, but that are not directly present in the
+ *  ``show`` is in its early days. Over time, it will provide additional
+    context-specific output helpers. For example, the "diff" views of ``py.test``
+    seem a high-value enhancement.
  *  Automated multi-version testing managed with the wonderful
     `pytest <>`_
     and `tox <>`_. ``show`` is 
-    version=verno("0.430"),
+    version=verno("0.437"),
     author='Jonathan Eunice',
     description='Debug print statements, done right. E.g. show(x)',
 # probably cannot make this work from interactive Python
+def format_escape(s):
+    """
+    Double { and } characters in a string to 'escape' them so ``str.format``
+    doesn't treat them as template characters. NB This is NOT idempotent!
+    Escaping more than once (when { or } are present ) = ERROR.
+    """
+    return s.replace('{', '{{').replace('}', '}}') 
 class Show(object):
     """Show objects print debug output in a 'name: value' format that
     is convenient for discovering what's going on as a program runs."""
         is eventually output by ``say``.
         fvalue = repr(value)
-        if isinstance(value, (dict, set)):
-            fvalue = fvalue.replace('{', '{{').replace('}', '}}') # escape { and }
-        return fvalue
+        return format_escape(fvalue)
     def arg_format(self, name, value, caller):


     x = 44
     assert show("x = {x}") == 'x = 44'
+def test_string_example():
+    n = 14312
+    assert show("{n} iterations, still running") == "14312 iterations, still running"
+    s = '{n} iterations'
+    assert show(s) == "s: '{n} iterations'"
 def test_set():
     s = set([1,2,99])