© 2014-2020 Thomas Khyn
Buildout recipes for django development
The recipes available in djangorecipebook are mostly derived from djangorecipe's functionalities. However, while djangorecipe aims at generating all scripts in one part, djangorecipebook enables you to define one part per script (create, manage, wsgi, test, makemigrations), hence allowing the use of different settings and/or eggs for each part.
Through its automatic minimal settings generation, djangorecipebook is particularly adapted to reusable apps development, e.g. for testing or maintenance (migrations generation).
djangorecipebook works with django 2.2 and 3.0 and relevant python versions (3.5 to 3.8, depending on django version).
If you like djangorecipebook and find it useful, you may want to thank me and
encourage future development by sending a few mBTC / mBCH / mBSV at this address:
1EwENyR8RV6tMc1hsLTkPURtn5wJgaBfG9
.
- djangorecipebook:manage
- Creates a management script for the project
- djangorecipebook:wsgi
- Creates a wsgi script for the project
- djangorecipebook:gunicorn
- Creates a gunicorn service launcher for the project
- djangorecipebook:test
- Creates a script that invokes
manage.py test [apps]
, or pytest - djangorecipebook:makemigrations (new in v1.2)
- Generates Django migrations If you need to generate south migrations for Django < 1.7, you need to use djangorecipe 1.2.x or 1.3.x
- djangorecipebook:migrate (new in v1.2)
- Invokes
manage.py migrate [apps]
. For the lazy ones. - djangorecipebook:create
- Creates a django project from a user-defined template or using django's
startproject
management command. This recipe will not generate any script. The name of the created project is the name of the section.
- project-dir
The directory where the project files lie, relative to the buildout.cfg directory.
Defaults to
'.'
(buildout directory).- settings
The settings module to load, imported from the project directory.
Defaults to
'settings'
or a set of minimal settings, depending on the recipe.- extra-paths
Paths to add to sys.path in the generated script.
Defaults to
[]
.- envvars
Any environment variable that need to be set for the test run, one per line, under the form
VARIABLE = value
(spaces are tolerated).Defaults to no environment variable set.
- initialization
Some (basic) python initialization code to insert in the generated script. Don't forget that leading whitespaces are stripped.
Defaults to
''
.
- settings
If a settings module is not provided, the settings will be a set of minimal parameters, with the added installed apps below.
Defaults to minimal settings.
- inst_apps
The apps to add to the
INSTALLED_APPS
setting if no settings module is provided. This option should not be used when a settings module is provided.Defaults to
''
.- command
The management command to run, if any.
Defaults to no command (and in that case the
args
option is disabled).- args
Any command-line argument you wish to have added to the generated script, separated by spaces or line-breaks.
Defaults to no arguments.
- settings
- Must be a settings module, no default minimal settings are available for these recipes.
- log-file
The path to a log file where all stdout and/or stderr data should be redirected to.
Defaults to
''
, which disables logging- log-level
The level to log errors for. Can be one of INFO (stdout + stderr) or ERROR (stderr only).
Defaults to
INFO
.- virtualenv
The virtualenv that should be used to run the wsgi script. This requires virtualenv and virtualenvwrapper, as it relies upon the
WORKON_HOME
environment variable.Defaults to
''
, which disables any virtual environment setup.- script_path
The desired output path of the script, as a path to a filename relative to the buildout directory (= where the
buildout.cfg
file lies).Defaults to buildout's bin directory with the recipe's name.
- application (wsgi and gunicorn only)
Used with the
wsgi
recipe, it is the dotted path to a user-defined wsgi application, and defaults to the result of django'sget_wsgi_application()
.- Used with the
gunicorn
recipe, it can be: - unspecified (default), which means that the
gunicorn
script must be called with an parameter defining the WSGI application - a
path/to/a/wsgi:application
. Thegunicorn
script will set the current working directory topath/to/a
and usewsgi:application
as the application parameter auto
. The recipe will automatically generate awsgi
module using the providedsettings
,log-file
andlog-level
, and thegunicorn
script will refer to that module
- unspecified (default), which means that the
- Used with the
Warning
When using runner = pytest
, the settings
, inst_apps
, apps
options have no effect. You should instead provide a
pytest configuration file in the tests working directory.
- runner
Replaces `nose` option from version 1.3
Use this option if you are using nose (and therefore django_nose) to test your Django app or project. This will simply include
django_nose
andnose
in your buildout.Defaults to unset.
- workingdir
The working directory to launch the tests from.
Defaults to the current
- args
- See Manage options.
- settings, inst_apps
- See Manage options. Note that the
command
option is disabled. Not available when using pytest. - apps
The names of the apps that should be tested, separated by spaces or line-breaks. If using minimal settings, these apps will be added to the
INSTALLED_APPS
(in addition to those in theinst_apps
option).Defaults to
''
, all the apps inINSTALLED_APPS
. Not available when usingrunner = pytest
- settings, inst_apps, args
- See Manage options. Note that the
command
option is disabled. - apps
The names of the apps for which migrations should be generated, separated by spaces or line-breaks. If using minimal settings, these apps will be added to the
INSTALLED_APPS
(in addition to those in theinst_apps
option).Defaults to
''
, all the apps inINSTALLED_APPS
Same options as in Test options. The only difference is that you cannot use
minimal settings (the default is 'settings'
) nor the inst_apps
option.
Indeed, migrations generally need a database to migrate!
In create mode, the following common options are unused:
- extra-paths
- initialization
The settings import path must be set as it is used to determine whether the project has already been created or not.
The following options are added:
- template-dirs
The directories in which to search for user-defined project templates. This option may also be added in a
[djangorecipebook]
section (for example in the default.cfg file). See the Templates discovery section below.Defaults to the built-in templates directory, containing default django project templates.
- template
The template that should be used.
Defaults to the standard django project for the major version of django you are using.
- secret
The
SECRET_KEY
to be used in the created settings file(s).Defaults to a randomly generated alphanumeric key.
For more details on templating, see the Templates section below.
In create mode, a templating engine is available for greater personalisation of your django project initialization.
If a template-dirs option is found either in the recipe section or in a specific djangorecipebook section, the recipe searches in these directories - from the last defined to the first - for a subdirectory name matching the template name provided.
If the search is unsuccessful or if none of template-dirs or template are defined, the recipe uses the default template for the major version of django being used.
For example, if in ~/.buildout/default.cfg you have the following lines:
[djangorecipebook] template-dirs = /my/project/template/directory /my/project/template/directory2
And your buildout.cfg contains this section:
[mynewproject] recipe = djangorecipebook:create template-dirs = /my/other/template/dir template = mytemplate
The recipe will search for a mytemplate
directory in that order:
- /my/other/template/dir
- /my/project/template/directory2
- /my/project/template/directory
The template engine is as simple as it can be and relies upon pythons's
string.Template
. A variable can be inserted in any file or directory name or
file content in template directory using the syntax ${variable}
.
The following variables are available:
- any user-defined recipe option from the configuration file
secret
: the secret key for django settingsproject_name
: the project name (= the section name)year
: the current yearmonth
: the current monthday
: the current day of the month
For example, if you have in buildout.cfg:
[mynewproject] recipe = djangorecipebook:create template = mytemplate author = Thomas Khyn
for a copyright notice in a module docstring, you may use:
(c) ${year} ${author}
which will produce to the following output in the final file (if we are in 2014):
(c) 2014 Thomas Khyn
or, if you have a directory named ${project_name}_parameters
, the final name
will be mynewproject_parameters
.