Metadata-Version: 1.1
Name: virtualenv-sh
Version: 0.2.2
Summary: Convenient shell interface to virtualenv
Home-page: https://bitbucket.org/psagers/virtualenv-sh
Author: Peter Sagerson
Author-email: psagers.pypi@ignorare.net
License: BSD, Public Domain
Description: =============
        virtualenv-sh
        =============
        
        This project is my personal substitute for the venerable `virtualenvwrapper
        <http://pypi.python.org/pypi/virtualenvwrapper>`_ (a set of shell functions to
        facilitate the use of `virtualenv <http://pypi.python.org/pypi/virtualenv>`_).
        Like many, I've used virtualenvwrapper for years, but it's gotten a bit heavy
        over time. I eventually found myself waiting too long for new shells to start
        up, even though I tended to use only the basic features.
        
        This project is an attempt to solve that problem. I borrowed the clever bits
        of virtualenvwrapper, discarded everything I considered expensive or just not
        interesting, and added a feature or two of my own. The number one priority of
        this project is speed. The code is almost pure shell script, although there
        may be one or two invocations of standard tools like grep or sed.
        
        Be warned that this implementation may not be for you. I may have gotten rid
        of a feature that you liked, either because it was expensive or because I just
        didn't care about it. I may have accidentally discarded a fix or workaround
        for some environment that I haven't encountered. I may have just introduced
        new bugs (shell is an easy language to get wrong in subtle ways). Proceed at
        your own risk.
        
        
        Installing
        ==========
        
        virtualenv-sh can be installed with pip or easy_install. To use it, you need
        to source a single shell script in your shell environment. By default, pip or
        easy_install should install it to /usr/local/bin. If you're using bash or zsh,
        you should import the shell-specific script; otherwise, you can try the
        generic one. Add *one* of the following to your shell's init script (.bashrc,
        .zshrc, etc.)::
        
            . /usr/local/bin/virtualenv-sh.bash
        
        ::
        
            . /usr/local/bin/virtualenv-sh.zsh
        
        ::
        
            . /usr/local/bin/virtualenv-sh.sh
        
        Nothing else is required. There's only one environment variable that you can
        use for configuration, which is WORKON_HOME. This is a path to your collection
        of virutalenvs; you can leave it blank to accept the default of
        ``${HOME}/.virtualenvs``. It is assumed that ``virtualenv`` itself is in your
        path.
        
        ::
        
            WORKON_HOME=${HOME}/.virtualenvs
        
        
        zsh
        ---
        
        If you're using zsh, you can instead use the precompiled function archive for
        optimal performance, although this needs to be compiled from source on your
        machine. You can download the source directly or try::
        
            > pip install --upgrade --no-install virtualenv-sh
            > cd build/virtualenv-sh
            > sudo make install
        
        This will find zsh in your path, use it to compile virtualenv-sh.zwc, and
        install it to /usr/local/bin. You can now autoload these functions and
        initialize virtualenv-sh. You may want to refer to the section on function
        autoloading in the zsh manual if you're not familiar with this process::
        
            # Configure all virtualenv-sh functions for autoloading
            fpath=(/usr/local/bin/virtualenv-sh $fpath)
            autoload -w /usr/local/bin/virtualenv-sh
        
            # Call the main initialization function
            virtualenv_sh_init
        
        
        Using
        =====
        
        The basic commands of virtualenv-sh are essentially the same as
        virtualenvwrapper. Here's a brief recap:
        
          ``mkvirtualenv <env_name>``
        
            Creates a new virtual_env in ``$WORKON_HOME``. All arguments are passed
            directly to ``virtualenv``. The new virtual_env will become active. Unlike
            virtualenvwrapper, this takes no additional arguments.
        
          ``rmvirtualenv <env_name>``
        
            Deletes an existing virtual_env. If this virtual_env is currently active,
            it is deactivated first as a courtesy.
        
          ``workon [<env_name>]``
        
            Activates the named virtual_env. If another virtual_env is currently
            active, it will be deactivated first. Without arguments, it will list the
            available virtual_envs. In compatible shells, you can choose a virtual_env
            from a menu.
        
          ``autoworkon``
        
            Automatically sets the virtual_env based on special files. See below.
        
          ``deactivate``
        
            Deactivates the current virtual_env (as when using ``virtualenv``
            directly).
        
          ``lsvirtualenvs``
        
            Prints a list of the virtual_envs you've created.
        
          ``cdvirtualenv [subdir]``
        
            Changes the current directory to the root of the active virtual_env, or a
            subdirectory thereof.
        
          ``lssitepackages``
        
            Lists the contents of the active virtual_env's site-packages directory.
        
          ``cdsitepackages [subdir]``
        
            Changes the currect directory to the site-packages directory of the active
            virtual_env, or a subdirectory thereof.
        
        
        Hooks
        =====
        
        virtualenv-sh supports the same global and local (per-env) hooks as
        virtualenvwrapper. Global hooks are files in $WORKON_HOME; local hooks are
        files in $WORKON_HOME/\{virtual_env\}/bin. Hooks are executed by sourcing them
        in the current shell context.
        
          initialize (global)
        
            Called at the end of virtualenv_sh_init.
        
          premkvirtualenv, postmkvirtualv, prermvirtualenv, postmkvirtualenv (global)
        
            Called at the beginning and end of mkvirtualenv and rmvirtualenv.
        
          preactivate, postactivate (global, local); predeactivate, postdeactivate (local, global)
        
            Called in the order indicated around activation and deactivation of a
            virtual_env.
        
        In addition, virtualenv-sh allows you to dynamically register functions to be
        called when executing hooks::
        
            virtualenv_sh_add_hook <hook_name> <function_name>
            virtualenv_sh_remove_hook <hook_name> <function_name>
        
        e.g.::
        
            my_virtualenv_cleanup()
            {
                # Do some stuff here
            }
        
            virtualenv_sh_add_hook postdeactivate my_virtualenv_cleanup
        
        Registered hook functions are always executed after all global and local hook
        scripts.
        
        
        autoworkon
        ==========
        
        autoworkon is a new command that is designed to automatically update your
        virtual_env based on your current directory. Note that there is no standard
        shell mechanism for running a function when the current directory changes--and
        many shells don't have such a mechanism--so installing this is up to you. If
        you're using zsh, you would use::
        
            autoload -U add-zsh-hook
            add-zsh-hook chpwd autoworkon
        
        The autoworkon function will walk up the filesystem from the current directory
        until it either reaches the root or finds an item named ".workon". If this is
        a readable file, it will treat the first line as the name of a virtual_env and
        activate it. There are a few special rules to keep in mind:
        
          * autoworkon always stops at the first .workon it finds. It's perfectly
            reasonable to have .workon files at multiple points in a directory tree to
            use different virtual_envs at different levels.
        
          * An empty or unreadable .workon file is interpreted as "no virtual_env".
            This is useful if you want to deactivate the automatic virtual_env in a
            particular subtree.
        
          * If you activate a virtual_env manually, autoworkon will never override it.
            autoworkon will only change your active virtual_env if it is unset or was
            previously set by autoworkon.
        
Keywords: virtualenv
Platform: UNKNOWN
Classifier: Programming Language :: Unix Shell
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: License :: Public Domain
