Thank you for this lucid account of the situation, Terry.

As for where in the documentation something additional could be said about .pyo files and the -O option, I must say that it is already mentioned in some relevant places (http://docs.python.org/tutorial/modules.html#compiled-python-files),

However, I can see one other place where some additional information would be useful: in the documentation for the -O option itself (http://docs.python.org/using/cmdline.html#miscellaneous-options). The current documentation only mentions the .pyo-producing effect of -O. Mentioning there that -O is *required* for interpreting .pyo files would be useful.

Thanks!