Commits

Jonathan Eunice committed 40f2f5f

fixed doc issue

Comments (0)

Files changed (3)

-See 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.)
 
 setup(
     name='show',
-    version=verno("0.476"),
+    version=verno("0.482"),
     author='Jonathan Eunice',
     author_email='jonathan.eunice@gmail.com',
     description='Debug print statements, done right. E.g. show(x)',
     long_description=open('README').read(),
     url='https://bitbucket.org/jeunice/show',
     packages=['show'],
-    install_requires=['six', 'options>=0.417', 'say>=0.83', 'stuf>=0.9.10', 'mementos>=0.5', 'codegen>=1.0'],
+    install_requires=['six', 'options>=0.417', 'say>=0.83', 'stuf>=0.9.10', 'mementos>=0.5', 'codegen'],
     tests_require = ['tox', 'pytest', 'six'],
     # zip_safe = True,
     keywords='debug print display show',

test/test_show.py

     assert show(a) == 'a: 1'
     assert show(a, b) == 'a: 1  b: 3.141'
     assert show(a, b, c) == "a: 1  b: 3.141  c: 'something else!'"
-    
-    assert show(1 + 1) == '1 + 1: 2'
-    assert nospaces(show(1+1)) == nospaces('1 + 1: 2')
-        # may have extra spaces in it, based on codegen.to_source() output
         
     assert show(len(c), c) == \
                 "len(c): 15  c: 'something else!'"
     assert show(1 + 1) == '1 + 1: 2'
     assert show(1+1) == '1 + 1: 2'
     
-    # assert nospaces(show(1+1)) == nospaces('1 + 1: 2')
+    # for when using astor as codegen replacement
+    # assert show(1 + 1) == '(1 + 1): 2'
+    # assert show(1+1) == '(1 + 1): 2'
     
     # NB output may have more or fewer spaces than actual parameter, based on codegen.to_source() 
     # creating its 'idealized' code output
+    
+    # when we were using codegen to recreate source, it did so without parenthesis
+    # astor uses parens -- which seem superflous here...but printing literals isn't
+    # the main use case, so whatever...
 
 def test_say_params():
     a = 1