.. _usage-label:

Usage
=====
As a simple package manager, Appypi is used to install, remove, upgrade
Pypi packages you may need. Here are the ways to do it.


Install a package
-----------------
Easy peasy::

    $ appypi install <package>

It may be a bit long the first time, as it constructs the package list.
You can install multiple packages in one line, each one will be installed
in an independant virtualenv::

    $ appypi install <package1> <package2> ...

Of course, if you try to install a package that is not on Pypi,
appypi will gently decline your proposition.
Same thing, if you try to install a package that don't have any launcher
to be used with, like in a library, appypi will stop the installation.
Unhappily, there is no way to know it before going far
into the installation process.


Remove a package
----------------
Sad, but true::

    $ appypi remove <package>

A confirmation for deletion is asked to the user. Again, you can remove
multiple packages at the same time::

    $ appypi remove <package1> <package2> ...


Upgrade a package
-----------------
You guessed right::

    $ appypi upgrade <package>

The given package is upgraded to the last version available on Pypi.


Upgrade all installed packages
------------------------------
Yes, it's easy::

    $ appypi upgrade

All packages are upgraded to their last versions available on Pypi.


Show information about a package
--------------------------------
::

    $ appypi show <package>

This prints details found on Pypi about the installed version of the package.
The full description is printed, so it may be a bit verbose.
For example, for the Projy_ package:

.. code-block:: python
    :linenos:

    Package: Projy
    Version: 0.2
    Author: Stéphane Péchard
    Homepage: https://github.com/stephanepechard/projy
    Summary: Projy is a template-based skeleton generator.

    Description: Projy
    =====
    **Projy is a template-based skeleton generator**.
    In one command line, you can generate project skeletons
    like Python packages, LaTeX document or any file structure
    composed of directories and files.

    Each file is generated by a different template.
    It uses the simple core templating system from Python,
    nothing fancy on that part. You can easily add new templates
    and new ways to collect data to insert in the created files.
    As much as possible, Projy tries to be simple to use and extend.

    See [the complete documentation](http://projy.readthedocs.org/).


    Installation
    ============
    If you are familiar with Python, it is strongly suggested that you
    install Projy in [virtualenv](http://pypi.python.org/pypi/virtualenv).


    Pip and Distribute
    ------------------
    If you are on Linux or Mac OS X, just type:

        $ sudo pip install projy

    If no pip available, try ``easy_install``:

        $ sudo easy_install projy


    Install from git
    ----------------
    If you prefer git, that is ok too. You can get the very latest code at
    Github:

        $ git clone http://github.com/stephanepechard/projy

    Usage
    =====
    As an example, let's create a Python package. The Projy template mostly
    follows recommendations from
    [The Hitchhiker's Guide to Packaging](http://guide.python-distribute.org/).


    A simple example
    ----------------
    Use simply:

        $ projy PythonPackage TowelStuff

    In the same directory as you typed this command, you now have a
    *TowelStuff* directory, with the following structure:


        TowelStuff/
            bin/
            bootstrap
            CHANGES.txt
            docs/
                index.rst
            LICENSE.txt
            MANIFEST.in
            README.txt
            setup.py
            towelstuff/
                __init__.py


    Each file has been created with a specific template, so the package is
    fully functional, yet empty. Now, let's give a little explanation
    on each file. You can find [further
    information here](http://guide.python-distribute.org/creation.html).


    Specify substitutions
    ---------------------
    You can specify template substitutions directly from the command line.
    Add them at the end of the previous example:

        $ projy PythonPackage TowelStuff "author,Emmett Brown" "date,1851-09-24"

    Then the substitutes *author* and *date* (defaulted to the current day)
    are defined by the given values, not those computed by Projy.
    The format of such substitutions should be "key,value". Neither the 
    key or the value should therefore include a comma.
    Leading and trailing spaces are removed from both key and value.

    To know which substitutions can be overwritten this way, use the *-i*
    option as described in the dedicated section. You can add substitutions
    that are not listed with the *-i* but they won't have any effect if the
    template file does not consider them.


    Options
    -------
    Projy comes with some command line options. Type:

        $ projy -l

    and you'll see the list of available templates in your installation.
    That's an easy way to copy/paste the name of the template you want
    to use next.

    Type

        $ projy -i PythonPackage

    and you'll see the details of the Python package template. It shows
    the created directories and files, with the substitutions included in
    the template.

    Available templates
    ===================
    The currently available templates are:

     * a [Fabric](http://fabfile.org) file ;
     * a [LaTeX](http://www.latex-project.org/) book ;
     * a [Python](http://python.org/) package ;
     * a Python script ;
     * a [Projy](https://github.com/stephanepechard/projy) template, meta-style.
     * a bootstrap file, to manage your virtualenv happiness ;

    See the official doc for more details on created files into these
    templates. Soon to come, more templates around Django. Of course, 
    anyone can propose some templates, they'll be integrated into Projy.


.. _Projy: http://pypi.python.org/pypi/Projy/0.2


List installed packages
-----------------------
Obviously::

    $ appypi list

The output shows the name, the version and the summary of every installed
package. Here is an example output::

    appypi - 4 installed packages
    ------------------------------
    Name       - Version - Summary
    ------------------------------
    Projy      - 0.2     - Projy is a template-based skeleton generator.
    Fabric     - 1.5.0   - Fabric is a simple, Pythonic tool for remote execution and deployment.
    subliminal - 0.6.2   - Subtitles, faster than your thoughts
    Glances    - 1.5.1   - CLI curses-based monitoring tool


Update the local list of Pypi packages
--------------------------------------
You guessed right::

    $ appypi update

Note that it is done programmatically every 7 days.

