Metadata-Version: 1.0
Name: say
Version: 0.306
Summary: Simple formatted printing with templates. E.g.: say("Hello, {whoever}!")
Home-page: https://bitbucket.org/jeunice/say
Author: Jonathan Eunice
Author-email: jonathan.eunice@gmail.com
License: UNKNOWN
Description: This module is supplementd or replaced Python's ``print``
        statement/function, ``format`` function/method, and ``%`` string interpolation
        operator with higher-level facilities.
        
            **Q:** It's been *forty years* since ``C`` introduced ``printf()`` and the basic
            formatted printing of positional parameters. Isn't it time for an upgrade?
        
            **A:** Yes! ZOMG, yes!
            
        ``say`` provides straightforward string formatting with a DRY, Pythonic
        templating approach. It piggybacks the ``format()`` method, using its 
        formatting syntax (and underlying engine).
        
        Usage
        =====
        
        ::
        
            from say import say, fmt
            
            x = 12
            nums = list(range(4))
            
            say("There are {x} things.")
            say("Nums has {len(nums)} items: {nums}")
        
        yields::
        
            There are 12 things.
            Nums has 4 items: [1, 2, 3, 4]
            
        ``say`` is basically a simpler, nicer recasting of::
            
            print "There are {} things.".format(x)
            print "Nums has {} items: {}".format(len(nums), nums)
            
        The more items that are being printed, and the complicated the ``format``
        invocation, the more valuable having it stated in-line becomes. Note that full
        expressions are are supported. They are evaluated in the context of the caller.
        
        Printing Were You Like
        ======================
        
        ``say()`` writes to a list of files--by default just ``sys.stdout``. But
        with it simple configuration call, it will write to different--even multiple--
        files::
        
            from say import say, stdout
            
            say.setfiles(stdout, "report.txt")
            say(...)   # now prints to both stdout and report.txt
        
        This has the advantage of allowing you to capture program output without changing
        any code. You can also define your own targeted ``Say`` instances::
        
            from say import say, Say, stderr
            
            warn = say.clone().setfiles(stderr)
            err  = Say(files=[stderr, 'error.txt'])  # alternate constructor
            
            warn("This is a warning!")          # writes to stderr
            err("Failed with error {errcode}")  # writes to stderr, error.txt
        
        Printing When You Like
        ======================
        
        If you want to stop printing for a while::
        
            say.set(silent=True)  # no printing until set to False
            
        Or transiently::
        
            say(...stuff..., silent=not verbose) # prints iff bool(verbose) is True
        
        Of course, you don't have to print to any file. There's a predefined sayer
        ``fmt()`` that works exactly like ``say()`` and inherits most of
        its options, but 
        doesn't print. (The
        ``C`` analogy: ``say`` **:** ``fmt`` **::** ``printf`` **:** ``sprintf``.)
        
        Encodings
        =========
        
        ``say()`` and 
        ``fmt()`` try to work with Unicode strings, for example providing them as
        return values. But character encodings remain a fractious and often exasperating
        part of IT. When writing to files, ``say`` handles this with an 
        
        If you are using Python 2.7
        with strings containing ``utf-8`` rather than Unicode characters, ``say`` will
        not be greatly happy--but basically in the same places that ``format()`` is
        already not happy.
        
        When writing to files under Python 2.7, ``say`` writes using an encoding
        (by default, ``utf-8``). But you can get creative::
        
            say('I am a truck!', encoding='base64')  # SSBhbSBhIHRydWNrIQo=
        
        Or change the default::
        
            say.set(encoding='rot-13')
            
        Knock yourself out with `all the exciting opportunites <http://docs.python.org/library/codecs.html#standard-encodings>`_!
        If you really want the formatted text returned just as it is written to files,
        use the ``encoded`` option. Set to ``True`` it returns text in the output
        encoding. Or set to anything else, that becomes the return encoding.
        
        ``say()`` returns the formatted text with one small tweak: it removes the final
        newline if a newline is the very last character. Though odd, this is exactly
        what you need if you're going to ``print`` or
        ``say`` the resulting text without a gratuitous "extra" newline.
        
        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>`_.
        
        Python 3
        ========
        
        Say works the same way in both Python 2 and Python 3. This can simplify 
        software that should work across the versions, without all the ``from __future__
        import`` hassle.
        
        ``say`` attempts to mask some of the quirky compexities of the 2-to-3 divide,
        such as string encodings and codec use.
        
        Alternatives
        ============
        
         * `ScopeFormatter <http://pypi.python.org/pypi/ScopeFormatter>`_ is a
           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.
           
         * Even simpler are invocations of ``%`` or ``format()``
           using ``locals()``. E.g.::
           
               name = "Joe"
               print "Hello, %(name)!" % locals()
               # or
               print "Hello, {name}!".format(**locals())
               
           Unfortunately this has even more limitations than ``ScopeFormatter``: it only supports
           local variables, not globals or expressions. And the interpolation code seems
           gratuitous. Simpler::
           
              say("Hello, {name}!")
        
        Notes
        =====
        
         *  The ``say`` name was inspired by Perl's `say <http://perldoc.perl.org/functions/say.html>`_,
            but the similarity stops there.
           
         *  Automated multi-version testing with the wonderful
            `pytest <http://pypi.python.org/pypi/pytest>`_
            and `tox <http://pypi.python.org/pypi/tox>`_ modules has commenced. ``say`` is now
            successfully packaged for, and tested against, all late-model verions of
            Python: 2.6, 2.7, 3.2, and 3.3.
         
         *  ``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.
         
         *  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
        
        To ``easy_install`` under a specific Python version (3.3 in this example)::
        
            python3.3 -m easy_install say
            
        (You may need to prefix these with "sudo " to authorize installation.)
Keywords: print format template say
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: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.2
Classifier: Programming Language :: Python :: 3.3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
