Metadata-Version: 1.0
Name: say
Version: 0.106
Summary: Simple formatted printing with templates
Home-page: https://bitbucket.org/jeunice/say
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
            nums = range(4)
            
            say("There are {x} things.")
            say("Nums has {len(nums)} items: {nums}")
            say("Or quoted: {[str(x) for x in nums]}")
            
        This is basically a nicer recasting of::
            
            print "There are {} things.".format(x)
            print "Nums has {} items:".format(len(nums))
            print "Or quoted: {}".format([str(x) for x in nums])
            
        Albeit with a nice inline, DRY, templated style that is
        clearer and simper than Python's defaults.
        
        Printing, or Not
        ================
        
        ``say()`` always returns the formatted text in addition to printing it.
        (Actually, the formatted text minus the final newline if it comes at the very
        end of the formatted string. While that's a little complicated to describe, it
        has the handy property of being exactly what you need in order to ``print`` or
        ``say`` the resulting text without a gratuitous "extra" newline.)
        
        If you want it to just the formatted text without the printing, ``say(...,
        silent=True)`` does the trick. 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 interpolates 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
