Clarify expectation around template filters and exceptions
|Reported by:||Carl Meyer||Owned by:||nobody|
|Cc:||Triage Stage:||Ready for checkin|
|Has patch:||no||Needs documentation:||no|
|Needs tests:||no||Patch needs improvement:||no|
In the custom template filters documentation, we say "Filter functions should always return something. They shouldn’t raise exceptions. They should fail silently. In case of error, they should return either the original input or an empty string – whichever makes more sense."
Then we immediately proceed to show (with approval, not as a counter-example) a template filter which fails to implement this recommendation. (If passed anything without a
replace method, it will fail loudly.)
If we really mean to say that template filters should never raise exceptions, then a) we should provide a utility decorator that helps to implement that recommendation (something like sorl-thumbnail's safe_filter), and we should use it in all of our example filters.
Personally I think this is a bad recommendation and we should change it. Template filters, like any other code, should catch errors that they can reasonably expect and handle with a fallback value, but a blanket catching of all exceptions is just as bad in template filters as in any other code (because it is likely to hide bugs).