Python学习--__doc__ 属性详解

# 查看内置模块的文档import mathprint(math.__doc__)# 查看当前模块的文档print(__doc__)  # 当前模块的文档# 自定义模块的文档# mymodule.py"""这是一个自定义模块用于演示文档字符串"""# 导入后查看# import mymodule# print(mymodule.__doc__)

def add(a, b):    """    计算两个数的和    参数:        a: 第一个数字        b: 第二个数字    返回:        两个数的和    """    return a + b# 查看函数文档print(add.__doc__)# 查看内置函数文档print(print.__doc__)print(len.__doc__)

class Person:    """    人员类    属性:        name: 姓名        age: 年龄    方法:        greet(): 问候方法    """    def __init__(self, name, age):        """初始化Person对象"""        self.name = name        self.age = age    def greet(self):        """返回问候语"""        return f"Hello, I'm {self.name}"# 查看类的文档print(Person.__doc__)# 查看方法的文档print(Person.__init__.__doc__)print(Person.greet.__doc__)

def calculate_average(numbers):    """计算数字列表的平均值"""    return sum(numbers) / len(numbers)# 使用 help 查看# help(calculate_average)  # 交互式帮助# 编程方式获取帮助文本import sysfrom io import StringIOdef get_help_text(obj):    """获取对象的帮助文本"""    old_stdout = sys.stdout    sys.stdout = StringIO()    help(obj)    help_text = sys.stdout.getvalue()    sys.stdout = old_stdout    return help_textprint("=== 计算平均值函数的帮助 ===")print(get_help_text(calculate_average)[:500])

import pydocdef show_pydoc(obj):    """使用 pydoc 显示文档"""    doc = pydoc.render_doc(obj)    print(doc[:500])  # 打印前500字符# show_pydoc(calculate_average)

def square(x):    """返回数字的平方"""    return x ** 2def is_positive(x):    """判断数字是否为正数"""    return x > 0# 查看print(square.__doc__)print(is_positive.__doc__)

class Student:    """    学生类，存储学生信息    这个类用于管理学生的基本信息，    包括姓名、学号、成绩等。    属性:        name (str): 学生姓名        student_id (str): 学号        scores (list): 各科成绩列表    方法:        add_score(course, score): 添加成绩        get_average(): 计算平均分        get_info(): 获取学生信息    """    def __init__(self, name, student_id):        """        初始化学生对象        参数:            name (str): 学生姓名            student_id (str): 学号        """        self.name = name        self.student_id = student_id        self.scores = {}    def add_score(self, course, score):        """        添加学生成绩        参数:            course (str): 课程名称            score (float): 课程成绩        返回:            None        """        self.scores[course] = score    def get_average(self):        """        计算平均分        返回:            float: 所有课程的平均分，如果没有成绩则返回0        """        if not self.scores:            return 0        return sum(self.scores.values()) / len(self.scores)# 查看文档print("=== 类的文档 ===")print(Student.__doc__)print("\n=== 方法的文档 ===")print(Student.add_score.__doc__)print(Student.get_average.__doc__)

def process_data(data, options=None, verbose=False):    """    处理数据并返回结果    Args:        data (list): 要处理的数据列表        options (dict, optional): 处理选项，默认为None        verbose (bool, optional): 是否输出详细信息，默认为False    Returns:        dict: 处理后的结果，包含以下字段：            - status (str): 处理状态            - result (list): 处理结果            - elapsed_time (float): 处理耗时    Raises:        ValueError: 当数据为空时抛出        TypeError: 当数据类型不正确时抛出    Example:        >>> process_data([1, 2, 3], verbose=True)        {'status': 'success', 'result': [2, 4, 6], 'elapsed_time': 0.001}    """    if not data:        raise ValueError("数据不能为空")    if verbose:        print(f"处理 {len(data)} 条数据")    result = [x * 2 for x in data]    return {        'status': 'success',        'result': result,        'elapsed_time': 0.001    }print(process_data.__doc__)

