Python常用函数--文档字符串DocStrings

简介: Python 有一个甚是优美的功能称作文档字符串(Documentation Strings),在称呼它时通常会使用另一个短一些的名字docstrings。DocStrings 是一款你应当使用的重要工具,它能够帮助你更好地记录程序并让其更加易于理解。

Python 有一个甚是优美的功能称作Python文档字符串(Documentation Strings),在称呼它时通常会使用另一个短一些的名字docstrings。DocStrings是一款你应当使用的重要工具,它能够帮助你更好地记录程序并让其更加易于理解。令人惊叹的是,当程序实际运行时,我们甚至可以通过一个函数来获取文档!
案例(保存为 function_docstring.py):

def print_max(x, y):
    '''打印两个数值中的最大数。

    这两个数都应该是整数'''
    # 如果可能,将其转换至整数类型
    x = int(x)
    y = int(y)

    if x > y:
        print(x, 'is maximum')
    else:
        print(y, 'is maximum')

print_max(3, 5)
print(print_max.__doc__)

输出:

$ python function_docstring.py
5 is maximum
打印两个数值中的最大数。

    这两个数都应该是整数

它是如何工作的
函数的第一行逻辑行中的字符串是该函数的 文档字符串(DocString)。这里要注意文档字符串也适用于后面相关章节将提到的python模块与python类(Class) 。
该文档字符串所约定的是一串多行字符串,其中第一行以某一大写字母开始,以句号结束。第二行为空行,后跟的第三行开始是任何详细的解释说明。5在此强烈建议你在你所有重要功能的所有文档字符串中都遵循这一约定。
我们可以通过使用函数的 __doc__(注意其中的双下划綫)属性(属于函数的名称)来获取函数 print_max 的文档字符串属性。只消记住 Python 将所有东西都视为一个对象,这其中自然包括函数。我们将在后面的类(Class)章节讨论有关对象的更多细节。
如果你曾使用过 Python 的 help() 函数,那么你应该已经了解了文档字符串的用途了。它所做的便是获取函数的 doc 属性并以一种整洁的方式将其呈现给你。你可以在上方的函数中尝试一下——只需在程序中包含 help(print_max) 就行了。要记住你可以通过按下 q 键来退出 help。
自动化工具可以以这种方式检索你的程序中的文档。因此,我强烈推荐你为你编写的所有重要的函数配以文档字符串。你的 Python 发行版中附带的 pydoc 命令与 help() 使用文档字符串的方式类似。

总结

我们已经了解了许多方面的函数,但我们依旧还未覆盖到所有类型的函数。不过,我们已经覆盖到了大部分你每天日常使用都会使用到的 Python 函数。
接下来,我们将了解如何创建并使用 Python 模块。

相关文章
|
4天前
|
Python
Python闭包函数和计时器
本文介绍了闭包函数的概念,它允许内部函数引用外部作用域的变量但无法修改它们。示例展示了如何使用闭包来封装函数。接着,文章讨论了如何在函数调用时添加开始和结束的打印语句,通过传递函数作为参数实现。然后,文章引入装饰器,通过闭包定义了一个`timer`装饰器,用于在函数执行前后打印消息。最后,给出了一个练习,实现了一个计算函数执行时间的装饰器,处理了带有参数的被装饰函数。
12 1
|
4天前
|
索引 Python
python字符串(str)
【5月更文挑战第8天】
10 3
|
1天前
|
程序员 开发者 Python
Python中的装饰器:优雅而强大的函数修饰工具
在Python编程中,装饰器是一种强大的工具,它可以简洁地实现函数的增强、扩展和重用。本文将深入探讨Python中装饰器的工作原理、常见应用场景以及如何自定义装饰器,帮助读者更好地理解和运用这一重要的编程概念。
|
2天前
|
数据采集 Python
10个Python set 常用操作函数!,bilibili面试题
10个Python set 常用操作函数!,bilibili面试题
10个Python set 常用操作函数!,bilibili面试题
|
2天前
|
数据采集 数据挖掘 Python
Python学习——函数,2024年最新手持4个大厂offer的我
Python学习——函数,2024年最新手持4个大厂offer的我
|
2天前
|
数据采集 数据挖掘 关系型数据库
Excel计算函数(计算机二级)(1),2024年最新2024Python架构面试指南
Excel计算函数(计算机二级)(1),2024年最新2024Python架构面试指南
|
2天前
|
存储 Java Shell
【Python学习教程】Python函数和lambda表达式_6(1),2024蚂蚁金服面试题及答案
【Python学习教程】Python函数和lambda表达式_6(1),2024蚂蚁金服面试题及答案
|
2天前
|
索引 Python Go
【python学习】字符串详解,面试必问公司的问题
【python学习】字符串详解,面试必问公司的问题
|
2天前
|
Python
Python基础教程: math库常用函数(1),Python这些高端技术只有你还不知道
Python基础教程: math库常用函数(1),Python这些高端技术只有你还不知道
|
3天前
|
机器学习/深度学习 数据采集 自然语言处理
python函数参数的传递、带星号参数的传递,2024年大厂Python高级面试题分享
python函数参数的传递、带星号参数的传递,2024年大厂Python高级面试题分享