如何避免Pydoc执行Python代码片段？资深用户存储方案探讨

核心问题回顾 #

习惯将代码片段存入文件、自主选择执行时机，但使用Python时，存为.py文件会被PYTHONPATH下的pydoc执行（比如运行pydoc -k blah时，会触发test.py里的print代码），想实现无副作用使用pydoc，同时询问：

• 是否有标准的非.py扩展名用于这类代码片段？
• 资深Python用户存储代码片段的主流方式是什么？

非.py代码片段的扩展名说明 #

没有Python官方指定的标准扩展名用于这类仅需手动执行的代码片段。你可以自行选择易识别的扩展名，比如.pysnippet、.pys等——只要不是.py，pydoc就不会将其当作Python模块扫描执行。如果需要编辑器语法高亮，大部分主流编辑器都支持自定义扩展名关联Python语法。

资深用户的主流解决方案 #

• 用if __name__ == "__main__":包裹执行代码：这是Python社区的标准实践，完全不繁琐，也不会影响import行为。当你import该文件时，__name__不等于__main__，包裹的代码不会执行；只有直接运行该文件时，这部分代码才会触发。这是最符合Python规范的方式，也是推荐度最高的。
• 将代码片段移出PYTHONPATH：把临时代码片段放在PYTHONPATH之外的目录，pydoc不会扫描到这些文件。需要执行时，直接通过文件路径运行，或者用exec(open('文件路径').read())执行。适合不需要被import的临时小片段。
• 使用自定义扩展名：如前面所说，给代码片段换个非.py的扩展名，避免被pydoc识别为模块。需要执行时用exec读取运行即可。
• 替换pydoc为其他工具：如果频繁遇到这个问题，可以改用交互式环境里的help()函数查询文档，或者用第三方工具如pdoc——这类工具的扫描逻辑更谨慎，不会触发模块顶层代码的执行（除非必要）。

关于pydoc的执行行为 #

pydoc是通过import模块来生成文档的，而Python的模块导入机制本身就会执行模块的顶层代码，这是pydoc的工作原理，属于预期行为，所以没有额外警告。

内容的提问来源于stack exchange，提问作者Metamorphic