def calculate_statistics(data, axis=None, ddof=0):    """    计算数据的统计量    Parameters    ----------    data : array_like        输入数据，可以是列表或数组    axis : int or None, optional        计算轴，默认为None（计算所有元素）    ddof : int, optional        自由度修正，默认为0    Returns    -------    mean : float        平均值    std : float        标准差    var : float        方差    Notes    -----    使用标准公式计算：    - 平均值 = sum(x) / n    - 方差 = sum((x - mean)^2) / (n - ddof)    Examples    --------    >>> calculate_statistics([1, 2, 3, 4, 5])    (3.0, 1.4142135623730951, 2.0)    """    import math    n = len(data)    mean = sum(data) / n    variance = sum((x - mean) ** 2 for x in data) / (n - ddof)    std = math.sqrt(variance)    return mean, std, varianceprint(calculate_statistics.__doc__)

import inspectdef show_module_docs(module):    """显示模块中所有公开对象的文档"""    print(f"模块: {module.__name__}")    print("=" * 50)    # 显示模块文档    if module.__doc__:        print(f"模块文档:\n{module.__doc__}\n")    # 获取所有成员    for name, obj in inspect.getmembers(module):        if name.startswith('_'):  # 跳过私有成员            continue        if inspect.isfunction(obj) or inspect.isclass(obj):            print(f"{name}:")            if obj.__doc__:                # 显示文档的第一行                doc_lines = obj.__doc__.strip().split('\n')                print(f"  {doc_lines[0]}")            else:                print("  无文档")            print()# 创建一个示例模块def greet(name):    """向指定人员问候"""    return f"Hello, {name}!"class Calculator:    """计算器类，提供基本数学运算"""    def add(self, a, b):        """返回两个数的和"""        return a + b    def multiply(self, a, b):        """返回两个数的积"""        return a * b# 显示当前模块的文档# show_module_docs(sys.modules[__name__])

import inspectdef search_docs(module, keyword):    """在模块的文档中搜索关键字"""    results = []    # 搜索模块文档    if module.__doc__ and keyword.lower() in module.__doc__.lower():        results.append(('module', module.__name__))    # 搜索函数和类的文档    for name, obj in inspect.getmembers(module):        if name.startswith('_'):            continue        if hasattr(obj, '__doc__') and obj.__doc__:            if keyword.lower() in obj.__doc__.lower():                results.append((type(obj).__name__, name))    return results# 示例import mathresults = search_docs(math, 'log')print("搜索 'log' 结果:")for obj_type, obj_name in results:    print(f"  {obj_type}: {obj_name}")

def validate_docs(module):    """    验证模块中文档的完整性    检查模块、所有函数和类是否有文档字符串    """    import inspect    issues = []    # 检查模块    if not module.__doc__:        issues.append(f"模块 {module.__name__} 缺少文档")    # 检查函数    for name, obj in inspect.getmembers(module):        if name.startswith('_'):            continue        if inspect.isfunction(obj) and not obj.__doc__:            issues.append(f"函数 {name} 缺少文档")        elif inspect.isclass(obj):            if not obj.__doc__:                issues.append(f"类 {name} 缺少文档")            # 检查类的方法            for method_name, method in inspect.getmembers(obj):                if not method_name.startswith('_') and inspect.isfunction(method):                    if not method.__doc__:                        issues.append(f"方法 {name}.{method_name} 缺少文档")    return issues# 示例class TestClass:    """这个类有文档"""    def method_with_doc(self):        """这个方法有文档"""        pass    def method_without_doc(self):        passdef test_function():    """这个函数有文档"""    passdef test_function_no_doc():    pass# 验证当前模块issues = validate_docs(sys.modules[__name__])if issues:    print("文档问题:")    for issue in issues:        print(f"  - {issue}")else:    print("所有对象都有文档！")

