Empty Thoughts

Since I published my introductory post on the project, I have not posted any additional updates regarding the project. Quietly, there’s been tons of work happening, and so I thought I would give some visibility to all of the great contributions to the effort.

As a review, the django-command-extensions project is a repository for collecting global custom management extensions for the Django Framework.

Since the project was started there has been an additional twelve commands added. The bulk of the work has been headed up by Ido Sebastiaan van Oostveen, with some additional work by Doug Napoleone and Ludvig Ericson. Personally, I haven’t had much involvement in the development beyond a few initial commands. Although, I have been a satisfied customer of the extensions, such that it has become a staple for all of my Django projects.

So on to the fun stuff. Here’s a list of commands in the project:

• create_app – creates an application directory structure for the specified app name. This command allows you to specify the --template option where you can indicate a template directory structure to use as your default.

• create_command – creates a command extension directory structure within the specified application. This makes it easy to get started with adding a command extension to your application.

• create_jobs – Creates a Django jobs command directory structure for the given app name in the current directory. This is part of the impressive jobs system.

• create_superuser – makes it easy to create a superuser for the django.contrib.auth.

• describe_form – used to display a form definition for a model. Copy and paste the contents into your forms.py and you’re ready to go.

• – export the email addresses for your users in one of many formats. Currently supports Address, Google, Outlook, LinkedIn, and VCard formats. I have found this really handy.

• generate_secret_key – creates a new secret key that you can put in your settings.py module.

• – creates a GraphViz dot file. You need to send this output to a file yourself. Great for graphing your models. Pass multiple application names to combine all the models into a single dot file. This one is very useful with lots of options for flexibility. See the wiki page for detailed information.

• passwd – makes it easy to reset a user’s password

• run_job – run a single maintenance job. Part of the jobs system.

• run_jobs – runs scheduled maintenance jobs. Specify hourly, daily, weekly, monthly. Part of the jobs system.

• runprofileserver – starts runserver with hotshot/profiling tools enabled. I haven’t had a chance to check this one out, but it looks really cool.

• shell_plus – An enhanced version of the Django shell. It will autoload all your models making it easy to work with the ORM right away. I use this every day. It is so handy.

• show_urls – displays the url routes that are defined in your project. Very crude at this point.

• sqldiff – prints the (approximated) difference between an apps models and what is in the database. This is very nice, but also very experimental at the moment. It can not catch everything but it’s a great sanity check.

On the documentation front, Ido has been actively putting together some and usage instructions to help people get started. We still have quite a few undocumented commands so if you would like to pitch in, we appreciate your help.

If you like using Mercurial, Ido maintains a Mercurial repository for the project. You can find more information on using his repository on the .

I would like to thank Ido Sebastiaan van Oostveen for his help. He’s really taken a leadership role and contributed a lot of great stuff. Additionally he’s been fleshing out the documentation and managing the tickets / patches.

Finally, if you would like to get involved in the project, we’re always looking for people to help out. Feel free to . If you would like to contribute directly, please let me know.

Lately I have been thinking a lot about how well Django adapts to new users. I noticed that there seems to be an influx of first-timers. Although these programmers come from a variety of backgrounds, there are some areas within the framework that consistently cause stumbling blocks. In a lot of ways it is part of the reason that I’ve devoted a segment of This Week in Django to the subject. So what can be done to make Django more new user-friendly?

Convention Over Configuration

The idea of convention over configuration was really brought home with the Ruby on Rails framework. At almost every opportunity Ruby on Rails provides a default convention. David Heinemeier Hansson, the creator of Rails, calls it “Opinionated Software.” It definitely is opinionated. So much so that in some cases it is the reason why people do not embrace the framework. I’m not suggesting that Django does “convention over configuration” to the same extreme that Ruby on Rails does, but there are things that can be learned from Rails.

Sensible Settings

So what sort of things am I talking about? First, as an example, the ADMIN_MEDIA_PREFIX should default to something other than /media/. Most new developers to Django want to put their media at, well media. And as a result they end up having trouble serving up the Admin’s media files. So you say, there’s nothing stopping them from changing one or the other. Sure they can change the defaults, but that is not going to be their first response. Instead they are going to spend a lot of time trying to figure out why it does not work. So if the ADMIN_MEDIA_PREFIX was something like /adminmedia/ by default this would cause a lot less confusion.

“The whole global_settings.py is about defaults!” you say. So am I being nit-picky? Sure I am. I want Django to be the best damn framework on the planet. Plus, this post is not about ADMIN_MEDIA_PREFIX, it is really about making Django more palatable to new users. A good exercise would be to go through all the default settings and really think about them from the standpoint of a new user. For instance, should the TIME_ZONE information be pulled from the system environment? In some cases, perhaps we just need better documentation. In other words there’s not a sensible default, but perhaps we could clear up areas of confusion around the differing possibilities.

A Place for Everything

The other area where Django could could use some more convention is in “where things go”. The most often asked question about NewForms has nothing to do with using NewForms or making NewForms work. The most often asked question is “Where should I put my form class?” Yes, for those of you familiar with Python and Django this seems ridiculous. You say, “It’s a python module, put it wherever you want!” And you’re right, but a lot of “newbies” to Django are “newbies” to Python. They are coming to Python through Django. In fact that the case for myself. Yet, none of these “newbies” are asking “Where do I put my views?”

So given the audience, “convention over configuration” makes a lot of sense and saves a lot of repeated questions around the same types of issues. Someone who is new to the framework doesn’t really have an opinion about what is best, but they generally want someone to tell them “this is the way to do it.” Therein lies the confusion.

So how can we accomplish that? I can think of two solutions.

