.. _overview:

===================
Fromagerie Overview
===================

This document gives a brief overview of installing and using Fromagerie in a
Django_ project.


Installing Fromagerie
=====================

Fromagerie depends upon a working installation of Django_, version 1.0 or
newer.

Installation of Fromagerie itself can be achieved by downloading the
Fromagerie archive, extracting it, then, from the Fromagerie directory, 
invoking the included setup script from the command line as shown::

    $ python setup.py install

Note that this will install the Fromagerie package globally, therefore you
may need administrator privileges. For a list of other install options type::

    $ python setup.py install --help

at the command line in the Fromagerie directory.

Using Fromagerie in a Project
=============================

Once you have installed Fromagerie, you can add it to a Django_ project by
doing the following:

    1. Put ``'fromagerie'`` in your ``INSTALLED_APPS`` setting.
    2. Run the command ``manage.py syncdb``

These steps create the necessary database tables for Fromagerie.


Loading PyPI Classifiers
------------------------

A dump of the PyPI_ classifiers list is available as a fixture located in
``fixtures/classifiers.json`` and may be loaded by invoking
``manage.py loaddata classifiers.json``.


Enabling the Index Views
------------------------

To enable the default views, add the following pattern to your ``urlpatterns``
in your ``ROOT_URLCONF``::
    
    (r'^pypi/', include('fromagerie.urls')),


Customizing Views
-----------------

For information on customizing views, refer to the :ref:`views <views>`
documentation.


Interacting with the Fromagerie Package Index
=============================================


Using Distutils with Fromagerie
-------------------------------

Distutils_ may be used to register and upload packages to a Fromagerie index.
Assuming you are running the index locally at ``127.0.0.1:8000``, edit
``~/.pypirc`` to add the local index to the list of index servers for
Distutils_::

   [distutils]
   index-servers =
       pypi
       local

   [pypi]
   username: user
   password: secret

   [local]
   repository: http://127.0.0.1:8000/pypi/
   username: user
   password: secret

You may then interact with the index using Distutils_ like so::

    $ python setup.py [command] -r local

Specifying the local package index server as above, you can register packages,
releases, and manage your user account with the Fromagerie index.


Using EasyInstall with Fromagerie
---------------------------------

You may install packages from your Fromagerie index using EasyInstall_ by
passing ``easy_install`` an ``index-url`` argument like so::

    $ easy_install --index-url=http://127.0.0.1:8000/pypi/ some_package

or::

    $ easy_install -i http://127.0.0.1:8000/pypi/ some_package

or by specifying ``index-url`` in the ``easy_install`` section of your
Distutils_ configuration file, found in ``~/.pydistutils.cfg`` or
``HOME\\pydistutils.cfg`` on Unix-like systems and Windows systems
respectively::

    [easy_install]
    ...
    index-url = http://127.0.0.1:8000/pypi/
    ...

Note that the ``find-links`` option may be used to specify URLs to search for
package downloads as well.


Using zc.buildout with Fromagerie
---------------------------------

As with EasyInstall_, Buildout_ can be directed to use an alternate package
index server with the ``index`` option, or can be directed to search for
package downloads in pages returned by specified ``find-links`` URLs. User 
default values for these options can be specified in the default Buildout_
configuration found in ``$HOME/.buildout/default.cfg`` like so::

    [buildout]
    ...
    index = http://127.0.0.1:8000/pypi/
    ...


.. _Django: http://www.djangoproject.com/
.. _PyPI: http://pypi.python.org/pypi
.. _Distutils: http://docs.python.org/library/distutils.html
.. _EasyInstall: http://peak.telecommunity.com/DevCenter/EasyInstall
.. _Buildout: http://pypi.python.org/pypi/zc.buildout
