13.3 When to use Python methods

You always have a choice whether to code your methods as Cheetah #def methods or Python methods (the Python methods being located in a class your template inherits). So how do you choose?

Generally, if the method consists mostly of text and placeholders, use a Cheetah method (a #def method). That's why #def exists, to take the tedium out of writing those kinds of methods. And if you have a couple #if stanzas to #set some variables, followed by a #for loop, no big deal. But if your method consists mostly of directives and only a little text, you're better off writing it in Python. Especially be on the watch for extensive use of #set, #echo and #silent in a Cheetah method-it's a sure sign you're probably using the wrong language. Of course, though, you are free to do so if you wish.

Another thing that's harder to do in Cheetah is adjacent or nested multiline stanzas (all those directives with an accompanying #end directive). Python uses indentation to show the beginning and end of nested stanzas, but Cheetah can't do that because any indentation shows up in the output, which may not be desired. So unless all those extra spaces and tabs in the output are acceptable, you have to keep directives flush with the left margin or the preceding text.

The most difficult decisions come when you have conflicting goals. What if a method generates its output in parts (i.e., output concatenation), contains many searchList placeholders and lots of text, and requires lots of #if ...#set ...#else #set ...#end if stanzas. A Cheetah method would be more advantageous in some ways, but a Python method in others. You'll just have to choose, perhaps coding groups of methods all the same way. Or maybe you can split your method into two, one Cheetah and one Python, and have one method call the other. Usually this means the Cheetah method calling the Python method to calculate the needed values, then the Cheetah method produces the output. One snag you might run into though is that #set currently can set only one variable per statement, so if your Python method needs to return multiple values to your Cheetah method, you'll have to do it another way.