Python 模块导入与文档字符串消失问题详解

本文旨在解释 Python 中模块导入后文档字符串变为 None 的现象。我们将深入探讨 Python 的导入机制和 PEP 8 规范，分析为什么在导入语句后定义的文档字符串无法被正确识别，并提供避免此问题的最佳实践。

在 Python 中，文档字符串（docstring）是用于为模块、类、函数或方法提供文档说明的字符串。它通常位于定义的首行，用三个引号（"""Docstring goes here"""）包围。然而，在某些情况下，尤其是在模块导入后，我们可能会发现文档字符串变成了 None。这通常与 Python 的导入机制和 PEP 8 规范有关。

问题分析

考虑以下两种情况：

立即学习“Python免费学习笔记（深入）”；

情况一：没有导入语句

"""
This is a docstring.
"""

print(f'Doc=[{__doc__}]')

这段代码的输出为：

Doc=[
This is a docstring.
]

情况二：包含导入语句

import sys

"""
This is a docstring.
"""

print(f'Doc=[{__doc__}]')

这段代码的输出为：

Doc=[None]

为什么第二种情况下 __doc__ 变成了 None 呢？

原因解释：PEP 8 规范

文心大模型

百度飞桨-文心大模型 ERNIE 3.0 文本理解与创作

56

查看详情

关键在于 PEP 8 规范中关于导入语句位置的规定：

Imports are always put at the top of the file, just after any module comments and docstrings, and before module globals and constants.

这意味着导入语句应该放在文件的顶部，紧随模块注释和文档字符串之后。当导入语句出现在文档字符串之前时，Python 解释器会将文档字符串识别为普通字符串，而不是模块的文档字符串。因此，__doc__ 属性将不会被设置为该字符串。

最佳实践

为了确保文档字符串能够被正确识别，应遵循以下最佳实践：

1. 将导入语句放在文档字符串之后： 这是最直接的解决方案。确保所有的 import 语句都位于文档字符串的下方。

   """
   This is a docstring.
   """
   
   import sys
   
   print(f'Doc=[{__doc__}]') # 输出: Doc=[ This is a docstring. ]

   登录后复制

2. 模块级别的注释应该在文档字符串之前： 如果需要在模块顶部添加注释，请确保它们位于文档字符串之前。

   # This is a module-level comment.
   
   """
   This is a docstring.
   """
   
   import sys
   
   print(f'Doc=[{__doc__}]') # 输出: Doc=[ This is a docstring. ]

   登录后复制

总结

Python 的模块文档字符串行为受到 PEP 8 规范的影响。为了避免文档字符串变为 None 的问题，务必将 import 语句放置在文档字符串之后。 遵循这些简单的规则可以确保你的代码具有良好的可读性和可维护性，并允许开发人员轻松访问模块的文档。

以上就是Python 模块导入与文档字符串消失问题详解的详细内容，更多请关注php中文网其它相关文章！