How and where does Python code start running? How can I control that?

• The supplied name needs to be a module path, the way it would look in an absolute import statement inside the code. Since we would import myscript.py (assuming everything else were set up properly) using something like import myscript (with no .py), that's how the command looks: python -m myscript (with no .py).

• This changes the rules for where Python looks for modules. If for example we had myscript.py inside of myfolder, then python -m myfolder.myscript tell Python that *the current directory (.) is a place that may contain modules and packages. But python myfolder/myscript.py will tell Python that the myfolder directory is a place that may contain modules and packages.

• Python will search for the named module, instead of following a specific file path. This is important because some standard library modules (and possibly some third-party packages) offer their own command-line interface, and can be run like scripts instead of just importing them from one's own code.

• Starting the code this way will also import packages for folders along the way: python -m myfolder.myscript will make myfolder a package (and run code in myfolder/__init__.py, if there is such a file). This also allows relative imports to work.

It's important to understand that from Python's perspective, running a script is not much different from importing a module. Either way, the code is run from top to bottom in the file. Any code that isn't indented happens immediately, in order. (Some code that is indented might still happen: for example, code inside an if block would run if the condition is satisfied.) This includes things like import statements, by the way: they aren't required to be at the top of the file (although this is usually a good idea), and they happen when Python encounters them, not automatically.

Keep in mind that this does not mean that functions are called: "running" the code in the question simply creates the function - it doesn't make the code inside the function run.

There are no "special" function names here. Python won't automatically call a function named main, or anything else - functions only run when they are called.

Many real-world scripts contain code along the lines of:

if __name__ == '__main__':
    sys.exit(main())

There are many variations of this technique, and the use of sys.exit is not important for us at the moment. The interesting idea here is the if block.

Sometimes people talk about this code 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). What actually happens here is that the code is "guarded", so that the main function is only called when the script is run as a script. When the code is simply imported from somewhere else, this code won't run.

Why?

This happens because of how the special variable __name__ works. A key idea here is that Python's "global" variables aren't global to an entire program, but only to a file or module. When Python imports a module, it runs the code in that file, using a separate lookup for its global variables; then those global variables become the attributes of the module (which is what lets us write things like mymodule.my_function after import mymodule).

Python also sets some special global variables, one of which is __name__. When the file was imported as a module, this will be set based on the file name (without the .py extension). But when the file is run as a script, __name__ gets the special value '__main__'. Therefore, we can simply test for this value in the if statement.

In this environment, Python scripts can be given a shebang line that tells the operating system that the file is a script, and what interpreter (i.e., Python) to use for it. Because # starts a comment in Python, Python itself doesn't need any special handling for this - it's just ignored anyway. Of course, the file also needs to be marked as executable (chmod +x).

Keep in mind that without a shebang, the operating system will typically try to treat the script as a shell script, which will fail completely (probably with many errors). The operating system doesn't care about a .py extension on the file name.

It's common to use something like #!/usr/bin/env python, to allow the operating system to find Python. But sometimes it's necessary to give the path to a specific Python to make the script work properly.

It's also common for such scripts to name the file without a .py extension (so just myscript), and to not use a if __name__ == '__main__: guard. That's because these tools are simply unnecessary if the script will only be used as a script and should not ever be imported from somewhere else.

Let's see how a complete example looks in a typical Linux shell.

How the script is named, and the permissions:

$ ls
myscript
$ stat -c '%A' myscript 
-rwxrwxr-x

What's in it:

$ cat myscript 
#!/usr/bin/env python

def my_function():
    print("Test")

my_function()

How we run it, and what happens:

$ ./myscript 
Test

Windows does not care about shebangs generally, and doesn't have a concept of executable text files. However, it does have a concept of file associations - so we can tell Windows to use Python (via a specific path to python, perhaps something like
C:\Program Files\Python 3.12\python.exe) to open any file with a .py file name extension when it's double-clicked.

But better yet, we can tell it to use the Python Launcher for Windows. There's only one of these even if you install multiple versions of Python, and it's in a single, consistent place -
C:\Windows\py.exe (assuming Python was installed "for all users"). More importantly, this py program tries to read and understand shebang lines - simply write the script as if it would run on a Mac or Linux system, and let py do the rest.