深入理解 Python 内置数据类型：文档字符串与 doc 属性详解

芯兔兔 20260514

深入理解 Python 内置数据类型：文档字符串与 doc 属性详解

概述

在 Python 语言中，文档字符串（Docstring）是一种专为模块、类、函数或方法提供文档说明的字符串格式。它通常位于代码定义的开头，紧随在声明语句之后，是一种清晰描述代码功能和用法的工具。文档字符串由三重引号（''' 或 """）包裹，支持跨行书写。

文档与源码资源

本教程旨在系统讲解如何运用 Python 进行面向对象编程。读者应具备 Python 基础语法知识，并对单片机开发有一定了解。相比市面上其他 Python OOP 教程，本教程更注重嵌入式上位机开发的实践应用，涵盖主机与从机之间的串口通信、数据解析及可视化展示等内容。教程还结合 Sourcetrail 软件对源码进行可视化分析，以增强理解。

文档字符串与 doc 属性的使用

在 Python 中，文档字符串可用于方法、类或模块，其内容可通过特殊属性 __doc__ 获取。这些字符串通常放置在定义的最上方，用以描述对象的功能、用法和行为。文档字符串由三重引号界定，是 Python 中构建自文档化代码的重要部分。

以下示例展示了如何为 MasterClass 类及其 StartMaster 方法编写文档字符串，并通过 __doc__ 属性读取：

# 访问 MasterClass 类的文档字符串print(MasterClass.__doc__)# 访问 MasterClass 类中 StartMaster 方法的文档字符串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

运行效果如下：

为命名元组添加文档字符串

除了普通类，命名元组（namedtuple）也可以通过继承方式添加文档字符串。示例如下：

from collections import namedtuple_Sensor = namedtuple("Sensor", "ID CURRENTVALUE MAXVALUE MINVALUE")class Sensor(_Sensor):    '''    该类继承自 Sensor 命名元组，用于表示传感器采集数据结构。    属性包括：    - ID         ：传感器编号    - CURRENTVALUE ：当前采集值    - MAXVALUE   ：最大采集值    - MINVALUE   ：最小采集值    '''sensor_tuple = Sensor(ID="16", CURRENTVALUE=32, MAXVALUE=62, MINVALUE=2)print(sensor_tuple.__doc__)

该代码的运行结果如下：

查看全文

芯兔兔

作者最近更新

深入理解 Python 内置数据类型：文档字符串与 __doc__ 属性详解