In the IRC channel tonight there was some discussion (mostly motivated
by ticket #1204) about template tags and filters failing silently,
particularly those in the markup app. Since it was kind of late and
people were popping in and out it sputtered, but I think it's an
interesting topic to bring up.
The Django docs say that template filters should always fail silently
and never raise exceptions; they should instead return either the
original input or an empty string, as appropriate. And when writing
template tags, the tag's render() method should fail silently as well.
The question is whether this is always helpful; in the case of the
markup filters, a couple of arguments were brought up:
1. There's really no documentation on the markup app outside of its
code, so someone who installs it without reading the code might not
realize that the appropriate markup libraries need to be installed and
present or else the filters won't do anything.
2. Even though the convention of filters and tags failing silently is
mentioned in the template documentation, users who won't be writing
custom tags or filters might not read that.
3. This is contrary to how, for example, the admin documentation
browser behaves; if you don't have docutils, it will give you a
helpful error message to that effect.
There are, of course, a couple of good responses to these points:
1. You shouldn't install an app without looking to see what it does,
either in its online documentation if that exists, or by looking at
the code if it doesn't.
2. It's always a good idea to read all the docs, even the bits you
might not think are relevant to what you're doing, just so you know
how the framework will behave.
3. The admin documentation browser is a significantly different use
case from the markup filters, because it doesn't use docutils in the
templates; instead it does the necessary text processing in the view
code, which also means that a missing docutils can be easily noticed
and handled cleanly.
Personally, I think failing silently is the right option for filters
and tags and so I agree with this convention; it's too difficult to
try to figure out on a case-by-case basis how a filter or tag should
fail and what output should be displayed to the end user, and even
more of a nightmare for someone using the framework to keep track of
all the different possibilities. And, of course, bending the rules for
a single special case like the markup filters would probably be
un-Pythonic.
But as it stands, the template docs provide no particular rationale;
they just tell you to fail silently. And there's no mention of this
anywhere else in the docs, which could lead to problems for users who
are just starting to explore Django. So what's the official line on
why template tags/filters fail silently? And where would be a good,
obvious place to point it out so it's not a "gotcha" for beginning
Django users?
--
"May the forces of evil become confused on the way to your house."
-- George Carlin
