“Boilerplate” code in Python?

Question

Google has a Python tutorial, and they describe boilerplate code as "unfortunate" and provide this example:

#!/usr/bin/python

# import modules used here -- sys is a very standard one
import sys

# Gather our code in a main() function
def main():
  print 'Hello there', sys.argv[1]
  # Command line args are in sys.argv[1], sys.argv[2] ..
  # sys.argv[0] is the script name itself and can be ignored

# Standard boilerplate to call the main() function to begin
# the program.
if __name__ == '__main__':
  main()

Now, I've heard boilerplate code being described as "seemingly repetitive code that shows up again and again in order to get some result that seems like it ought to be much simpler" (example).

Anyways, in Python, the part considered "boilerplate" code of the example above was:

if __name__ == '__main__':
  main()

Now, my questions are as follows:

1) Does boilerplate code in Python (like the example provided) take on the same definition as the definition I provided? If so, why?

2) Is this code even necessary? It seems to me like the code runs whether or not there's a main method. What makes using this code better? Is it even better?

3) Why do we use that code and what service does it provide?

4) Does this occur throughout Python? Are there other examples of "boilerplate code"?

Oh, and just an off topic question: do you need to import sys to use command line arguments in Python? How does it handle such arguments if its not there?

Answer 1

1. It is repetitive in the sense that it's repeated for each script that you might execute from the command line.
2. If you put your main code in a function like this, you can import the module without executing it. This is sometimes useful. It also keeps things organized a bit more.
3. Same as #2 as far as I can tell
4. Python is generally pretty good at avoiding boilerplate. It's flexible enough that in most situations you can write code to produce the boilerplate rather then writing boilerplate code.

Off topic question:

If you don't write code to check the arguments, they are ignored.

Answer 2

The reason that the if __name__ == "__main__": block is called boilerplate in this case is that it replicates a functionality that is automatic in many other languages. In Java or C++, among many others, when you run your code it will look for a main() method and run it, and even complain if it's not there. Python runs whatever code is in your file, so you need to tell it to run the main() method; a simple alternative would be to make running the main() method the default functionality.

So, if __name__ == "__main__": is a common pattern that could be shorter. There's no reason you couldn't do something different, like:

if __name__ == "__main__":
  print "Hello, Stack Overflow!"

  for i in range(3):
    print i

  exit(0)

This will work just fine; although my example is a little silly, you can see that you can put whatever you like there. The Python designers chose this behavior over automatically running the main() method (which may well not exist), presumably because Python is a "scripting" language; so you can write some commands directly into a file, run it, and your commands execute. I personally prefer it the Python way because it makes starting up in Python easier for beginners, and it's always nice to have a language where Hello World is one line.

Answer 3

The reason you use an "if main" check is so you can have a module that runs some part of its code at toplevel (to create the things – constants, functions, or classes – it exports), and some part only when executed as a script (e.g. unit tests for its functionality).

The reason the latter code should be wrapped in a function is because local variables of the main() block would leak into the module's scope.

Now, an alternate design could be that a file executed as a script would have to declare a function named, say, __main__(), but that would mean adding a new magic function name to the language, while the __name__ mechanism is already there. (And couldn't be removed, because every module has to have a __name__, and a module executed as a script has to have a "special" name because of how module names are assigned.) Introducing two mechanisms to do the same thing just to get rid of two lines of boilerplate – and usually two lines of boilerplate per application – just doesn't seem worth it.

Answer 4

You don't need to add a if __name__ == '__main__' for one off scripts that aren't intended to be a part of a larger project. See here for a great explanation. You only need it if you want to run the file by itself AND include it as a module along with other python files.

If you just want to run one file, you can have zero boilerplate:

print 1

and run it with $ python your_file.py

Adding the shebang line #!/usr/bin/python and running chmod +x print_one.py gets you the ability to run with

./print_one.py

Finally, # coding: utf-8 allows you to add unicode to your file if you want to put ❤'s all over the place.

Answer 5

1) main boilerplate is common, but cannot be any simpler

2) main() is not called without the boilerplate

3) the boilerplate allows module usage both as a standalone script, and as a library in other programs

4) it’s very common. doctest is another one.

Train to become a Python guru…and good luck with the thesis! ;-)

Answer 6

Let’s take a moment to see what happened when you called import sys:

• Python looks at a list and brings in the sys module
• It finds the argv function and runs it

So, what’s happening here?

A function written elsewhere is being used to perform certain operations within the scope of the current program. Programming in this fashion has a lots of benefits. It separates the logic from actual labour.

Now, as far as the boilerplate is concerned, there are two parts:

• the program itself (the logic), defined under main, and
• the call part that checks if main exists

You essentially write your program under main, using all the functions you defined just before defining main (or elsewhere), and let Python look for main.