文档字符串

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日

相关文章

  • 类方法和对象方法

    6.4 类方法和对象方法 方法的本质其实就是函数,在模块中定义就是函数,在类中定义就是类的方法。方法按照归属分类一般有3种:对象方法、类方法、静态方法。 6.4.1 对象方法 class Person: cls_attr = ‘我是类属性’ def __init__(self): self.obj_attr = ‘我是对象属性’ def eat(self):…

    Python开发 2023年3月31日
    00
  • 定义(创建)、调用函数及返回值

    5.2 定义(创建)、调用函数及返回值 5.2.1 定义(创建)函数 要调用一个函数,首先要定义它。在Python中使用关键字def来定义一个函数。函数通常由函数名、参数列表以及一系列语句组成的函数体构成的。函数定义的一般格式如下: def 函数名(参数列表): 函数体 例如: def sayhello(): print(‘hello’) 最简单的函数: d…

    Python开发 2023年4月2日
    00
  • Python关键字(保留字)

    3.2 Python关键字(保留字) 保留字又称关键字,不可用于普通标识符。关键字的拼写必须与这里列出的完全一致。Python 的标准库提供了一个 keyword 模块,可以输出当前版本的所有关键字。>>> import keyword>>> keyword.kwlist [‘False’, ‘None’, ‘True’,…

    Python开发 2023年4月2日
    00
  • 数据类型前置知识

    4.1 数据类型前置知识 4.1.1 数据类型的概念 顾名思义,数据类型就是指数据的类型,计算机不像人,能够很好的分辨数据类型,比如10086,计算机就不知道这个数据到底是字符串还是数值。计算机在用这个数据进行计算时就会出现问题。为了避免这种情况,需要对数据贴一个标签,这个标签就是类型。告诉计算机遇到这种数据应该怎么处理。 4.1.2 哈希 哈希(Hash)…

    Python开发 2023年4月2日
    00
  • Python简单语句

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

    Python开发 2023年4月2日
    00
  • 元组(tuple)

    4.5 元组(tuple) 元组这种数据类型和列表非常相似,也是一种序列。和列表的不同之处在于存放到元组内的数据不能直接修改。元组是一种可迭代对象。使用元组可以使程序运行性能提升,因为一般来说,创建元组类型tuple的变量比列表类型list要快,而且占用更小的存储空间。 4.5.1 元组的创建 4.5.1.1 通过逗号创建 >>> tup1…

    Python开发 2023年4月2日
    00
  • Python表达式

    3.4 Python表达式 Python表达式是运算符和操作数进行有意义排列所得的组合。操作数可以是值、变量、标识符等。单独的一个值或一个变量也是一个表达式。表达式是Python程序中最常见的代码。表达式是一段可以被求值的代码。因为可以被求值,所以一般表达式可以写在赋值语句=的右边。表达式可以作为语句的组成部分。以下都是Python表达式: 5 + 3 3 …

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

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

    Python开发 2023年3月31日
    00
合作推广
合作推广
分享本页
返回顶部