Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 98 lines (75 sloc) 3.37 kb
75c9685 @dcramer Added README, which describes how we want it to work
authored
1 Logan
2 =====
3
4 Logan is a toolkit for running standalone Django applications. It provides you
5 with tools to create a CLI runner, manage settings, and the ability to bootstrap
6 the process.
7
8 Let's take the Sentry project for example, it specifies that it wants to use logan
9 for running the application::
10
11 setup(
12 name='sentry',
13 install_requires=['logan'],
14 entry_points={
15 'console_scripts': [
d23ebb8 @dcramer initial commit
authored
16 'sentry = logan.runner:run_app',
75c9685 @dcramer Added README, which describes how we want it to work
authored
17 ],
18 },
19 )
20
21 It then defines several Django Management Commands as part of it's project, via the
22 standard structure of sentry/management/commands/<command name>.py.
23
24 Now when we call sentry. it's actually piping that to the logan runner. Logan simply
25 loads the predefined settings file (which defaults to PROJECT_CONF, or ~/.project/project.conf.py)
ba16f3c @dcramer Note about naming
authored
26 and then passes the command off to Django's internal representation of django-admin.py. In this case,
27 PROJECT is determined by the caller of logan.runner, which is "sentry". If it were "foo-bar", PROJECT
28 would be FOO_BAR, and "project" would still be "foo-bar".
75c9685 @dcramer Added README, which describes how we want it to work
authored
29
30 In most cases, you're also going to want to provide a default configuration to inherit from,
31 as well as a template to generate for the user if their configuration does not exist.
32
f70373d @dcramer It's better to package everything as a whole module, rather than top lev...
authored
33 To do this, within our sentry project we create a simple script, lets call put it in ``sentry/logan_runner.py``::
75c9685 @dcramer Added README, which describes how we want it to work
authored
34
d23ebb8 @dcramer initial commit
authored
35 from logan.runner import run_app
75c9685 @dcramer Added README, which describes how we want it to work
authored
36
37 def generate_settings():
38 """
39 This command is run when ``default_path`` doesn't exist, or ``init`` is
40 run and returns a string representing the default data to put into their
41 settings file.
42 """
43 return ""
44
45 def main():
d23ebb8 @dcramer initial commit
authored
46 run_app(
75c9685 @dcramer Added README, which describes how we want it to work
authored
47 project='sentry',
9ad1862 @dcramer Update README
authored
48 default_config_path='~/.sentry/',
3479623 @dcramer Update config used in readme
authored
49 default_settings='sentry.conf.defaults',
f70373d @dcramer It's better to package everything as a whole module, rather than top lev...
authored
50 settings_initializer='sentry.logan_runner.generate_settings',
9ad1862 @dcramer Update README
authored
51 settings_envvar='SENTRY_CONF',
75c9685 @dcramer Added README, which describes how we want it to work
authored
52 )
53
54 if __name__ == '__main__':
55 main()
ee7bd64 @dcramer Note about fixing up entry point after creating bootstrap
authored
56
57 We'd then slightly adjust our entry point in our ``setup.py``::
58
59 setup(
60 name='sentry',
61 install_requires=['logan'],
62 entry_points={
63 'console_scripts': [
f70373d @dcramer It's better to package everything as a whole module, rather than top lev...
authored
64 'sentry = sentry.logan_runner:main',
ee7bd64 @dcramer Note about fixing up entry point after creating bootstrap
authored
65 ],
66 },
67 )
8011256 @dcramer Some general cleanup and the start of tests
authored
68
69 You'll now be able to access the ``sentry`` command as if it were django-admin.py. Even better, it will
70 be configurable via an arbitrary settings file, and inherit any default settings you've specified::
71
72 # Note: run_gunicorn is provided by the gunicorn package
4dda275 @dcramer Add the ability to specify EXTRA_* for append settings
authored
73 sentry run_gunicorn 0.0.0.0:8000 -w 3
74
75 Extra Applications
76 ------------------
77
78 A need might come up to allow the user to register additional settings. These will automatically apply
79 based on keynames prefixed with ``EXTRA_`` assuming the base key (the latter part of the setting name) is
80 of type list or tuple.
81
82 For example, to register additional ``INSTALLED_APPS``, you would simply specify this in your custom
83 (user) configuration::
84
84b4194 @dcramer Correct extra apps example
authored
85 EXTRA_INSTALLED_APPS = (
4dda275 @dcramer Add the ability to specify EXTRA_* for append settings
authored
86 'foo.bar',
87 )
88
89 This will ensure your default setting's ``INSTALLED_APPS`` do not have to be modified, and the user
90 can specify additional apps with ease.
91
92 If you wish to disable this functionality, simply pass ``allow_extra=False`` to ``run_app``::
93
94 run_app(
95 # ...,
96 allow_extras=False,
97 )
Something went wrong with that request. Please try again.