Python 入门教程：文档字符串与 doc 属性详解

芯兔兔 20260511

嵌入式系统

Python 入门教程：文档字符串与 doc 属性详解

摘要

在 Python 编程语言中，文档字符串（Docstring）是一种用于描述模块、类、函数或方法的工具性字符串。它通常被放置在相应定义的最开始位置，以三重引号（''' 或 """）包裹，支持多行写法，便于开发者撰写清晰的注释与说明文档。

文档与代码获取方式

本教程旨在详细介绍 Python 中的面向对象编程方法，适合具备 Python 基础知识和单片机开发经验的读者。相比于其他教程，本文档更侧重于嵌入式系统中上位机软件的设计与实现，涵盖串口通信、数据解析、实时图像绘制等常见应用场景，并结合 Sourcetrail 工具对代码结构进行可视化分析，提升代码理解效率。

正文

Python 允许通过文档字符串（docstring）为模块、类、方法或函数添加说明信息，这些信息可以通过其内置的 __doc__ 属性访问。文档字符串通常位于定义的起始部分，使用三引号（''' 或 """）包裹，用于解释其功能、输入输出格式以及使用方法。

以下代码演示了如何为一个名为 MasterClass 的主机类及其 StartMaster 方法添加文档说明，并通过 __doc__ 属性读取内容：

# 访问 MasterClass 类的 __doc__ 属性print(MasterClass.__doc__)# 访问 MasterClass 类中 StartMaster 方法的 __doc__ 属性print(MasterClass.StartMaster.__doc__)

示例代码如下所示：

class MasterClass(SerialClass, PlotClass):    '''    MasterClass：表示一个主机类，主要用于实现与传感器的通信与控制    属性包括：        state    —— 主机当前运行状态        port     —— 串口端口号        wintitle —— 窗口标题        ...    方法包括：        StartMaster     —— 启动主机功能        StopMaster      —— 停止主机运行        RecvSensorValue —— 接收传感器数值        ...    '''    # 类的初始化方法    def __init__(self, state: int = IDLE_STATE, port: str = "COM17",                  wintitle: str = "Basic plotting examples",                 plottitle: str = "Updating plot", width: int = 1000, height: int = 600):        pass    # 启动主机方法    def StartMaster(self):        '''        StartMaster 方法：用于启动主机设备        调用 SerialClass.OpenSerial() 方法        返回值：无        '''        pass

执行上述代码后，输出结果如下：

此外，Python 也支持为命名元组（namedtuple）添加文档字符串。具体方法是通过继承 namedtuple 并在类中加入注释，示例代码如下：

from collections import namedtuple_Sensor = namedtuple("Sensor", "ID CURRENTVALUE MAXVALUE MINVALUE")class Sensor(_Sensor):    '''    该类继承自一个表示传感器数据的命名元组    属性说明：        ID          ：传感器编号        CURRENTVALUE：当前采集数值        MAXVALUE    ：历史最大值        MINVALUE    ：历史最小值    '''    passsensor_tuple = Sensor(ID="16", CURRENTVALUE=32, MAXVALUE=62, MINVALUE=2)print(sensor_tuple.__doc__)

执行结果如下：

查看全文

芯兔兔

作者最近更新

Python 入门教程：文档字符串与 __doc__ 属性详解