First we can provide more templates when the startapp management command is used. This would work much in the same way as the views.py module template is provide. A blank module with some comments and perhaps an import or two.

So the positives of this approach are that it would answer the question. There would be a “place for everything and everything is in its place.” But the negatives are that, well “everything would be in its place.” So where does it stop? Do we provide a managers.py, feeds.py, and signals.py templates? I think Ruby on Rails overdoes it with all the structure and files. You end up with the opposite problem of not knowing where anything is—not sure if you’re using the right bucket for the right purpose. So there’s got to be a balance somewhere.

The second solution is to provide more generators, management commands, to create these things on an as needed basis. I like this approach much better because it makes it real easy to ask the framework “I need a form. Please create one for me.” As you get more experienced with the framework, and develop your own “best practices,” you may or may not continue to use the generators, but at least they are out of the way and available if you want them.

If these management commands were to take a note or two out of the play book of Ruby on Rails, they could end up being quite convenient. For instance, there could be a management command that looks like:

./manage.py create form appname FormClassName

This could generate the forms.py module in the appname specified, where it has the FormClassName defined with all the correct imports. Likewise, we could have something like:

./manage.py create modelform appname ModelName

This would generate the forms.py module in the appname specified, with the ModelForm class defined and the inner meta for the model defined.

What Do You Think?

Clearly this is not going to be everyone’s “cup of tea,” but the great thing about this approach is that you don’t have to use it.

So, do you agree or disagree? Do you have other ideas about this “problem”, or do you think there is no “problem” to be solved in the first place? I look forward to hearing your thoughts, questions, criticisms.

If you have global custom management command extensions or if you have suggestions for some that would be useful to you in your daily work with Django, . Yesterday I posted a new project on , called , that will hopefully grow into a nice repository of custom management command extensions. Currently I’ve included the following three commands:

• describe_form – Writes out a newforms definition to the console for the specified model

• create_command – Generates a custom management command directory structure in the application specified, which makes it easy to get started creating your own commands.

• generate_secret_key – Generates and displays a new secret key that can be used in your settings.py module.

There’s no documentation at the moment but that will come shortly. The application should be installed on your python path like all Django applications. Your Django framework must be at least updated to Changeset 6047.

Join In

Here’s a couple ways you can help out:

• Become a Committer – If you’d like to contribute to the code please let me know and I’ll add you.

• Test – Use the commands on various operating systems, different environments. .

• Make Suggestions – If you have ideas about how we can expand the functionality of current command extensions or if you have a suggestion for a new command extension, .

• Documentation – Like to write documentation? Okay, but would you be willing to? Let me know.

If you need help getting started in creating your own custom management commands please check out the screencast I did on the subject.

The code is licensed under the MIT license.

I had a need to generate a new secret key for a Django project that I’m working on. Often when I start a new project I’ll just copy an existing project template that I have which has all the bits and pieces in the right places. This helps me to get going quickly without a lot of fuss. Although when doing so I always need a new SECRET_KEY for the settings file. Instead of doing it manually this time, I decided to create a new custom management command and make it part of my global . For doing this I just inherited from the NoArgsCommand and extracted the logic for creating the secret key from the startproject command in the Django source.

from random import choice
from django.core.management.base import NoArgsCommand

class Command(NoArgsCommand):
    help = "Generates a new SECRET_KEY that can be used in a project settings file." 

    requires_model_validation = False
    can_import_settings = True

    def handle_noargs(self, **options):
        return ''.join([choice('abcdefghijklmnopqrstuvwxyz0123456789!@#$%^&*(-_=+)') for i in range(50)])

While creating the most recent Django Screencast on Custom Management Commands, I had it in my show notes to mention how you can call Django’s management commands from an external script. There’s probably several different ways to accomplish this, but the simplest and “baked in” way to do this is through the use of the call_command function. This function is part of django.core.management.

For example, if we wanted to call sqlall from the shell we could do something like the following:

>>> from django.core.management import call_command
>>> call_command('sqlall', 'delinkuent')

The call_command function’s signature looks like:

call_command(name, *args, **options)

It accepts the name of the command we’re executing, any required arguments, and options to the command. If we have a command with an argument and options it might look like the following:

>>> call_command('say_hello_name', 'michael', capitalize=True)
Hello Michael

This approach works fine with any custom management commands you may have created as well.

There is a caveat to this approach. You must be sure that you’ve properly set up your DJANGO_SETTINGS_MODULE environment variable. For more information about this see James Bennett’s excellent writeup on the subject.

I mentioned in the Django Screencast that I would be putting together a cheatsheet on Django’s custom management commands, so here it is. I hope you find it useful.

In this screencast I cover adding custom management commands into your Django applications. Custom management commands are a method of extending Django’s built-in commands that are made available through the manage.py or django-admin.py scripts.

Source code for the screencast is provided below. Please be sure to read the README file included in the download.

Downloads

Regular (64.2 MB, 41:09, H.264, MP4)

IPod (26.6MB, 41:09, H.264, MP4)

Source Code (124 KB)

Requires the latest version of QuickTime, VLC Media Player, or comparable software capable of playing MP4 container format and the H.264 codec.

Show Notes

• Custom Management Commands Cheatsheet

• Django Documentation on Custom Management Commands

• Optparse Python Library

• Registering Custom Commands with Manage.py

• NewForms Generator

P.S. I apologize for the delay in getting this screencast put together. Between Leopard upgrades and health issues time got away from me.

Update

My server was getting hammered with downloads and was unavailable for a while this morning. I’ve moved the downloads to S3 to try to offload some of the impact. Hopefully this will correct the issue. If you experience problems downloading the screencast, please email me.