Metadata-Version: 1.0
Name: qanda
Version: 0.1dev
Summary: Simple text prompts and validation for user input
Home-page: http://www.agapow.net/software/py-qanda
Author: Paul-Michael Agapow
Author-email: pma@agapow.net
License: MIT
Description: ===========
        About qanda
        ===========
        
        Background
        ----------
        
        Interactive command-line programs need to query users for information, be it
        text, choices from a list, or simple yes-or-no answers. *qanda* [qanda-home]_
        [qanda-pypi]_ module of simple functions to prompt users for such information,
        allowing validation and cleanup of answers, default responses, consistent
        formatting and presentation of help text, hints and choices. It is not a
        replacement for textual interfaces like curses and urwid, but intended solely
        for simple console scripts with user input is required.
        
        **Status:** *qanda* is in use by one other non-trivial library, and so is
        functional. However this is still an early release and the API may change.
        Comment is invited.
        
        
        Installation
        ------------
        
        The simplest way to install *qanda* is via ``easy_install`` [setuptools]_ or an
        equivalent program::
        
        % easy_install qanda
        
        Alternatively the tarball can be downloaded, unpacked and ``setup.py`` run::
        
        % tar zxvf qanda.tgz
        % cd qanda
        % python set.py install
        
        *qanda* has no prerequisites and should work with just about any version of
        Python.
        
        
        Using qanda
        -----------
        
        A full API is included in the source distribution.
        
        
        An example
        ~~~~~~~~~~
        
        ::
        
        >>> from qanda import prompt
        >>> prompt.string ("What is your name")
        What is your name: Foo
        >>> fname = prompt.string ("Your friends name is",
        help="I need to know your friends name as well before I talk to you.",
        hints="first name",
        default='Bar',
        )
        
        I need to know your friends name as well before I talk to you.
        Your friends name is (first name) [Bar]:
        >>> print fname
        Bar
        >>> years = prompt.integer ("And what is your age", min=1, max=100)
        And what is your age: 101
        A problem: 101 is higher than 100. Try again ...
        And what is your age: 28
        
        
        
        Central concepts
        ~~~~~~~~~~~~~~~~
        
        *qanda* packages all question-asking methods in a Session class. This allows
        the appearance and functioning of all these methods to be handled consistently
        and modified centrally. However, you don't necessarily have to create a Session
        to use it - there's pre-existing Session in the variable called ``prompt``::
        
        >>> from qanda import Session
        >>> s = Session()
        >>> from qanda import prompt
        >>> type (prompt)
        <class 'qanda.session.Session'>
        
        The question methods are named after the type of data they elicit::
        
        >>> print type(prompt.integer ("Pick a number"))
        Pick a number: 2
        <type 'int'>
        >>> print type(prompt.string ("Pick a name"))
        Pick a name: Bob
        <type 'string'>
        
        Many of the question methods with accept a list of "converters", each of which
        is used to successively transform or validate user input. This follows the idiom
        of Ian Bicking's FormEncode: raw values are passed into  a converter and the
        results are passed into the next. If input fails validation, the question is
        posed again. *qanda* supplies a number of basic validators:
        
        ToInt, ToFloat
        Convert inputs to other types
        Regex
        Only allow values that match a certain pattern
        Range
        Check that input falls within given bounds
        Length
        Check that input length falls within given bounds
        Synonyms
        Map values to other values
        Vocab
        Ensure values fall within a fixed set
        
        
        References
        ----------
        
        .. [qanda-home] `qanda home page <http://www.agapow.net/software/py-qanda>`__
        
        .. [qanda-pypi] `qanda on PyPi <http://pypi.python.org/pypi/qanda>`__
        
        .. [setuptools] `Setuptools & easy_install <http://packages.python.org/distribute/easy_install.html>`__
        
        
        
        History
        -------
        
        v0.1dev (20110624)
        ~~~~~~~~~~~~~~~~~~
        
        * Initial release, sure to be buggy and incomplete
Keywords: text commandline ui prompt
Platform: UNKNOWN
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: User Interfaces
