django-cherrydev 0.1b
CherryPy Web server for Django development.
License: MIT

================
Django-CherryDev
================


Description
===========

This utility is a substitute for Django's ``runserver`` command. It was
inspired by Gunicorn_'s ``gunicorn_django`` command which makes it so easy
to serve Django projects without having to create extra WSGI scripts.

.. _Gunicorn: http://www.gunicorn.org/

I chose to use CherryPy as it is pure Python (thus cross-platform) and quite
efficient in its own right. It also had the functionality I desired to be able
to serve static media without fuss while developing Django applications.

**To be clear, this utility will automatically serve your static media (as well
as admin media) without needing to modify your settings.py or maintain a
development version of your settings.**

To do this, it modifies your settings.MEDIA_URL and settings.ADMIN_MEDIA_PREFIX
on the fly before loading Django, which is also the reason that it is not
provided as a custom management command.


Requirements and Installation
=============================

Django-CherryDev requires:

    - Django
    - CherryPy 3.1 or higher
    - setuptools or preferably `distribute
      <http://pypi.python.org/pypi/distribute/>`_
    - `argparse <http://pypi.python.org/pypi/argparse/>`_ (already included in
      Python 2.7)

Installation is as simple as ``pip install django-cherrydev``.

Source
------
You can install the latest development version from the `hg repository`_ with
``pip install -e hg+http://code.db-init.com/django-cherrydev`` or from a
tarball_ with ``pip install django-cherrydev==dev``.

.. _hg repository: http://code.db-init.com/django-cherrydev/
.. _tarball:
    http://code.db-init.com/django-cherrydev/get/tip.gz#egg=django-cherrydev-dev


Usage
=====

Django-CherryDev provides a single script, ``cherrydev``, which uses CherryPy
to serve your Django project and media files. To use it, simply CD into your
Django project directory and run ``cherrydev``::

    $ cd myproject
    $ cherrydev

Arguments
---------
usage: cherrydev [-h] [--noreload] [-b ADDRESS] [--nomedia] [-m MEDIA_ADDR]
                 [--noadmin] [-a ADMIN_ADDR] [-l LINK_DIR]
                 [SETTINGS_PATH]

positional arguments:
  SETTINGS_PATH         By default SETTINGS_PATH will look for settings.py in
                        the current directory.

optional arguments:
  -h, --help            show this help message and exit
  --noreload            Tells CherryPy to NOT use the auto-reloader.
  -b ADDRESS, --bind ADDRESS
                        The socket to bind. A string of the form: 'HOST',
                        'HOST:PORT'. An IP is a valid HOST. (default:
                        '127.0.0.1:8000')

Media:
  By default, CherryPy will be used to serve your media. If your MEDIA_URL
  includes a host component, it will be changed to an alternate port on
  localhost. If your ADMIN_MEDIA_PREFIX includes a host component that does
  not match that of MEDIA_URL, it will also be changed to its own alternate
  port.

  --nomedia             Tells CherryPy to NOT host media.
  -m MEDIA_ADDR, --media MEDIA_ADDR
                        The socket to bind media. A string of the form:
                        'HOST', 'HOST:PORT'. An IP is a valid HOST. (default:
                        '127.0.0.1:8001')
  --noadmin             Tells CherryPy to NOT host admin media.
  -a ADMIN_ADDR, --admin ADMIN_ADDR
                        The socket to bind admin. A string of the form:
                        'HOST', 'HOST:PORT'. An IP is a valid HOST. (default:
                        '127.0.0.1:8002')
  -l LINK_DIR, --link LINK_DIR
                        An additional directory to be linked to MEDIA_URL. May
                        be used multiple times. A string of the form:
                        'PATH=DIRECTORY'. (e.g. 'app=../myapp/media')