cykooz.djangorecipe 1.2.1
Buildout recipe for Django
License: BSD

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

This project is a fork of django recipe (https://launchpad.net/djangorecipe)
originally created by Jeroen Vloothuis. Forked to alter for our internal workflow and directory structure.

This buildout recipe can be used to create a setup for Django. It will
automatically download Django and install it in the buildout's
sandbox.

You can see an example of how to use the recipe below::

  [buildout]
  parts = satchmo django
  eggs = ipython
  versions = versions

  [satchmo]
  recipe = gocept.download
  url = http://www.satchmoproject.com/snapshots/satchmo-0.6.tar.gz
  md5sum = 659a4845c1c731be5cfe29bfcc5d14b1

  [django]
  recipe = cykooz.djangorecipe
  settings = development
  eggs = ${buildout:eggs}
  extra-paths =
    ${satchmo:location}
  project = dummyshop

  [versions]
  Django = 1.3


Supported options
=================

The recipe supports the following options.

project
  This option sets the name for your project. The recipe will create a
  basic structure if the project is not already there.

projectegg
  Use this instead of the project option when you want to use an egg
  as the project. This disables the generation of the project
  structure.

python
  This option can be used to specify a specific Python version which can be a
  different version from the one used to run the buildout.

settings
  You can set the name of the settings file which is to be used with
  this option. This is useful if you want to have a different
  production setup from your development setup. It defaults to
  `development`.

extra-paths
  All paths specified here will be used to extend the default Python
  path for the `bin/*` scripts.

pth-files
  Adds paths found from a site `.pth` file to the extra-paths.
  Useful for things like Pinax which maintains its own external_libs dir.

control-script
  The name of the script created in the bin folder. This script is the
  equivalent of the `manage.py` Django normally creates. By default it
  uses the name of the section (the part between the `[ ]`).

wsgi
  An extra script is generated in the bin folder when this is set to
  `true`. This can be used with mod_wsgi to deploy the project. The
  default name of the script is `control-script.wsgi`.

wsgi-script
  The name of the wsgi script. 

logfile
  In case the WSGI server you're using does not allow printing to stdout,
  you can set this variable to a filesystem path - all stdout/stderr data
  is redirected to the log instead of printed

fcgi
  Like `wsgi` this creates an extra script within the bin folder. This
  script can be used with an FCGI deployment.

test
  If you want a script in the bin folder to run all the tests for a
  specific set of apps this is the option you would use. Set this to
  the list of app labels which you want to be tested.

testrunner
  This is the name of the testrunner which will be created. It
  defaults to `test`.

All following options only have effect when the project specified by
the project option has not been created already.

urlconf
  You can set this to a specific url conf. It will use project.urls by
  default.

media_root
  You can set this to a specific MEDIA_ROOT value.
  It default to `os.path.join(os.path.dirname(__file__), 'media')`

static_root
  You can set this to a specific STATIC_ROOT value (only for Django >= 1.3).
  It default to `os.path.join(os.path.dirname(__file__), 'static')`


FCGI specific settings
======================

Options for FCGI can be set within a settings file (`settings.py`). The options
is `FCGI_OPTIONS`. It should be set to a dictionary. The part below is an
example::

  FCGI_OPTIONS = {
      'method': 'threaded',
  }


Another example
===============

The next example shows you how to use some more of the options::

  [buildout]
  parts = django extras
  eggs =
    hashlib

  [extras]
  recipe = iw.recipe.subversion
  urls =
    http://django-command-extensions.googlecode.com/svn/trunk/ django-command-extensions
    http://django-mptt.googlecode.com/svn/trunk/ django-mptt

  [django]
  recipe = cykooz.djangorecipe
  settings = development
  project = exampleproject
  wsgi = true
  eggs =
    ${buildout:eggs}
  test =
    someapp
    anotherapp

Example using .pth files
========================

Pinax uses a .pth file to add a bunch of libraries to its path; we can
specify it's directory to get the libraries it specified added to our
path::

  [buildout]
  parts	= PIL
	  svncode
	  myproject

  [PIL]
  recipe	= zc.recipe.egg:custom
  egg		= PIL
  find-links	= http://dist.repoze.org/

  [svncode]
  recipe	= iw.recipe.subversion
  urls		= http://svn.pinaxproject.com/pinax/tags/0.5.1rc1	pinax

  [myproject]
  recipe	= cykooz.djangorecipe
  eggs		= PIL
  project	= myproject
  settings	= settings
  extra-paths	= ${buildout:directory}/myproject/apps
		  ${svncode:location}/pinax/apps/external_apps
		  ${svncode:location}/pinax/apps/local_apps
  pth-files	= ${svncode:location}/pinax/libs/external_libs
  wsgi		= true

Above, we use stock Pinax for pth-files and extra-paths paths for
apps, and our own project for the path that will be found first in the
list.  Note that we expect our project to be checked out (e.g., by
svn:external) directly under this directory in to 'myproject'.

Example with a different Python version
=======================================

To use a different Python version from the one that ran buildout in the
generated script use something like::

  [buildout]
  parts	= myproject

  [special-python]
  executable = /some/special/python

  [myproject]
  recipe	= cykooz.djangorecipe
  project	= myproject
  python		= special-python


Example configuration for mod_wsgi
==================================

If you want to deploy a project using mod_wsgi you could use this
example as a starting point::

  <Directory /path/to/buildout>
         Order deny,allow
         Allow from all
  </Directory>
  <VirtualHost 1.2.3.4:80>
         ServerName      my.rocking.server
         CustomLog       /var/log/apache2/my.rocking.server/access.log combined
         ErrorLog        /var/log/apache2/my.rocking.server/error.log
         WSGIScriptAlias / /path/to/buildout/bin/django.wsgi
  </VirtualHost>


Changes
=======

1.2.1
-----

- Correct documentation

1.2.0
-----

- Added support `Django 1.3`
- Added option `static_root`
- Fixed: remove from settings.py options DEBUG and TEMPLATE_DEBUG

1.1.2
-----

- Add `Django` into eggs of section, if it necessary.

1.1.1
-----

- Fixed: Add the necessary imports into `settings.py`

1.1
---

- Delete `manage.py` from project directory

1.0
---

- Forked from djangorecipe.

- Remove option `version`. Now Django installed from egg.

- Add option `wsgi-script` for change default wsgi script name.

- Now, the recipe creates the file `settigs.py` by using the `startproject` command from django.

0.20
----

- The recipe know makes the `django` package know to setuptools during install.
  This closes #397864. Thanks to Daniel Bruce and Dan Fairs for the patch.

- Fixed #451065 which fixes a problem with the WSGI log file option.

- Added the posibilty to configure more FCGI related settings. Thanks to Vasily
  Sulatskov for the patch.

0.19.2
------

- The generated WSGI & FCGI scripts are now properly removed when
  options change (fixes #328182). Thanks to Horst Gutmann for the
  patch.

- Scripts are now updated when dependencies change. This fixes #44658,
  thanks to Paul Carduner for the patch.

0.19.1
------

- Applied fix for the change in WSGI script generation. The previous
  release did not work properly.

0.19
----

- When running again with non-newest set the recipe will no longer
  update the Subversion checkout. Thanks to vinilios for the patch.

- The WSGI and FCGI scripts are now generated using Buildout's own
  system. This makes them more similar to the generated manage script
  with regard to the setup of paths. Thanks to Jannis Leidel for the
  patch.

0.18
----

- Paths from eggs and extra-paths now get precedence over the default
  system path (fixes #370420). Thanks to Horst Gutmann for the patch.

- The generated WSGI script now uses the `python` option if
  present. This fixes #361695.

0.17.4
------

- Fixed a problem when not running in verbose mode (fixes #375151).

0.17.3
------

- Removed dependency on setuptools_bzr since it does not seem to work
  like I expected.

0.17.2
------

- Changed the download code to use urllib2. This should make it work
  from behind proxies (fixes #362822). Thanks to pauld for the patch.

0.17.1
------

- Fixed a problem with the new WSGI logging option #348797. Thanks to
  Bertrand Mathieu for the patch.

- Disable generation of the WSGI log if "wsgilog" isn't set, thanks to
  Jacob Kaplan-Moss for the patch.

- Updated buildout.cfg and .bzrignore, thanks Jacob Kaplan-Moss.

0.17
----

- Added an option to specify a log file for output redirection from
  the WSGI script. Thanks to Guido Wesdorp for the patch.

0.16
----

- Subversion aliases are now supported (something like
  svn+mystuff://myjunk). Thanks to Remco for the patch.

0.15.2
------

- Update to move pth-files finder from the __init__ method to the
  install method so it runs in buildout-order, else it looks for pth
  files in dirs that may not yet exist. Thanks to Chris Shenton for
  the update to his original patch.

0.15.1
------

- Update to make the previously added pth-files option better
  documented.

0.15
----

- Added "pth-files" option to add libraries to extra-paths from
  site .pth files. Thanks to Chris Shenton for the patch.

0.14
----

- The recipe now supports creating a FCGI script. Thanks to Jannis
  Leidel for the patch.

- When downloading a Django recipe for the first time the recipe now
  properly reports the url it is downloading from.

0.13
----

- Specifying a user name within a subversion url now works. The code
  that determined the revision has been updated. This fixes issue
  #274004. Thanks to Remco for the patch.

- Updated the template for creating new projects. It now uses the
  current admin system when generating it's `urls.py` file. This fixes
  issue #276255. Thanks to Roland for the patch.

0.12.1
------

- Re-upload since CHANGES.txt was missing from the release

0.12
----

- The recipe no longer executes subversion to determine whether the
  versions is to be downloaded using subversion. This fixes issue
  #271145. Thanks to Kapil Thangavelu for the patch.

- Changed the `pythonpath` option to `extra-paths`. This makes the
  recipe more consistent with other recipes (see issue #270908).

0.11
----

- Another go at fixing the updating problem (#250811) by making sure
  the update method is always called. It would not be called in the
  previous version since the recipe wrote a random secret (if it
  wasn't specified) to the options for use with a template. Buildout
  saw this as a change in options and therefore always decided to
  un-install & install.

- When both projectegg and wsgi=True are specified, the generated wsgi
  file did not have the correct settings file in it. This has been
  fixed with a patch from Dan Fairs.

- The recipe now has logging. All print statements have been replaced
  and a few extra logging calls have been added. This makes the recipe
  more informative about long running tasks. Thanks erny for the patch
  from issue #260628.

0.10
----

- The recipe no longer expects the top level directory name in a
  release tarball to be consistent with the version number. This fixes
  issue #260097. Thanks to erny for reporting this issue and
  suggesting a solution.

- Revision pinns for the svn checkout now stay pinned when re-running
  the buildout. This fixes issue #250811. Thanks to Remco for
  reporting this.

- Added an option to specify an egg to use as the project. This
  disables the code which creates the basic project structure. Thanks
  to Dan Fairs for the patch from issue #252647.

0.9.1
-----

- Fixed the previous release which was broken due to a missing
  manifest file

0.9
---

- The settings option is fixed so that it supports arbitrary depth
  settings paths (example; `conf.customer.development`).

- The version argument now excepts a full svn url as well. You can use
  this to get a branch or fix any url to a specific revision with the
  standard svn @ syntax

- The wsgi script is no longer made executable and readable only by
  the user who ran buildout. This avoids problems with deployment.