Source

say / README.rst

Diff from to

File README.rst

 invocation, the more valuable having it stated in-line becomes. Note that full
 expressions are are supported. They are evaluated in the context of the caller.
 
-``say()`` is the API for standard printing functions. A parallel API,
-``show()``, helps rapidly print the current state of variables. It 
-enables
-"debugging print statements" that don't require the craptastic repetition of
-``print "x = {x}".format(x)``. Instead, just::
+Debug Printing
+==============
+
+Sometimes programs print so that users can see things, and sometimes they print
+so that develpopers can. ``say()`` is the API for standard printing functions. A
+parallel API, ``show()``, helps rapidly print the current state of variables. It
+enables "debugging print statements" that don't require the craptastic
+repetition of ``print "x = {x}".format(x)``. Instead, just::
 
     show(x)
     show(nums)
     x: 12  nums: [0, 1, 2, 3]  len(nums): 4
 
 All of the standard keyword options for ``say()`` work for ``show()`` as well.
+If you'd like to see where the data is being produced, ``show.set(where=True)``
+will turn on location reporting.
+
+Sadly, because Python provides weaker introspection during
+interactive operation, (see e.g. `this <http://stackoverflow.com/questions/13204161/how-to-access-the-calling-source-line-from-interactive-shell>`_)
+``show()`` is somewhat limited in interactive use. It works at the main
+level and usually in imported modules, but does work within the body of functions defined
+interactively.
 
 Printing Where You Like
 =======================
     successfully packaged for, and tested against, all late-model verions of
     Python: 2.6, 2.7, 3.2, and 3.3, as well as PyPy 1.9 (based on 2.7.2).
  
+ *  Debug printing via ``show()`` is now operational.
+    Draft support for interactive Python and iPython. Works within imported modules,
+    and at the interactive prompt, but cannot be used
+    within interactively defined functions. Unknown whether that is a hard limit
+    of Python introspection, or something that can be worked around over time.
+
  *  ``say`` has greater ambitions than just simple template printing. It's part
-    of a larger rethinking of how output should be formatted. Stay tuned.
+    of a larger rethinking of how output should be formatted. ``show()``
+    is an initial down-payment. Stay tuned for more.
  
  *  In addition to being a practical module in its own right, ``say`` is
     testbed for `options <http://pypi.python.org/pypi/options>`_, a package
  *  The author, `Jonathan Eunice <mailto:jonathan.eunice@gmail.com>`_ or
     `@jeunice on Twitter <http://twitter.com/jeunice>`_
     welcomes your comments and suggestions.
+    
+To-Dos
+======
+
+ *  Provide code that allows ``pylint`` to see that variables used inside
+    the ``say`` and ``fmt`` format strings are indeed thereby used.
 
 Installation
 ============