django-boss is an implementation of the ideas outlined in my blog post on
Django management commands. With django-boss, you can specify commands in
individual apps and then run them using the djboss command-line interface.
If settings.DEBUG is True, the default logging level will be set to DEBUG.
Otherwise it will be WARN.
django-boss is now free and unencumbered software released into the public
domain.
You can now use the MODEL_LABEL argparse type to define arguments which take
model specifiers. The arguments object will contain the model class. For
example:
from djboss.commands import *
@command
@argument('model', type=MODEL_LABEL)
def print_model(args):
"""Print the class object for a specified model."""
print args.model
Could be run like this:
$ djboss print-model auth.user
<class 'django.contrib.auth.User'>
Model specifiers take the form app_label.model_name, where model_name is
case-insensitive.
You can now use the APP_LABEL argparse type to define an argument which takes
the name of an installed Django app; the attribute on the arguments object will
hold the appropriate module object. For example, this:
from djboss.commands import *
@command
@argument('app', type=APP_LABEL)
def print_app(args):
"""Print the module object for a specified app."""
print args.app
Would run like this:
$ djboss print-app auth
<module 'django.contrib.auth' from '/.../auth/__init__.pyc'>
django-boss now comes with a manage command that lets you run native
Django management commands under djboss. For example:
$ djboss manage --help
$ djboss manage syncdb
$ djboss manage runserver --help
So you can (if you want) delete the ./manage.py file in your project and use
djboss exclusively!
At the moment, installation is done via easy_install django-boss or
pip install django-boss. The only prerequisites are
argparse, whose installation is handled by
setuptools, and Django, which you should have
installed by now anyway.
Commands are defined as instances of djboss.commands.Command, present in a
commands submodule inside an installed app. For example, take the following
app layout:
echoapp/
|-- __init__.py
|-- commands.py
`-- models.py
The commands.py file is a submodule that can be imported as
echoapp.commands.
The following is a complete example of a valid commands.py file:
from djboss.commands import *
@command
def hello(args):
"""Print a cliche to the console."""
print "Hello, World!"
This example uses the @command decorator to declare that the function is a
django-boss command. You can add arguments to commands too; just use the
@argument decorator (make sure they come after the @command):
@command
@argument('-n', '--no-newline', action='store_true',
help="Don't append a trailing newline.")
def hello(args):
"""Print a cliche to the console."""
if args.no_newline:
import sys
sys.stdout.write("Hello, World!")
else:
print "Hello, World!"
The @argument decorator accepts whatever
argparse.ArgumentParser.add_argument() does; consult the argparse docs
for more information.
You can also annotate commands by giving keyword arguments to @command:
@command(name="something", description="Does something.")
def do_something(args):
"""Do something."""
print "something has been done."
In this case, the command will be called "something" instead of the
auto-generated "do-something", and its description will differ from its
docstring. For more information on what can be passed in here, consult the
argparse.ArgumentParser docs.
The API is very similar without decorators. The Command class is used to wrap
functions, and you can give keyword arguments when invoking it as with
@command:
def echo(args):
...
echo = Command(echo, name='...', description='...')
Adding arguments uses the Command.add_argument() method, which is just a
reference to the generated sub-parser’s add_argument() method:
def echo(args):
...
echo = Command(echo, name='...', description='...')
echo.add_argument('-n', '--no-newline', ...)
echo.add_argument('words', nargs='*')
Commands are executed via the djboss command-line interface. For this to run
correctly, you need one of two things:
- A
DJANGO_SETTINGS_MODULEenvironment variable which refers to a valid, importable Python module. - A valid, importable
settingsmodule in the current working directory.
Once one of those is covered, you can run it:
$ djboss --help
usage: djboss [-h] [-v] [-l LEVEL] COMMAND ...
Run django-boss management commands.
optional arguments:
-h, --help show this help message and exit
-v, --version show program's version number and exit
-l LEVEL, --log-level LEVEL
Choose a log level from DEBUG, INFO, WARN (default)
or ERROR.
commands:
COMMAND
echo Echo the arguments back to the console.
hello Print a cliche to the console.
To discover sub-commands, djboss first finds and imports your Django settings.
The DJANGO_SETTINGS_MODULE environment variable takes precedence, but if
unspecified, djboss will look for a `settings` module in the current
directory. Commands should be defined in a `commands` submodule of each app.
djboss will search each of your INSTALLED_APPS for management commands.
Each subcommand gets a --help option too:
$ djboss echo --help
usage: djboss echo [-h] [-n] [words [words ...]]
Echo the arguments back to the console.
positional arguments:
words
optional arguments:
-h, --help show this help message and exit
-n, --no-newline Don't print a newline afterwards.
And then you can run it:
$ djboss echo some words here
some words here
More of the same:
$ djboss hello --help
usage: djboss hello [-h]
Print a cliche to the console.
optional arguments:
-h, --help show this help message and exit
And finally:
$ djboss hello
Hello, World!
This is free and unencumbered software released into the public domain.
Anyone is free to copy, modify, publish, use, compile, sell, or distribute this software, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means.
In jurisdictions that recognize copyright laws, the author or authors of this software dedicate any and all copyright interest in the software to the public domain. We make this dedication for the benefit of the public at large and to the detriment of our heirs and successors. We intend this dedication to be an overt act of relinquishment in perpetuity of all present and future rights to this software under copyright law.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
For more information, please refer to http://unlicense.org/