def dynamic_function(x):    return x * 2# 动态添加文档字符串dynamic_function.__doc__ = "将输入乘以2后返回"# 验证print(dynamic_function.__doc__)# 为类动态添加文档class DynamicClass:    passDynamicClass.__doc__ = "这是一个动态添加文档的类"print(DynamicClass.__doc__)

def create_help_text(obj):    """根据文档字符串创建格式化的帮助文本"""    if not hasattr(obj, '__doc__') or not obj.__doc__:        return "没有可用文档"    doc_lines = obj.__doc__.strip().split('\n')    help_text = []    help_text.append("=" * 50)    help_text.append(f"帮助: {obj.__name__ ifhasattr(obj, '__name__') else'object'}")    help_text.append("=" * 50)    for line in doc_lines:        help_text.append(line)    return '\n'.join(help_text)def multiply(a, b):    """    计算两个数的乘积    参数:        a: 第一个乘数        b: 第二个乘数    返回:        乘积结果    """    return a * bprint(create_help_text(multiply))

class DocGenerator:    """文档生成器，从代码中提取文档"""    def __init__(self, module):        self.module = module        self.module_name = module.__name__    def generate_markdown(self):        """生成 Markdown 格式的文档"""        lines = []        # 标题        lines.append(f"# {self.module_name} 模块文档")        lines.append("")        # 模块文档        if self.module.__doc__:            lines.append("## 模块说明")            lines.append("")            lines.append(self.module.__doc__)            lines.append("")        # 函数文档        lines.append("## 函数")        lines.append("")        for name, obj in inspect.getmembers(self.module):            if name.startswith('_'):  # 跳过私有函数                continue            if inspect.isfunction(obj):                lines.append(f"### `{name}`")                lines.append("")                if obj.__doc__:                    lines.append(obj.__doc__)                else:                    lines.append("*无文档*")                lines.append("")                # 获取签名                try:                    sig = inspect.signature(obj)                    lines.append(f"**签名:** `{name}{sig}`")                    lines.append("")                except:                    pass        # 类文档        lines.append("## 类")        lines.append("")        for name, obj in inspect.getmembers(self.module):            if name.startswith('_'):                continue            if inspect.isclass(obj):                lines.append(f"### `{name}`")                lines.append("")                if obj.__doc__:                    lines.append(obj.__doc__)                else:                    lines.append("*无文档*")                lines.append("")                # 方法文档                methods = []                for method_name, method in inspect.getmembers(obj):                    if (not method_name.startswith('_') and                         inspect.isfunction(method)):                        methods.append(method_name)                if methods:                    lines.append("**方法:**")                    for method_name in methods:                        method = getattr(obj, method_name)                        lines.append(f"- `{method_name}`")                        if method.__doc__:                            lines.append(f"  {method.__doc__.strip()}")                    lines.append("")        return '\n'.join(lines)# 使用示例if __name__ == "__main__":    import inspect    import sys    # 为当前模块生成文档    generator = DocGenerator(sys.modules[__name__])    doc = generator.generate_markdown()    print(doc[:1000])  # 打印前1000字符    # 保存到文件    # with open('module_doc.md', 'w', encoding='utf-8') as f:    #     f.write(doc)

# 1. 始终为公开对象编写文档def public_function():    """提供清晰的文档说明"""    pass# 2. 使用三重引号class Example:    """    使用三重引号编写多行文档    第一行简要描述，空行后详细说明    """    pass# 3. 包含必要信息def complex_function(param1, param2):    """    函数简要描述    Args:        param1: 参数1的说明        param2: 参数2的说明    Returns:        返回值的说明    Raises:        ValueError: 异常触发条件    Examples:        >>> complex_function(1, 2)        3    """    pass# 4. 使用工具检查文档完整性def check_docstrings(module):    """检查模块中哪些对象缺少文档"""    missing = []    for name, obj in inspect.getmembers(module):        if callable(obj) and not name.startswith('_'):            if not obj.__doc__:                missing.append(name)    return missing