Commits

Jonathan Eunice committed c88ae03

Updated docs.

Comments (0)

Files changed (3)

   * Added ``noshow`` object for easy turning off of showing.
   * General cleanups. Tightened imports. Tweaked docs. Switched to
     ``FmtException`` from ``say>=1.0.4``, and separated extensions
-    into won module.
+    into own module.
   * Drove version information into ``version.py``
 
 1.0.1 (September 2013)
   * Added ``noshow`` object for easy turning off of showing.
   * General cleanups. Tightened imports. Tweaked docs. Switched to
     ``FmtException`` from ``say>=1.0.4``, and separated extensions
-    into won module.
+    into own module.
   * Drove version information into ``version.py``
 
 1.0.1 (September 2013)
 
 Sometimes programs print so that users can see things, and sometimes they print
 so that developers can. ``show()`` is for developers, helping
-rapidly print the current state of variables. It replaces require the craptastic
+rapidly print the current state of variables. A simple invocation::
+
+    show(x)
+
+replaces require the craptastic
 repetitiveness of::
 
     print "x: {0}".format(x)
 
-with::
-
-    show(x)
-
 If you'd like to see where the data is being produced,::
 
     show.set(where=True)
 
     __main__():21:   d: 'this'
 
-The ``where`` property, along with most every option, can be set on call-by-call basis.
+The ``where`` property, along with most every option, can be set
+permanently, over the scope of a ``where`` block, or on call-by-call basis.
 ``show`` is built atop the `options <http://pypi.python.org/pypi/options>`_ module
 for configuration management, and the output management of
 `say <http://pypi.python.org/pypi/say>`_. All ``say`` options are available. If you
 and up-level common formatting tasks.
 
 
-Collections
-===========
+Collections and Items
+=====================
 
 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
+restate values and names in print statements is the start, but it 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
 ===============
 
 Often it's convenient to only display debugging information under some conditions,
+but not others,
 such as when a ``debug`` flag is set. That often leads to multi-line conditionals
 such as::
 
         print "x:", x, "y:", y, "z:", z
 
 With ``show`` it's a bit easier. There's a keyword argument, also called
-``show``, that controls whether anything is shown. Set it to ``True`` or ``False``
-to show or not show, or set it to the debug flag::
+``show``, that controls whether anything is shown. If it's truthy, it shows;
+falsy, ad it doesn't::
 
     show(x, y, z, show=debug)
 
-Or set the show/don't show more globally::
+You can set the show flag more globally::
 
-    show.set(show=False)  # turn off showing
+    show.set(show=False)
 
 You can also make multiple ``show`` instances that can be separately controlled::
 
 .. note:: This assignment should be done in a global context. If done inside a
     function, you'll need to add a corresponding ``global show`` declaration.
 
-As an alternative, you can always have::
+As an alternative, you can::
 
     from show import show
     from show import noshow as show
 
-Then comment out the ``noshow`` line when you do want debug printing.
+Then comment out the``noshow`` line for debugging, or the ``show`` line for production
+runs.
 
 .. note:: A little care is required to configure global non-showing behavior
     if you're using ``show``'s function decorators such as ``@show.inout``.
     from pprint import pformat
     show.set(fmtfunc=pformat)
 
-    # NB pformat, not pprint!
-
-Or to configure ``pformat`` more precisely::
+Or to configure separate data and
+code formatters::
 
     show.set(fmtfunc=lambda x: pformat(x, indent=4, width=120, depth=5))
+    show.set(fmtcode=lambda x: highlight(x, ...))
 
-Or you can set more complex pretty printing functions, using syntax
-highlighting and other transformations. As a convenience, ``show``
-provides a method that uses ``pygments`` and
-``pprint`` in concert to more attractively display text. Just::
-
-    show.prettyprint()
-
-does the trick. It also takes ``indent``, ``depth``, and ``width`` options
+As a convenience, the ``show.prettyprint()`` configures
+``pygments`` and
+``pprint`` in concert to more attractively display text on
+ANSI terminals. Just run it once after importing ``show``.
+It also takes ``indent``, ``depth``, and ``width`` options
 for ``pformat`` and the ``style`` (style name) option for ``pygments``.
 Some style names to try::
 
 
 It's often helpful to figure out "what am I dealing with here? what attributes
 or methods or properties are available to me?" This is where ``show.dir`` comes
-into play. You could do ``show(dir(x))``, but ``show.dir(x)`` will show you more
-information, and do so more compactly. It also allows you to filter out the
+into play. You could do ``show(dir(x))``, but ``show.dir(x)`` will provides more
+information, and does so more compactly. It also allows you to filter out the
 often huge hubbub of some objects. By default, it doesn't show any attributes
 starting with double underscore ``__``. You can control what's omitted with the
 ``omit`` keyword argument. ``show.dir(x, omit=None)`` shows everything, while
 Interactive Limitations
 =======================
 
-``show`` has  draft support for both interactive Python and iPython.
-It works well at the
-interactive prompt, and within imported modules. It cannot, however, be used
-within functions and classes defined within the interactive session. This is
-due to how Python supprots--or fails to support--introspection in this instance.
-Whether this is a hard limit, or something
-that can be worked around over time, remains to be seen.
-
-See e.g. `this <http://stackoverflow.com/questions/13204161/how-to-access-the-calling-source-line-from-interactive-shell>`_.
+``show`` has experimental support for interactive Python and iPython. It works
+well at the interactive prompt, and within imported modules. It cannot, however,
+be used within functions and classes defined within the interactive session.
+This is a result of how Python supprots--or fails to support--introspection for
+interactively defined code. Whether this is a hard limit, or something that can
+be worked around over time, remains to be seen. (See e.g. `this discussion
+<http://stackoverflow.com/questions/13204161/how-to-access-the-calling-source-line-from-interactive-shell>`_).
 
 Python under Windows does not support readline the same way it is supported
-on Unix, Linux, and Mac OS X. As of version 0.60, experimental
+on Unix, Linux, and Mac OS X. Experimental
 support is provided for the use of ``pyreadline`` under Windows to correct
 this variance. This feature is yet untested. Works/doesn't work reports welcome!
 
     context-specific output helpers. For example, the "diff" views of ``py.test``
     seem a high-value enhancement.
 
- *  ``show`` depends on introspection, with its various complexities. It assumes
-    that all objects are new-style classes, and that your program has not
-    excessively fiddled with class data. Diverge from these assumptions, and all
-    bets are off.
+ *  ``show`` depends on introspection, with its various complexities and
+    limitations. It assumes that all objects are new-style classes, and that
+    your program has not excessively fiddled with class data. Diverge from these
+    assumptions, and all bets are off.
 
  *  Automated multi-version testing managed with the wonderful `pytest
     <http://pypi.python.org/pypi/pytest>`_ and `tox