Post History

Whenever Python loads code from a `.py` file, that code gets its own [namespace](https://software.codidact.com/posts/290337) for global variables - so they're not truly global, but per-file values. (When you look at an `import`ed module "from outside", those global variables are the *attributes of* the `module` object. Thus, when `module.py` has `value = 1` at top level, code which does `import module` can then see `module.value`.)

Python also pre-defines a few of these names. In particular, it sets `__name__`. When the file was `import`ed, the value for `__name__` will be the module name. But when the file is run as a script, `__name__` is set to the special value `'__main__'`.

Therefore, we can simply write an `if` statement that checks for this value, to know whether the file was `import`ed or not. This allows the file to do specific things only when it's used as a script. For example, older standard library modules used this to contain ad-hoc testing code - you could run a module using `python -m` to see the test results, but `import`ing the module would skip running the tests.

<section class="notice is-warning">

Sometimes people talk about this idiom as if it defined an "entry point" for the script. But this is not accurate. **The code still runs from the top to the bottom** (defining global variables and classes and functions along the way). However, wrapping up the code this way (especially if it's organized using a `main` function) is Pythonic: it clearly signals intent to the reader (this code may be run directly) and keeps things neatly organized.
</section>

<section class="notice is-warning">

There are a few more interesting situations that can arise due to how this system works. (Credit to [Mr Fooz' answer on Stack Overflow](https://stackoverflow.com/a/419185/523612) for pointing these out. The explanation given here is my own.)

Note that this allows code in the "main" script to `import` itself once - the module cache will contain two separate modules created from the same code: one named `__main__`, and one named according to the file. This can somewhat complicate debugging if you have an issue caused by a circular import.

Also, notice that because of how Python handles command-line arguments, you *cannot* detect whether the code is being `import`ed this way. Further, command-line arguments that make sense for one script may not make sense for another, so letting the "script" code run on import can cause serious problems besides just wasting time.

Imports can also happen in somewhat unexpected circumstances. For example, if `imported.py` defines a class, and `importer.py` tries to unpickle an instance of that class, that will trigger an import of `imported.py`. For this reason, some people prefer to include this sort of "guard" even when the file is only ever *intended* to be used as a script.
</section>