When Should You Not Use the Name-Main Idiom?
00:00 In the previous lesson, you saw when it’s recommended to use the name-main idiom. And in this lesson, you’ll see examples of when you may want to use the name-main idiom, but when other solutions may be more appropriate.
00:14 The first scenario is when you’re writing pure scripts. If you don’t plan on importing your script as a module, and you’re not writing tests for it, you don’t need to use the name-main idiom at all.
Feel free to put your code into the global namespace without nesting it in an
__name__ == "__main__" block. That being said, if you’re using a tool that provides extra functionality when you use it, feel free to use the name-main idiom. It doesn’t hurt. For example, the PyCharm code editor adds a little run button beside any instance of the name main idiom that it sees because it’s an indication that you do intend to run the file as a script at some point.
If you watched the previous lesson, I showed you an example of how to write tests for your script in a separate
test.py file. But if you are not using your script as a command-line entry point, and you just need it for module functionality, you might be tempted to write your tests in the same file as your module.
Then when you run that script, it’ll run the tests instead of asking for user input like before. Here’s an example of
repeat.py where the unit test is written in the same file, and in the name-main idiom, you’re actually calling
unittest.main() to run the suite of tests.
02:03 This is not as recommended because mixing your test code with your module code is not a best practice. It’s best to put them in separate test files. So this works if you’ve got a small personal project, and you just need to write a really quick test to verify that your function is working correctly, such as if you’re doing a coding challenge for an interview.
But the larger your project grows, and if you’re going to be sharing it with other people and actually using this module in a useful way, having tests in the same place both makes the code harder to read and understand, and it allows other people to import your tests when they really just want to import the functions and classes that are defined here. So in this case, even if you’re not using the
repeat.py file as a command-line entry point, it’s best to separate the test out into a separate file.
Looking back at
repeat.py again, if you want to use it just as a module, then just have the
repeat() function defined. And then inside of the name-main idiom, you could have it printing out the results of calling the
repeat() function on some text, like
"Hello", with some number of repetitions, like three.
Then if you were to call
repeat.py as a script, it would print out
Hello three times. So that’s great if it’s just a little demo and it’s a personal project that only one person is working on and it’s small, but say you wanted to provide this module for someone else to use.
And then when you call
repeat.py as a script again, now you have a nicely formatted demonstration, but here the alternative actually is to provide just proper documentation for your module instead, because imagine that you have more than this function, and you wanted to show that as well.
05:40 Of course, the docstring I’m providing here is just a minimal example, and if you want to learn more about docstrings, you can look at the additional resources provided at the end of this course.
05:50 There are many benefits of using docstrings for your demonstrations. For one, your demo is now located in the same location as the code, and it doesn’t have to be run to see the output. You just have to read it.
You can also make use of Python’s built-in features, like the
help() function. So, if you go into the Python console, you can import the
repeat module so you have access to it, and then call the
help() function on
repeat, and it provides you documentation about the module.
You could also use the
doctest module so that your docstrings can double as tests, essentially feeding two birds with one scone. A tutorial for using the
doctest module is also provided in the additional resources at the end of the course.
And finally, if you’re building larger command-line applications, it’s best to use a separate file as your dedicated entry point, like a
main.py file. In
main.py, you can handle user input without nesting it in the name-main idiom.
And then any functions you use, like
repeat(), can be imported in. Note that for parsing more complex command-line inputs, you can also use the built-in
argparse module or any number of external modules for building command-line programs.
07:28 And just like with the examples before, I’ll provide you some resources about building command-line interfaces at the end of this course. So, to summarize when you may want to use the name-main idiom but when a different approach may be better: when you’re writing pure scripts, you can use the name-main idiom, but you don’t have to.
07:48 Especially if your code is going to be read by beginner programmers, it may just confuse or overwhelm someone reading it. And if you’re tempted to include tests for your module in the same script, consider moving the test to a separate location.
08:03 And if you’re trying to provide demonstrations about how your module should work, consider putting those demonstrations in docstrings instead and providing full documentation for your project. And finally, when you’re creating a complex command-line interface, create a dedicated module for it and a separate file that acts as your interface, and then you can import everything in from your module.
Become a Member to join the conversation.