Django tips: documentation and resources
Django’s official documentation often draws praise for being well above average for an open-source project, but it’s far from being the only source of useful information for a developer using the framework. Also, articles and tutorials specific to Django aren’t the only useful documentation out there; the Python language in general tends to have tons of great resources. So let’s take a look at some resources you might not know about but should.
Python in general
For someone who’s new to programming in general, or for a programmer who’s new to Python, the official tutorial is quite good, but I personally don’t think there’s any better introduction to the language than Mark Pilgrim’s “Dive Into Python”, which is available for free online. However, the dead-tree edition can be quite nice to cuddle up with, and now it even earns Mark royalties.
The Python standard library is generally applauded for including tons of useful things, and is quite well-documented; if you find yourself wondering, “how would I do this in Python?”, odds are there’s a standard module which can help you out (real live example: tonight in IRC someone’s problem was partially solved by looking at the socket module).
For unofficial documentation and generally useful tips, ActiveState’s Python Cookbook can be pretty hard to beat — if you’ve got a problem the standard modules can’t entirely solve, do a search in the cookbook and you’ll probably find someone else who’s worked through it and posted their code.
And, finally, keep in mind that Python makes it easy for code to document itself, and actively encourages doing so; there’s even a andy trick for viewing that documentation directly. Pop open a Python interpreter, import a module you want to know more about, and type help(modulename) — you’ll get a nicely-formatted listing of all the classes and functions in the module, along with any documentation they include. You can narrow this down if you like, to read only the documentation on a specific class or function. For example, if you wanted to poke around in md5, Python’s module for creating and using MD5 hashes, you could do this:
>>> import md5 >>> help(md5) ... full documentation of the module will appear ... >>> help(md5.new) ... this just gets the documentation of the 'md5.new' function ...
I use that all the time; it works on anything that has a docstring and it’s indispensible.
Django resources
The help function also lets you explore Django — most of the code has documentation included, and some of that goes into more detail than the official online docs. Often that’s because the extra information in the docstrings is really only useful for people who want to hack on Django instead of hacking with Django, but every now and again you’ll find a useful nugget in there.
Django also makes its documentation — and then some — available through the admin app. In the upper right of each page should be a link labeled “Documentation”, and if you click it (and if your server has the docutils module installed) you’ll see an index of what’s available. Django generates the following documentation automatically:
- A list of all available template tags, grouped by module. Any template tag with a docstring will have its docstring displayed here.
- A list of all available template filters, again grouped by module and including any docstrings.
-
A list of all installed models, grouped by application. For each model you’ll see a list of all its fields and methods, along with short descriptions of them if available (for fields, this is the
help_textattribute; for methods, it’s the docstring). - A list of all the views that are actually in use, generated by inspecting your site’s URL configuration. Views are listed by the URLs they correspond to, and the detail page for each view includes its docstring if available.
Django also comes with a wide assortment of documentation, not all of which appears in the online documentation index — usually because it covers something that’s under development, and needs to change with the code. Look in the docs directory of your Django download, or in the online code repository, to browse through these files.
The Django wiki has an assortment of contributed documentation, tips and examples, but should be taken with a grain of salt — there are a lot of pages there which list code samples based on older versions of Django, and they may not work now. Also, occasionally wiki pages pop up with information on topics related to Django’s development, but they tend to get out-of-date extremely quickly; if you’re looking for information on where Django is going, the best place to check is always the archive of the django-developers mailing list.
Similarly, subscribing to the Django community aggregator can be a good way to catch useful things as they’re posted; anyone who writes about Django is free to submit their feed for inclusion in the aggregator (though not everyone who’s aggregated their uses a categorized feed, so you will see some completely non-Django-related posts go by).
The “django” tags on del.icio.us and on ma.gnolia are also good sources of Django-related information, and both of them are available as feeds. There’s also a “planet Django” which tries to aggregate sites that write about Django, and at least one roundup of Django tutorials and tips floating around.
What did I miss?
I know there are more places out there to get solid, useful info on Python and Django, so leave a comment and tell me about them.
Feed of latest entries
September 4, 2006
#
You used a brace instead of a square bracket when you linked to ‘Dive Into Python’.
Other than that, pretty neat list of resources, thanks!
September 4, 2006
#
http://rgruet.free.fr/PQR24/PQR2.4.html
is superb for all the standard stuff… just found out about it a while ago. It obviously only documents the standard things, but it’s a great quick reference.
September 4, 2006
#
For newcomers to Python, How to Think Like a Computer Scientist: Learning with Python can be valuable too.
For newcomers to both, it’s a important to get a handle on Python first. That may sound obvious, but I’ve seen a lot of people on #django who describe themselves as “new to Python and Django,” and often they think they have Django questions when they really have Python questions. Django leverages a lot of the strengths of Python and presumes you’re familiar with them.
September 5, 2006
#
You’re right, Paul.
As one of those people “new to Python and Django”, if there was one thing I’d do differently before diving into Django, it would be diving into Python.
While both the docs and the Django community are extremely helpful to people like me, they DO presume you have a clue, which may not always be the case, as I’ve proven time and time again, and will probably continue to for at least awhile.
That said, it CAN be done.
September 9, 2006
#
Hey James, if you use help() all day you’ll love Ipython, which is located at http://ipython.scipy.org/ — can’t believe you don’t know it already.
Ipython is the advanced interactive python-interpreter. Most outstanding (at least for me) over the standard interactive python-interpreter are tab-completion and using “foo?” instead of “help(foo)” for object introspection. But there are many many more features you’ll probably find even more impressive than that, so go to it’s page and scroll down to the list of “main features” for more information.
Additionally (and that’s why I’m wondering you don’t know it already or at least didn’t mention it) Django’s “./manage.py shell” checks if ipython is installed and starts it in favor of the normal interactive interpreter.
My personal theses about Ipython is, that nobody who tried it at least once, ever wants to use the standard interactive-interpreter again if Ipython is available to them. (And that theses proved correct to this day. g)
P.S.: As I’m a foreign speaker it ocassionally happens that I make mistakes, so don’t mind to mention those, as it’ll help me to get rid of them in the future. :)
September 9, 2006
#
Actually, I’ve used ipython off and on, but it’s never really “clicked” for me. Kind of like Quicksilver in that regard; people who’ve used it tell me how much more productive it makes them, but I’ve just never really gotten into it.