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.

00:24 Feel free to put your code into the global namespace without nesting it in an if __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.

00:55 Another scenario when you might want to think twice about using the name-main idiom is if you were to write tests for your module in the same file.

01:05 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.

01:26 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.

01:51 And to just show that it works like before, you can run python but this time repeat.py instead of test.py, and it will run that test.

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.

02:30 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.

03:09 Another use case you may want to avoid is if you wanted to use the name-main idiom to demonstrate how someone could use your module.

03:18 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.

03:42 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.

04:05 Now that demonstration is a little lacking because the output doesn’t actually show what’s being called. So you could do that and add it in like so.

04:19 Here, you’ve got a print() line that’s showing, Hey, this is an example call, and then shows the code that’s actually being called and has a little bit of formatting so that it looks nice.

04:33 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.

04:56 Your if __name__ == "__main__" block is going to get pretty big and cumbersome, and the demonstrations are going to be in separate locations than the definition of the function.

05:08 So to add a docstring to this function, you would just add triple quotes (""") underneath the function definition. And just as an example, you could copy and paste this

05:26 and actually have that printed out in the docstring, and then you could remove the name-main idiom completely.

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.

06:05 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.

06:26 This would also work if you just imported the function. It would show you the docstring there. And then just press Q to exit out of that help manual.

06:39 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.

06:57 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.

07:12 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.

08:32 Now you have a better idea about when you should be using the name-main idiom. In the next lesson, you’ll learn some tips about how to use it in your scripts.