Metadata-Version: 1.0
Name: fancycompleter
Version: 0.3
Summary: colorful TAB completion for Python prompt
Home-page: http://bitbucket.org/antocuni/fancycompleter
Author: Antonio Cuni
Author-email: anto.cuni@gmail.com
License: BSD
Description: .. -*- encoding: utf-8 -*-
        .. -*- restructuredtext -*-
        
        
        fancycompleter: colorful Python TAB completion
        ===============================================
        
        What is is?
        -----------
        
        ``fancycompleter`` is a module to improve your experience in Python by adding
        TAB completion to the interactive prompt.  It is an extension of the stdlib's
        rlcompleter_ module.
        
        Its best feature is that the completions are displayed in different colors,
        depending on their type:
        
        .. image:: http://bitbucket.org/antocuni/fancycompleter/raw/5bf506e05ce7/screenshot.png
        
        In the image above, strings are shown in green, functions in blue, integers
        and boolean in yellows, ``None`` in gray, types and classes in
        fuchsia. Everything else is plain white.
        
        ``fancycompleter`` is compatible with Python 3. However, by default colors
        don't work on Python 3, see the section `How do I get colors?`_ for details.
        
        Other features
        --------------
        
        * To save space on screen, ``fancycompleter`` only shows the characters "after
          the dot".  By contrast, in the example above ``rlcompleter`` shows
          everything prepended by "``sys.``".
        
        * If we press ``<TAB>`` at the beginning of the line, a real tab character is
          inserted, instead of trying to complete.  This is useful when typing
          function bodies or multi-line statements at the prompt.
        
        * Unlike ``rlcompleter``, ``fancycompleter`` **does** complete expressions
          containing dictionary or list indexing.  For example,
          ``mydict['foo'].<TAB>`` works (assuming that ``mydict`` is a dictionary and
          that it contains the key ``'foo'``, of course :-)).
        
        * Starting from Python 2.6, is the completed name is a callable,
          ``rlcompleter`` automatically adds an open parenthesis ``(``.  This is
          annoying in case we do not want to really call it, so ``fancycompleter``
          disable this behaviour.
        
        Installation
        ------------
        
        First, install the module with ``pip`` or ``easy_install``::
        
            $ pip install fancycompleter
        
        Then, at the Python interactive prompt::
        
            >>> import fancycompleter
            >>> fancycompleter.interact()
            >>>
        
        If you want to enable it automatically, you can those lines to your startup
        file (identified by the `PYTHONSTARTUP`_ environment variable).
        
        **Note**: depending on your particular system, ``interact`` might need to play
        dirty tricks in order to display colors, although everything should "just
        work™".  In particular, the call to ``interact`` should be the last line in
        the startup file, else the next lines might not be executed. See section `What
        is really going on?`_ for details.
        
        How do I get colors?
        ---------------------
        
        If you are using PyPy_, you can stop reading now, as ``fancycompleter`` will
        work out of the box.
        
        If you are on CPython and you installed ``fancycompleter`` with ``pip`` or
        ``easy_install``, they automatically installed ``pyrepl`` as a requirement,
        and you should also get colors out of the box.  If for some reason you don't
        want to use ``pyrepl``, you should keep on reading.
        
        By default, in CPython line input and TAB completion are handled by `GNU
        readline`_ (at least on Linux).  However, ``readline`` explicitly strips
        escape sequences from the completions, so completions with colors are not
        displayed correctly.
        
        There are two ways to solve it:
        
          * (suggested) don't use ``readline`` at all and rely on pyrepl_
        
          * use a patched version of ``readline`` to allow colors
        
        By default, ``fancycompleter`` tries to use ``pyrepl`` if it finds it.  To get
        colors you need a recent version, >= 0.8.2.
        
        If you are using Python 3, ``pyrepl`` does not work, and thus is not
        installed. Your only option to get colors is to use a patched ``readline``, as
        explained below.
        
        I really want to use readline
        ------------------------------
        
        This method is not really recommended, but if you really want, you can use use
        a patched readline: you can find the patches in the ``misc/`` directory:
        
          * for `readline-5.2`_
        
          * for `readline-6.0`_
        
        You can also try one of the following precompiled versions, which has been
        tested on Ubuntu 10.10: remember to put them in a place where the linker can
        find them, e.g. by setting ``LD_LIBRARY_PATH``:
        
          * readline-6.0 for `32-bit`_
        
          * readline-6.0 for `64-bit`_
        
        Once it is installed, you should double-check that you can find it, e.g. by
        running ``ldd`` on Python's ``readline.so`` module::
        
            $ ldd /usr/lib/python2.6/lib-dynload/readline.so | grep readline
                    libreadline.so.6 => /home/antocuni/local/32/lib/libreadline.so.6 (0x00ee7000)
        
        Finally, you need to force ``fancycompleter`` to use colors, since by default,
        it uses colors only with ``pyrepl``: you can do it by placing a custom config
        file in ``~/.fancycompleterrc.py``.  An example config file is `here`_ (remind
        that you need to put a dot in front of the filename!).
        
        .. _`readline-5.2`: http://bitbucket.org/antocuni/fancycompleter/src/tip/misc/readline-escape-5.2.patch
        .. _`readline-6.0`: http://bitbucket.org/antocuni/fancycompleter/src/tip/misc/readline-escape-6.0.patch
        .. _`32-bit`: http://bitbucket.org/antocuni/fancycompleter/src/tip/misc/libreadline.so.6-32bit
        .. _`64-bit`: http://bitbucket.org/antocuni/fancycompleter/src/tip/misc/libreadline.so.6-64bit
        .. _here: http://bitbucket.org/antocuni/fancycompleter/src/tip/misc/fancycompleterrc.py
        
        
        Customization
        --------------
        
        To customize the configuration of fancycompleter, you need to put a
        file named ``.fancycompleterrc.py`` in your home directory.  The file must
        contain a class named ``Config`` inheriting from ``DefaultConfig`` and
        overridding the desired values.
        
        
        What is really going on?
        -------------------------
        
        The default and preferred way to get colors is to use ``pyrepl``.  However,
        there is no way to tell CPython to use ``pyrepl`` instead of the built-in
        readline at the interactive prompt: this means that even if we install our
        completer inside pyrepl's readline library, the interactive prompt won't see
        it.
        
        The issue is simply solved by avoiding to use the built-in prompt: instead, we
        use a pure Python replacement based on `code.InteractiveConsole`_.  This
        brings us also some niceties, such as the ability to do multi-line editing of
        the history.
        
        The console is automatically run by ``fancycompleter.interact()``, followed by
        ``sys.exit()``: this way, if we execute it from the script in
        ``PYTHONSTARTUP``, the interpreter exits as soon as we finish the use the
        prompt (e.g. by pressing CTRL-D, or by calling ``quit()``).  This way, we
        avoid to enter the built-in prompt and we get a behaviour which closely
        resembles the default one.  This is why in this configuration lines after
        ``fancycompleter.interact()`` might not be run.
        
        Note that if we are using ``readline`` instead of ``pyrepl``, the trick is not
        needed and thus ``interact()`` will simply returns, letting the built-in
        prompt to show up.  The same is true if we are running PyPy, as its built-in
        prompt is based on pyrepl anyway.
        
        Does it work on Windows?
        ------------------------
        
        Unfortunately, not.  On Windows, ``readline`` is not available at all, and
        while pyrepl is written in pure Python, it sill makes use of unix specific
        syscalls to control the terminal.
        
        If you really want it, you might try to port pyrepl on Windows by writing the
        equivalent of `unix_console.py`_, or you can try to use pyreadline_ and adapt
        it to support colors in completions.  If you manage to make it working, I'd
        like to know, please :-).
        
        .. _rlcompleter: http://docs.python.org/library/rlcompleter.html
        .. _PYTHONSTARTUP: http://docs.python.org/using/cmdline.html#envvar-PYTHONSTARTUP
        .. _PyPy: http://pypy.org
        .. _`GNU readline`: http://tiswww.case.edu/php/chet/readline/rltop.html
        .. _pyrepl: http://codespeak.net/pyrepl/
        .. _`SVN repository`: http://codespeak.net/svn/pyrepl/trunk/pyrepl/
        .. _`code.InteractiveConsole`: http://docs.python.org/library/code.html#code.InteractiveConsole
        .. _`unix_console.py`: http://codespeak.net/svn/pyrepl/trunk/pyrepl/pyrepl/unix_console.py
        .. _pyreadline: https://code.launchpad.net/~pyreadline/
        
Keywords: rlcompleter prompt tab color completion
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX
Classifier: Topic :: Utilities
