您当前的位置:首页 > 电脑百科 > 程序开发 > 语言 > Python

3 种不同的 Python 文档字符串格式

时间:2022-04-29 10:27:59  来源:  作者:庄志炎
3 种不同的 Python 文档字符串格式

 

Python/ target=_blank class=infotextkey>Python 正在成为当今流行的编程语言。 对于任何编码项目,文档是提高代码可读性的最重要部分,但同时也是最被忽略的部分! 为了解决这个问题,Sphinx 工具派上用场了,它可以自动化文档部分

现在您已经了解 Sphinx 并知道如何使用它。 让我们知道最常用的文档字符串格式,即 google、NumPy 和 Sphinx 文档字符串格式。

 

1.Google Docstring

这种文档字符串格式是可汗学院推荐的,俗称“Google Docstring”。 为了确保文档字符串与 Sphinx 兼容并被 Sphinx 的自动文档识别,请在 conf.py 文件中添加 sphinx.ext.napoleon 扩展名。 文档字符串格式为:

def google_docstrings(num1, num2
                      ) -> int:
    """Add up two integer numbers.

    This function simply wraps the ``+`` operator, and does not
    do anything interesting, except for illustrating what
    the docstring of a very simple function looks like.

    Args:
        num1 (int) : First number to add.
        num2 (int) : Second number to add.

    Returns:
        The sum of ``num1`` and ``num2``.

    RAIses:
        AnyError: If anything bad hAppens.
    """
    return num1 + num2

 

2. NumPy 文档字符串

这种文档格式用于 NumPy、SciPy 和 Pandas 等主要数据科学库。 就像 Google 的文档字符串一样,要使其与 Sphinx 兼容,您必须在 conf.py 文件中添加 sphinx.ext.napoleon 扩展名。 文档字符串的格式为:

def numpy_docstrings(num1, num2) -> int:
    """
    Add up two integer numbers.

    This function simply wraps the ``+`` operator, and does not
    do anything interesting, except for illustrating what
    the docstring of a very simple function looks like.

    Parameters
    ----------
    num1 : int
        First number to add.
    num2 : int
        Second number to add.

    Returns
    -------
    int
        The sum of ``num1`` and ``num2``.

    Raises
    ======
     MyException
        if anything bad happens

    See Also
    --------
    subtract : Subtract one integer from another.

    Examples
    --------
    >>> add(2, 2)
    4
    >>> add(25, 0)
    25
    >>> add(10, -10)
    0
    """
    return num1 + num2

 

3.Sphinx 文档字符串

没有什么比旧的 sphinx 文档字符串更好的了,这是使用的最基本的文档字符串格式,但在视觉上有些密集,因此难以阅读。 相同的格式是:

def sphinx_docstrings(num1, num2) -> int:
    """Add up two integer numbers.

    This function simply wraps the ``+`` operator, and does not
    do anything interesting, except for illustrating what
    the docstring of a very simple function looks like.

    :param int num1: First number to add.
    :param int num2: Second number to add.
    :returns:  The sum of ``num1`` and ``num2``.
    :rtype: int
    :raises AnyError: If anything bad happens.
    """
    return num1 + num2

 

结论

除了上述格式之外,还有许多可用于 Python 的 docstring 格式,我们在这场比赛中没有一个赢家。

所以选择你喜欢的格式,不要混合格式,并在整个项目中坚持下去。 我个人最喜欢的是 NumPy 的 Docstring!



