文档字符串

5.5 文档字符串

开发者在编写函数或模块时不光要自己能看懂,在和他人合作共同开发或者被他人调用时也需要他人也能看懂。这个时候就可以为自己编写的函数、模块或者类添加相应的文档字符串(docstring)进行说明了。
一般的,如果想要在模块中添加模块文档字符串,则需要在模块的最上方用3个双引号引住内容,这部分内容则自动会被识别为模块的文档字符串。
注意:模块文档字符串上方可以有注释内容,但是不能有任何Python语句,否则不会被识别成模块文档字符串。
同理,如果想要在函数中添加文档字符串,也是需要在定义函数后马上跟上函数文档字符串内容。否则也不会被识别成函数文档字符串。在以后类的定义时也是同理。
放在函数开头的字符串称为函数文档字符串(docstring),将作为函数的一部分存储起来。下面的代码演示了如何给函数添加文档字符串:

def square(x):
'Calculates the square of the number x.'
return x * x

可以像下面这样访问文档字符串:
>>> square.doc
'Calculates the square of the number x.'
注意__doc__是函数的一个属性。属性名中的双下划线表示这是一个特殊的属性。
示例:为函数添加文档字符串并对参数进行说明

def frb_num_to_str(p_num, p_is_makeup=False, p_int_num=6):
    """
    将一个int类型或者float类型转变成str类型。若p_is_makeup为True,则需要补齐为p_int_num位。
    @param p_num: 输入的参数,一个int类型或者float类型数据
    @param p_is_makeup: 是否要补齐到指定位数
    @param p_int_num: 补齐的指定位数
    @return:
    """
    result = p_num
    if isinstance(p_num, int):
        result = str(p_num)
    elif isinstance(p_num, float):
        result = str(p_num)[:str(p_num).find('.')]
    elif isinstance(p_num, str):
        result = p_num
    # 判断传入的num的类型
    if p_is_makeup and len(result) < p_int_num:
        result = '0' * (p_int_num - len(result)) + result
    return result

提示:
为函数、类、模块自动添加文档字符串参照Pycharm软件设置

本站文章如无特殊说明,均为本站原创,如若转载,请注明出处:文档字符串 - Python技术站

(0)
上一篇 2023年3月31日
下一篇 2023年3月31日

相关文章

  • Python简单语句

    3.5 Python简单语句 Python语句由关键字、标识符、表达式组成。语句的根本作用就是执行某些修改操作,让代码发挥作用去做某些事。语句从执行结构上来分有顺序、条件、循环结构,这3种结构可以实现任何算法功能。Python语句根据代码占用的逻辑行数分为只占用1行的简单语句和占用多行的复合语句。 3.5.1 赋值语句 赋值语句用于将名称(重)绑定到特定值,…

    Python开发 2023年4月2日
    00
  • Python代码块及输入输出

    3.7 Python代码块及输入输出 3.7.1 Python代码块 前面分别介绍了关键字、运算符,由运算符和操作数组成了表达式。而语句由关键字、标识符、表达式组成。而代码块由若干条语句组成。通常Python中的代码块是通过缩进来创建的。在很多语言中,都使用一个特殊的单词或字符,比如begin或{来标识代码块的起始位置,并使用另一个特殊的单词或字符,如end…

    Python开发 2023年4月2日
    00
  • JSON

    4.8 JSON 4.8.1 JSON简介 JSON(JavaScript Object Notation, JS对象简谱)是一种轻量级的数据交换格式。它基于 ECMAScript(European Computer Manufacturers Association, 欧洲计算机协会制定的js规范)的一个子集,采用完全独立于编程语言的文本格式来存储和表示数…

    Python开发 2023年4月2日
    00
  • Python特性

    3.1 Python特性 Python是为可读性设计的,与英语有一些相似之处,并受到数学的影响。比如: Python使用新行来完成命令,而不像通常使用分号或括号的其他编程语言。 Python依赖缩进,使用空格来定义范围;例如循环、函数和类的范围。其他编程语言通常使用花括号或关键字来实现此目的。 Python中没有单个字符,单字符被认为是1个字符的字符串。 对…

    Python开发 2023年4月2日
    00
  • 类相关函数(反射机制)

    6.5 类相关函数(反射机制) 在 Python 中使用反射可以得到对象的属性,即:反过来让对象告诉我们他的相关信息是什么,用于实现在运行时获取对象的相关信息。Python中有几个内置方法,可以用来检查或是访问对象的属性。这些方法可以用于任意对象。 6.5.1 dir([obj]) 描述不带参数时,返回当前范围内的变量、方法和定义的类型列表;带参数时,返回参…

    Python开发 2023年3月31日
    00
  • AI修复照片

    一、前言 最近闲来无事,翻了翻以前的老照片,看着多年前的老照片,感慨万千,仿佛又回到了以前的青春岁月。只可惜青春易逝,无法重来。意气风发,头角峥嵘的画面只能永远地留存在相片之中了。只叹当时没有多拍几张照片留作纪念,可惜当时设备也不好,照片效果不佳。留下遗憾。最近学习了Python,发现可以通过Python使用AI来修复老旧照片,而且修复后的效果非常不错。AI…

    2023年4月2日
    00
  • 类和类的定义

    6.2 类和类的定义 面向对象最重要的概念就是类(Class)和实例(Instance),必须牢记类是抽象的模板,比如学生类,而实例是根据类创建出来的一个个具体的对象,每个对象都拥有相同的方法,但各自的数据可能不同。 6.2.1 什么是类 当你在马路上看到一辆飞驰的奥迪汽车时,这辆奥迪车就是汽车类的一个实例。汽车就是一个类,每辆车都是汽车类的一个实例。可以将…

    Python开发 2023年3月31日
    00
  • 包和库

    2.3 包和库 2.3.1 包的概念 包是在模块之上的概念,为了方便管理而将多个脚本文件(模块文件)进行打包。包是一种用点式模块名构造 Python 模块命名空间的方法。例如,模块名 A.B 表示包 A 中名为 B 的子模块。正如模块可以区分不同模块之间的全局变量名称一样,点式模块名可以区分 NumPy 或 Pillow 等不同多模块包之间的模块名称。包其实…

    2023年4月2日
    00
合作推广
合作推广
分享本页
返回顶部