This question is related to the question Stop pydoc from running my Python program, except that here I'm not actually trying to document my own code - I'm just trying to use pydoc to look up unrelated documentation without any side-effects.
I have some experience with other programming languages, and I'm accustomed to being able to put scraps of code in files, and then to choose when that code gets executed. Sometimes I source the code fragments from other files, and sometimes I execute them from the command line. Sometimes I never execute a piece of code directly, but I keep it in a file where I can copy and paste it into other files or into an interpreter.
With Python, I assumed that I should put my Python code in files with suffix .py, but I ran into a snag. The pydoc tool sometimes executes all files named .py in PYTHONPATH, for example when I do a keyword search:
$ export PYTHONPATH=.
$ cat test.py
print("Hello world\n")
$ pydoc -k blah
Hello world
This makes Python unlike other programming languages I have encountered, in that even when using the standard tool-chain for the language (i.e. pydoc), I had difficulty predicting when pieces of code that I had stored in files on my file system would be executed.
I've read that a workaround is to put all my code in an if block like this:
if __name__ == "__main__":
However, that is cumbersome because not only does it add another line and another level of indentation to every file, but it prevents me from using import to run the code.
If I decide to do away with import and rather execute all my code with exec:
exec(open('filename').read())
then although I have to specify the full path to my code files, I can use a different file extension than .py, and then presumably pydoc will stop executing them. Is there a standard file extension to use for this purpose?
Incidentally, I was surprised that pydoc has this potentially disruptive behavior because it is one of the first tools that a beginner to the language could be expected to use. I would not expect someone to read the full documentation on the tool which displays documentation before using the tool which displays documentation. Even if they did, although it is mentioned in the "module reference" https://docs.python.org:0/3.9/library/pydoc.html, there appears to be no warning in the online documentation (pydoc -h or pydoc pydoc) that pydoc might execute all files named .py.
How do experienced Python users store Python code fragments? Is it preferred to use a different extension than .py, or to keep such code out of PYTHONPATH, or to avoid the use of pydoc; or is the if __name__ method really the most popular?