Tags:Python   点击:()  评论:()
声明:本站部分内容及图片来自互联网,转载是出于传递更多信息之目的,内容观点仅代表作者本人,不构成投资建议。投资者据此操作,风险自担。如有任何标注错误或版权侵犯请与我们联系,我们将及时更正、删除。
▌相关推荐
Python 可视化:Plotly 库使用基础
当使用 Plotly 进行数据可视化时,我们可以通过以下示例展示多种绘图方法,每个示例都会有详细的注释和说明。1.创建折线图import plotly.graph_objects as go# 示例1: 创建简单...【详细内容】
2024-04-01  Search: Python  点击:(13)  评论:(0)  加入收藏
Python 办公神器:教你使用 Python 批量制作 PPT
介绍本文将介绍如何使用openpyxl和pptx库来批量制作PPT奖状。本文假设你已经安装了python和这两个库。本文的场景是:一名基层人员,要给一次比赛活动获奖的500名选手制作奖状,并...【详细内容】
2024-03-26  Search: Python  点击:(21)  评论:(0)  加入收藏
五分钟内完成个性化Python GUI计算器搭建
一、前言在本教程中,你将学习如何在Python中使用Tkinter在短短几分钟内制作自己的全功能GUI计算器。在完成本教程时,除了通常随Python标准库一起安装的Tkinter之外,不需要任何...【详细内容】
2024-01-05  Search: Python  点击:(110)  评论:(0)  加入收藏
50 条实用的编写Python 程序建议
好学编程总结的50 条实用的编写Python 程序建议,如果你要接触Python或准备要学习Python,希望对你有用。一、编程前言建议1:理解Pythonic概念,详见Python中的《Python之禅》。建...【详细内容】
2023-12-29  Search: Python  点击:(143)  评论:(0)  加入收藏
python 爬虫常用第三方库推荐
Python 是一种非常适合进行网络爬虫开发的语言,拥有丰富的第三方库和工具,可以方便快捷地实现各种爬虫需求。下面是好学编程总结的 Python 爬虫开发的一些常用步骤:1. 确定目标...【详细内容】
2023-12-29  Search: Python  点击:(92)  评论:(0)  加入收藏
使用 Python 连接 SQL Server 数据库并实时读取数据?
实时读取SQL Server数据库表并进行处理是一个常见的需求。在Python中,可以使用pyodbc库来连接SQL Server数据库,并使用pandas库来进行数据处理。下面是一个实战示例,演示如何实...【详细内容】
2023-12-28  Search: Python  点击:(98)  评论:(0)  加入收藏
Python 新手入门必学的20个开源库
Python 新手入门必学的20个开源库,今天好学编程全部整理出来了,有需要的小伙伴可以参考一下!1.requests主要功能:发起http请求做过爬虫的程序员一定知道Python的requests库,它使H...【详细内容】
2023-12-27  Search: Python  点击:(93)  评论:(0)  加入收藏
Python Selenium实现自动化测试及Chrome驱动使用!
本文将介绍如何使用Python Selenium库实现自动化测试,并详细记录了Chrome驱动的使用方法。通过本文的指导,读者将能够快速上手使用Python Selenium进行自动化测试。并了解如何...【详细内容】
2023-12-25  Search: Python  点击:(133)  评论:(0)  加入收藏
Python 的 match 有点好用,推荐试试
Match 和 switch 都是控制流语句,但它们在语法和用法上有一些区别。(1) 语法: switch 语句通常在其他编程语言中使用,如 C、C++、Java 等。它的语法通常是 switch(expression)...【详细内容】
2023-12-18  Search: Python  点击:(125)  评论:(0)  加入收藏
5 个让日常编码更简单的 Python 库
如果曾经在 Python 中使用过 subprocess 库,那么我们很有可能对它感到失望,它不是最直观的库,可能还有些复杂,并且很难处理底层系统调用的输出。但是 sh 库结束了低效使用子进程...【详细内容】
2023-12-14  Search: Python  点击:(163)  评论:(0)  加入收藏
▌简易百科推荐
一篇文章教会你使用Python中三种简单的函数
所谓函数,就是指:把某些特定功能的代码组成为一个整体,这个整体就叫做函数。一、函数简介所谓函数,就是指:把某些特定功能的代码组成为一个整体,这个整体就叫做函数。二、函数定义...【详细内容】
2024-04-11  Go语言进阶学习  微信公众号  Tags:Python   点击:(10)  评论:(0)  加入收藏
一篇文章带你了解Python的分布式进程接口
在Thread和Process中,应当优选Process,因为Process更稳定,而且,Process可以分布到多台机器上,而Thread最多只能分布到同一台机器的多个CPU上。一、前言在Thread和Process中,应当优...【详细内容】
2024-04-11  Go语言进阶学习    Tags:Python   点击:(8)  评论:(0)  加入收藏
Python 可视化:Plotly 库使用基础
当使用 Plotly 进行数据可视化时,我们可以通过以下示例展示多种绘图方法,每个示例都会有详细的注释和说明。1.创建折线图import plotly.graph_objects as go# 示例1: 创建简单...【详细内容】
2024-04-01  Python技术    Tags:Python   点击:(13)  评论:(0)  加入收藏
Python 办公神器:教你使用 Python 批量制作 PPT
介绍本文将介绍如何使用openpyxl和pptx库来批量制作PPT奖状。本文假设你已经安装了python和这两个库。本文的场景是:一名基层人员,要给一次比赛活动获奖的500名选手制作奖状,并...【详细内容】
2024-03-26  Python技术  微信公众号  Tags:Python   点击:(21)  评论:(0)  加入收藏
Python实现工厂模式、抽象工厂,单例模式
工厂模式是一种常见的设计模式,它可以帮助我们创建对象的过程更加灵活和可扩展。在Python中,我们可以使用函数和类来实现工厂模式。一、Python中实现工厂模式工厂模式是一种常...【详细内容】
2024-03-07  Python都知道  微信公众号  Tags:Python   点击:(36)  评论:(0)  加入收藏
不可不学的Python技巧:字典推导式使用全攻略
Python的字典推导式是一种优雅而强大的工具,用于创建字典(dict)。这种方法不仅代码更加简洁,而且执行效率高。无论你是Python新手还是有经验的开发者,掌握字典推导式都将是你技能...【详细内容】
2024-02-22  子午Python  微信公众号  Tags:Python技巧   点击:(41)  评论:(0)  加入收藏
如何进行Python代码的代码重构和优化?
Python是一种高级编程语言,它具有简洁、易于理解和易于维护的特点。然而,代码重构和优化对于保持代码质量和性能至关重要。什么是代码重构?代码重构是指在不改变代码外部行为的...【详细内容】
2024-02-22  编程技术汇    Tags:Python代码   点击:(42)  评论:(0)  加入收藏
Python开发者必备的八个PyCharm插件
在编写代码的过程中,括号几乎无处不在,以至于有时我们会拼命辨别哪个闭合括号与哪个开头的括号相匹配。这款插件能帮助解决这个众所周知的问题。前言在PyCharm中浏览插件列表...【详细内容】
2024-01-26  Python学研大本营  微信公众号  Tags:PyCharm插件   点击:(91)  评论:(0)  加入收藏
Python的Graphlib库,再也不用手敲图结构了
Python中的graphlib库是一个功能强大且易于使用的工具。graphlib提供了许多功能,可以帮助您创建、操作和分析图形对象。本文将介绍graphlib库的主要用法,并提供一些示例代码和...【详细内容】
2024-01-26  科学随想录  微信公众号  Tags:Graphlib库   点击:(92)  评论:(0)  加入收藏
Python分布式爬虫打造搜索引擎
简单分布式爬虫结构主从模式是指由一台主机作为控制节点负责所有运行网络爬虫的主机进行管理,爬虫只需要从控制节点那里接收任务,并把新生成任务提交给控制节点就可以了,在这个...【详细内容】
2024-01-25  大雷家吃饭    Tags:Python   点击:(62)  评论:(0)  加入收藏
站内最新
站内热门
站内头条