1. Éric Araujo
  2. hhgp


hhgp / source / usage.txt

Using Packages

Finding Packages

.. note:: TODO I'm mentioning :ref:`pypi_info` everywhere. Should probably move
   this up in the documentation instead of explaining it over and over.

How does one find a package. Well, the simple answer is to check
:ref:`pypi_info` first. The other options are:

- To do a simple web search with google.com, yahoo, etc.
- Ask around the python community using :term:`IRC` 

We will cover the :ref:`pypi_info` later in the documentation.

Installing from other sources

When using the :ref:`pip_info` application, how does it know what to install
when you run ``pip install Markdown``? By default, it checks the
:ref:`pypi_info` for a package of that name. In this case, it found one; but
what if you want to install a package that hasn't been uploaded to PyPI?

You have several options:

- `Installing from a tarball`_
- `Installing from a Version Control System (VCS)`_
- `Add URLs to search for links`_

.. index:: tarball; install

Installing from a tarball

You can install directly from a tarball or zip file, as long as there
is a working ``setup.py`` file in the root directory of the unzipped

    $ pip install path/to/mypackage.tgz

You can also install from a tarball/zip file over the network::

    $ pip install http://dist.repoze.org/PIL-1.1.6.tar.gz

Installing from a Version Control System (VCS)

Using the ``--editable`` or ``-e`` option, pip has the capability to
install directly from a version control repository (it currently
supports Subversion, Mercurial, Git, and Bazaar)::

    $ pip install -e svn+http://svn.colorstudy.com/INITools/trunk#egg=initools-dev

This option shells out to the command-line client for each respective
VCS, so you must have the VCS installed on your system.  The repo URL
must begin with ``svn+`` (or ``hg+``, ``git+``, or ``bzr+``) and end
with ``#egg=packagename``; otherwise, pip supports the same URL
formats and wire protocols supported by the VCS itself.

Pip will checkout the source repo into a ``src/`` directory inside the
virtualenv (i.e. ``pip_test_env/src/initools-dev``), and then run
``python setup.py develop`` in that source repo. This "links" the code
directly from the repo into the virtualenv's ``site-packages``
directory (by adding the repo directory into ``easy-install.pth``), so
changes you make in the source checkout are effective immediately.

If you already have a local VCS checkout you want to keep using, you
can just use ``pip install -e path/to/repo`` to install it "editable"
in the same way.

Add URLs to search for links

You can use the ``-f`` or ``--find-links`` option to add another URL
pip should search for links to the package. If you dump some package
tarballs in a webserver directory and turn on automatic indexing, you
can point pip at that index page and install any of those packages,
assuming you named the files in the pattern

For example, if you upload a tarball ``MyApp-1.0.tgz`` to a
``my-packages`` directory on your webserver, and make sure indexing is
on for that directory, you can run::

    $ pip install MyApp -f http://www.example.com/my-packages/

.. index::
   single: package index; creating
   single: package index; chishop

Running your own package index

If you want more of the features provided by PyPI (including the
ability to upload packages with ``python setup.py sdist upload``), you
can run software such as `chishop`_, which implements the PyPI API, on
your own server. Then you can use pip's ``-i`` (or ``--index-url``) or
``--extra-index-url`` options to point it at your index.

For instance, if you set up your own index at
http://www.example.com/chishop/, you might run::

    $ pip install MyPrivateApp -i http://www.example.com/chishop/simple/

If you use ``-i`` pip won't check PyPI, only the index you provide. If
you are installing multiple packages at once, some from your index and
some from PyPI, you may want to use ``--extra-index-url`` instead, so
pip will check both indexes.

.. _chishop: http://github.com/ask/chishop