Metadata-Version: 1.0
Name: say
Version: 0.105
Summary: Simple formatted printing with templates
Home-page: UNKNOWN
Author: Jonathan Eunice
Author-email: jonathan.eunice@gmail.com
License: UNKNOWN
Description: This module is intended to supplement or replace Python's ``print``
        statement/function, ``format`` function/method, and ``%`` string interpolation
        operator with higher-level facilities.
        
        It's been *forty years* since ``C`` introduced ``printf()`` and the basic
        formatted printing of positional parameters. Isn't it time for an upgrade?
        
        ``say`` provides straightforward string formatting with a DRY, Pythonic
        templating approach.
        
        Usage
        =====
        
        ::
        
            from say import say
            
            x = 12
            class R:
                biff = range(4)
            r = R()
            
            say("There are {x} things.")
            say("Biff has {len(r.biff)} items: {r.biff}")
            say("Or quoted: {[str(x) for x in r.biff]}")
            
        This is basically a nicer recasting of::
            
            print "There are {} things.".format(x)
            print "Biff has {} items:".format(len(r.biff))
            print "Or quoted: {}".format([str(x) for x in r.biff])
            
        Albeit with a nice inline, DRY, templated style that is
        clearer and simper than Python's defaults.
        
        Printing, or Not
        ================
        
        ``say()`` is a returns the value of the formatted text, in addition
        to printing it.
        
        If you want it to just format text, you can use
        ``say(..., silent=True)``. Or, there's a predefined sayer ``fmt()``
        that works like ``say()`` and inherits its options, but that doesn't
        print. (The ``C`` analogy: ``say``:``format``::``printf``:``sprintf``.)
        
        ``say()`` can also write to whatever file or files you like--with just a single
        additional configuration call, and no changes to your core code.  
        This is convenient
        when you want to see output, but also have it saved to a file.::
        
            from say import say
            import sys
            
            say.setfiles(sys.stdout, "report.txt")
            say(...)   # now prints to both stdout and report.txt
            
        ``say()`` and ``fmt()`` always return Unicode strings, but
        they write to files using an encoding. By default this is
        ``utf-8``.
        
        Titles and Horizontal Rules
        ===========================
        
        Say defines a few convenience formatting functions::
        
            say.title('Errors', sep='-')
            for i,e in enumerate(errors, start=1):
                say("{i:3}: {e['name'].upper()}")
                
        might yield::
        
            --------------- Errors ---------------
              1: I/O ERROR
              2: COMPUTE ERROR
        
        A similar method ``hr`` produces just a horizontal line, like
        the HTML ``<hr>`` element. For either, one can optionally 
        specify the width (``width``), character repeated to make the line (``sep``),
        and vertical separation/whitespace above and below the item (``vsep``).
        Good options for the separator might be be '-', '=', or parts of the `Unicode 
        box drawing character set <http://en.wikipedia.org/wiki/Box-drawing_character>`_.
        
        Notes
        =====
        
         * My goal is to make this module equally usable from Python 2 and Python 3.
           Most of my work is currently in Python 2.7, and I am a novice at cross-supporting
           both major language versions.
         
         * ``say`` has greater ambitions than just simple template printing. It's part
           of a larger rethinking of how output should be formatted. Stay tuned.
         
         * In addition to being a practical module in its own right, ``say`` is
           testbed for `options <http://pypi.python.org/pypi/options>`_, a package
           that provides high-flexibility option, configuration, and parameter
           management.
           
         * See also `ScopeFormatter <http://pypi.python.org/pypi/ScopeFormatter>`_, another
           module that provides variable interpolation into strings. It is amazingly
           compact and elegant. Sadly, it only iterpolates Python names, not full
           expressions. ``say`` has full expressions, as well as a framework for
           higher-level printing features beyond ``ScopeFormatter``'s...um...scope.
          
         * 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 say
            
        (You may need to prefix this with "sudo " to authorize installation.)
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: BSD License
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Libraries :: Python Modules
