Source

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
contents::

    $ 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
``packagename-version.ext``.

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
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.