Source

show / README.rst

Diff from to

README.rst

-Simple, effective debug printing. 
-
-Usage
-=====
-
-::
-
-    from show import show
-    
-    x = 12
-    nums = list(range(4))
-    
-    show(x, nums)
-    
-yields::
-
-    x: 12  nums: [0, 1, 2, 3]
-
-Debug Printing
-==============
-
-Sometimes programs print so that users can see things, and sometimes they print
-so that develpopers can. ``show()`` is for developers, helping
-rapidly print the current state of variables. It 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)
-    
-will turn on location reporting. This can also be set on call-by-call basis.
-``show`` is built atop the `options <http://pypi.python.org/pypi/options>`_ module
-for configuration management, and also the output management of
-`say <http://pypi.python.org/pypi/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
-    
-While::
-
-    s = '{n} iterations'
-    show(s)
-    
-yields::
-
-    s: '{n} iterations'
-    
-See ``say`` `say <http://pypi.python.org/pypi/say>`_ for additional detail on its
-operation.
-
-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
-collection::
-
-    nums = list(range(4))
-    show.items(nums)
-    
-yields::
-
-    nums (4 items): [0, 1, 2, 3]
-
-Showing Object Properties
-=========================
-
-::
-
-    show.props(x)
-    
-shows the properties of object ``x``. ("Properties" here
-is generic language for "values" or "attributes" associated with
-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. 
-
-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
-``x`` instance, will not be displayed.
-
-An optional second
-parameter can determine which properties are shown. E.g.::
-
-    show.props(x, 'name,age')
-    
-Or if you prefer the keyword syntax, this is equivalent to::
-
-    show(x, props='name,age')
-    
-Interactive Limitations
-=======================
-
-``show`` has  draft support for both interactive Python and iPython.
-It orks 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>`_.
-
-Notes
-=====
-
- *  ``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 <http://pypi.python.org/pypi/pytest>`_
-    and `tox <http://pypi.python.org/pypi/tox>`_. ``show`` is 
-    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).
- 
- *  The author, `Jonathan Eunice <mailto:jonathan.eunice@gmail.com>`_ or
-    `@jeunice on Twitter <http://twitter.com/jeunice>`_
-    welcomes your comments and suggestions.
-
-Installation
-============
-
-::
-
-    pip install show
-
-To ``easy_install`` under a specific Python version (3.3 in this example)::
-
-    python3.3 -m easy_install show
-    
-(You may need to prefix these with "sudo " to authorize installation.)
+See README.rst