CN112579152A - 一种面向Python语言的文档缺陷检测方法 - Google Patents

Abstract

一种面向Python语言的文档缺陷检测方法，其特征是基于对python语言的静态分析和自然语言处理技术，对python文档中的代码和注释指令中存在的缺陷进行自动检测。该方法涵盖了python代码及注释中最主要的三类错误，包括：自然语言描述相关的反模式，注释中约束条件实现检测，注释中范例代码错误检测。该发明的输入为python源代码包，分别提取代码示例、代码注释、代码名进行分析，检测并输出其中所存在的缺陷。该发明有以下有益效果：从复杂繁琐的文档中精准定位并找出文档缺陷，可以大大提高开发人员的审查效率，同时减少文档阅读者的阅读障碍及理解错误。自动化检测出文档中所存在的错误，对于软件的开发和维护都有着重要意义。

Description

一种面向Python语言的文档缺陷检测方法

技术领域

本发明属于计算机技术领域，涉及python语言静态分析和自然语言处理技术，用于自动化从复杂繁琐的python文档中精准定位并找出文档缺陷，可以大大提高开发人员的审查效率，同时减少文档阅读者的阅读障碍及理解错误。

背景技术

现代软件开发通常由许多个人的贡献组成，并且严重依赖可重用的软件构件，如库和框架等，以提高效率。为了正确使用他人的代码，开发人员需要理解文档和源代码，以熟悉必要的知识。因此这些可重用软件元素的作者有必要投入大量精力将各种指令嵌入源代码和注释中，以促进程序理解过程。然而，由于现代软件工件不断演化，而文档容易被意外忽略，因此缺陷可能存在于文档中，从而阻碍了程序理解。然而由于文档和源代码本身的体系繁杂，手动找出缺陷是非常耗时且容易出错的。因此，本发明旨在自动化检测出python文档中的错误，提高系统文档的准确性和可维护性。

AST(abstract syntax trees)是python中非常有用的一个模块，我们可以通过分析python的抽象语法树来对python的代码进行分析，对于抽象语法树从根节点开始遍历，根据其节点类型准确提取出我们所需要的内容，例如方法名、返回值、异常情况等，再根据提取的内容进行一致性分析，找出文档中存在的缺陷。

在优秀的代码注释中，通常会包含参数说明、设计原理、范例代码等信息。代码注释中可能会包含各种各样的错误，例如参数说明错误、范例代码失效等，代码本身可能会存在方法命名与方法实现不相符的地方，自动化检测这些错误，对于软件的开发和维护都有极其重要的意义。

本发明涵盖了python代码及注释中最主要的三类错误，包括：自然语言描述相关的反模式，注释中约束条件实现检测，注释中范例代码错误检测。该发明的输入为python源代码包，分别提取代码示例、代码注释、代码名进行分析，检测并输出其中所存在的缺陷。本发明有以下有益效果：从复杂繁琐的文档中精准定位并找出文档缺陷，可以大大提高开发人员的审查效率，同时减少文档阅读者的阅读障碍及理解错误。

发明内容

本发明要解决的问题是：从复杂繁琐的python文档中精确定位并找出文档缺陷，实现自动化检测，以提高开发人员的审查效率，减少文档阅读者的阅读障碍及理解错误。

本发明的技术方案为：将python文档的源代码包作为输入，提取方法名作反模式检测，提取方法的参数约束作约束条件检测，提取文档中的示例代码作错误代码名检测，最后输出所有检测到的文档缺陷并输出。具体包含以下步骤：

1)从源代码包中提取出对外开放的方法，对代码中的方法名进行反模式检测。其中，反模式是指在代码编写过程中，注释，文档，以及命名规则中，与常规设计理念不相符或使得程序难以理解的自然语言描述。主要步骤如下：

1a)使用python的ast包，对python源代码进行解析，将带有标准注释的方法视为对外开放方法，提取出这样的方法。

1b)遵循相应规则，找出python框架中对外开放的方法里，反语言模式的代码名，记录并输出。

2)从源代码包中提取方法中的参数使用约束以及其相关的异常规范，找出其中是否存在不一致的情况。其中函数签名的语句(即与参数类型和值相关的语句)和异常在编程期间为用户提供了最重要的信息。它们属于方法调用指令类别，代表所有API文档指令的最大部分。具体步骤如下：

2a)从项目源代码中提取约束情况：将python代码解析成抽象语法树，针对每一个方法，如果该方法有抛出异常，或者调用的方法有抛出异常但是该方法内没有捕捉异常，则提取该方法的方法名，异常信息和参数信息。

2b)异常信息处理：对提取出的异常信息进行校准，删除与参数约束无关的异常信息。再将异常信息分类，分为以下四类，并用公式表示出来：非空(None not allowed)：异常条件的描述中含有‘is None’类型限制(Type restriction)：异常条件的描述中含有’isInstance’范围限制(Range limitation)：异常条件的描述中含有比较操作符，例如’>’，’<’等

限定可选值(Not in)：异常条件的描述中含有’not in’

2c)从注释中提取约束：我们选择了遵循NumpyDoc格式的python框架源代码包，并根据其格式，使用正则表达式的内容匹配，提取出了方法中的参数描述。

2d)检测不一致情况：对于每个提取出的方法，我们比较来自API源代码的异常约束和来自API文档的参数约束。对于每一类异常，应该满足以下条件：

NoneNotAllowed(m，p)：参数描述中应该有明确的非空标志

Type(m，p，cl)：参数描述中应该指出参数的类型限制

Range(m，p，expr)：参数描述中应该明确支持参数的范围限制

NotIn(m，p，p_in)：参数描述中应该明确指出参数的可选值对于存在不一致情况的方法，记录下其参数约束以及异常规范，并输出。

3)从源代码包的注释中提取代码示例，对示例中的方法名进行分析，如果代码中所提及的代码名，不存在于代码中已定义的名和代码最新API中所定义的代码名之中，则将它视为代码错误，代码错误可能包括过期API调用、API方法使用错误等。具体步骤如下：

3a)提取代码示例：示例代码以特定的格式写在源代码中，我们通过python的ast包提取出代码中的注释部分，并提取带有‘Examples’关键字的内容，从而提取出代码示例，并处理代码示例中的特殊字符，例如’…’，‘>>>’等。

3b)从代码示例中提取Er，Ed，Eapi：将代码示例解析成抽象语法树，从根节点开始遍历，分析源码中出现的所有节点类型并且输出保存代码名称和代码类型(包含函数、参数、属性、模块、类、变量)。我们根据python语言的特性，使用正则表达式，按照特定规则提取Er和Ed.(其中Er是指代码示例中所提及的代码名，Ed是指代码示例中所定义的代码名)再从API参考中提取Eapi，包括对外开放的方法以及包名(Eapi是指API参考中对外开放的方法，也包括除本框架外的常用框架API，例如最新python源代码中的API)

3c)检测代码名：先去除Er中的无效代码名，包括那些应该由程序员实现的代码元素，例如代码名中包含“foo”，“my”，“some”等单词，则会被从Er的集合中删掉。再对Er集合中剩余的代码名进行匹配检测，匹配方式为，从所有的Ed文档中检测Er，如果没有检测到，则从Eapi文档中检测Er，仍未检测到的，则使用复数形式的代码名以及简单的正则表达式进行检测。对于仍然未被检测到的Er代码名，将其记录下来，并输出。

在本发明中，输入是python框架源代码包，输出为三种类型的python文档缺陷。本发明有以下有益效果：从复杂繁琐的文档中精准定位并找出文档缺陷，从而大大提高开发人员的审查效率，同时减少文档阅读者的阅读障碍及理解错误。自动化检测出文档中所存在的错误，对于软件的开发和维护都有着重要意义。

附图说明

图1为基于静态分析和自然语言处理技术的python文档缺陷检测方法的流程图

图2为图1中自然语言描述相关的反模式缺陷检测流程图

图3为图1中注释中约束条件实现检测流程图

图4为图1中注释中范例代码错误检测流程图

具体实施方式

为了更好了解本发明的技术内容，特举具体实例并配合所附图式说明如下。

图1为本发明实施的一种静态分析和自然语言处理技术的python文档缺陷检测方法的流程图。

反模式检测：从源代码包中提取出对外开放的方法，对代码中的方法名进行反模式检测。其中，反模式是指在代码编写过程中，注释，文档，以及命名规则中，与常规设计理念不相符或使得程序难以理解的自然语言描述。

参数约束异常检测：从源代码包中提取方法中的参数使用约束以及其相关的异常规范，找出其中是否存在不一致的情况。其中函数签名的语句(即与参数类型和值相关的语句)和异常在编程期间为用户提供了最重要的信息。它们属于方法调用指令类别，代表所有API文档指令的最大部分。

代码示例错误检测：从源代码包的注释中提取代码示例，对示例中的方法名进行分析，如果代码中所提及的代码名，不存在于代码中已定义的名和代码最新API中所定义的代码名之中，则将它视为代码错误，代码错误可能包括过期API调用、API方法使用错误等。

图2为反模式检测的流程图，主要检测源代码中对外开放的方法内，是否存在反语言模式的代码名。具体步骤如下：

步骤1：使用python的ast包，对python源代码进行解析，将带有标准注释的方法视为对外开放方法，提取出这样的方法，并识别出其中的方法名、返回值、注释情况以及具体规则要求的内容。

步骤2：遵循以下规则，找出python框架中对外开放的方法里反语言模式的代码名，记录并输出。具体规则实现如下：

A1：方法的名称以“get”开头，以与同一类中的属性对应的子字符串结尾，并且属性的声明类型和访问器的返回类型相同。然后，识别那些执行的操作多于返回相应属性的方法。

A2：识别出名称以“is”开头，但返回值是非布尔类型的方法。

A3：识别出名称以“set”开头，但返回值不为空的方法。

A4：识别出那些名称以单数名词结尾，却返回集合类型的方法(例如array，list，vector等)。

B1：将注释中的“if”出现次数计为c1，将方法中的“if”出现次数计为c2，识别那些c1＜c2的方法。

B2：识别目的为验证(例如以“validate”，“check”，“ensure”开头的方法)但返回值不为空且未抛出异常的方法。

B3：识别出应该有返回值但返回值为空的方法(例如以“get”开头或者以“return”开头的方法)。

B4：识别目的为预测(例如以“is”，“has”开头的方法)但返回值为空的方法。

B5：识别目的为转换(例如toSomething，source2target一类的方法)但返回值为空的方法。

B6：使用python nltk库检查方法名是否以复数名词结尾，识别那些以复数形式结尾但返回类型不是集合的方法。

C1：根据‘_’拆分方法名，使用python nltk库检测出方法名与返回值中存在反义词的方法。

C2：根据’_’拆分方法名，使用python nltk库检查注释中是否含有方法名的反义词，并识别出来。

将按照以上规则所检测到的反语言模式的方法名统一输出并记录。

图3是约束条件实现检测流程图。主要检测参数使用约束以及其相关的异常规范不一致的方法名。具体步骤如下：

步骤1：从项目源代码中提取约束情况：将python代码解析成抽象语法树，针对每一个方法，如果该方法有抛出异常，则将异常信息存储为(m，p，t，c)，其中m为方法名称，p为参数，t为异常类型，c为这个异常的触发条件。并处理异常传递情况，当有异常从方法m传递到方法n，且在方法n中异常没有被捕捉，则遍历m的抽象语法树，并更新到异常信息集合中。

步骤2：异常信息处理：对提取出的异常信息进行校准，删除与参数约束无关的异常信息。对于每一个(m，p，t，c)∈exceptpinfo，如果p中的参数没有出现在条件c中，则认为这条信息是无关的，因此我们更新exceptpinfo：＝exceptpinfo\(m，p，t，c)。再将异常信息分类，形成参数使用约束，并用公式表示出来，分为以下四类：

非空(None not allowed)：异常条件的描述中含有‘is None’

类型限制(Type restriction)：异常条件的描述中含有’isInstance’

范围限制(Range limitation)：异常条件的描述中含有比较操作符，例如’>’，’<’等

限定可选值(Not in)：异常条件的描述中含有’not in’

步骤3：从注释中提取约束：我们选择了遵循NumpyDoc格式的python框架源代码包，并根据其格式，使用正则表达式的内容匹配，提取出了方法中的参数描述。基本格式如下：

我们根据“Parameters”和“---”来提取每个方法相应的参数信息。

步骤4：检测不一致情况：对于每个提取出的方法，我们比较来自API源代码的约束和来自API文档的参数约束。针对以下四类异常，对应的约束如下：

NoneNotAllowed(m，p)：参数描述中应该有明确的非空标志

Type(m，p，cl)：参数描述中应该指出参数的类型限制

Range(m，p，expr)：参数描述中应该明确支持参数的范围限制

NotIn(m，p，p_in)：参数描述中应该明确指出参数的可选值

对于存在不满足约束的情况，记录下其参数约束以及异常规范，并输出。

图4为范例代码错误检测流程图。主要检测范例代码中所存在的代码错误，具体步骤如下：

步骤1：提取代码示例：对于NumpyDoc格式的python框架源代码包，示例代码以特定的格式写在源代码中，我们通过python的ast包提取出代码中的注释部分，根据‘Examples’和‘---’关键字的内容，提取出代码示例，并处理代码示例中的特殊字符，例如’…’，‘>>>’等。具体格式示例如下：

步骤2：从代码示例中提取Er，Ed，Eapi：将代码示例解析成抽象语法树，从根节点开始遍历，分析源码中出现的所有节点类型并且输出保存代码名称和代码类型(包含函数、参数、属性、模块、类、变量)。我们根据python语言的特性，使用正则表达式，按照特定规则提取Er和Ed.(其中Er是指代码示例中所提及的代码名，Ed是指代码示例中所定义的代码名)具体规则如下：

对于表达式’＝a.f’，如果a是变量，b是属性，则把a，b都加入到Er中

对于表达式’a.m(p，...)’，如果a是变量，m是函数，p是参数，则把a，m，p都加入到Er中

对于表达式’from m import T’，如果m是模块，则把m，T都加入到Er中

对于表达式’a，b…＝*’，如果a是变量，b是属性，则把a，b都加入到Ed中

对于表达式’def f(p，...)’，如果f是函数，p是参数，则把f，p都加入到Er中

再从API参考中提取Eapi，包括对外开放的方法以及包名(Eapi是指API参考中对外开放的方法，也包括除本框架外的常用框架API，例如最新python源代码中的API)

步骤3：检测代码名：先去除Er中的无效代码名，包括那些应该由程序员实现的代码元素，例如代码名中包含“foo”，“my”，“some”等单词，则会被从Er的集合中删掉。再对Er集合中剩余的代码名进行匹配检测，匹配方式为，从所有的Ed文档中检测Er，如果没有检测到，则从Eapi文档中检测Er，仍未检测到的，则使用复数形式的代码名以及简单的正则表达式进行检测。对于仍然未被检测到的Er代码名，将其记录下来，并输出。

最后，将以上输出的三类文档缺陷，统一输出到一个excel文件中，再反馈给开发人员自行审查。

下面通过实例说明本发明的实现效果：

我们对numpy v1.16.2版本的源代码包进行分析，源代码包中包括367个python文件，共计代码行数205059行。经过我们的检测，最终检测到反模式错误数52个，约束条件错误数34个，代码示例错误数7个。找出的缺陷示例如下：

反模式代码名检测示例：

在/numpy/core/multiarray.py的1289行，方法is_busday应该返回bool值，但返回的不是bool值，符合了A2的标准，被识别为反模式代码名。如下：

def is_busday(dates，weekmask＝None，holidays＝None，busdaycal＝None，out＝None)：

return(dates，weekmask，holidays，out)

约束条件检测代码名示例：

在/numpy/fft/pocketfft.py的第182行，对参数n的约束声明不够准确，参数n应该大于1，但是约束中并没有指出这一点，属于类型限制(Range limitation)的缺陷，被识别出来。具体如下：

参数声明：

方法内的参数实际约束：

if(n＜1)：raise ValueError((’Invalid number of FFT data points(％d)specified.’％n))

范例代码错误检测示例：

在/numpy/core/numeric.py第2725行，出现的import OrderedDict，OrderedDict是未被定义过的代码名，被识别出来。具体如下：

>>>from collections import OrderedDict

>>>old_settings＝np.seterr(all＝’print’)

>>>OrderedDict(np.geterr())

Claims (4)

1.一种面向Python语言的文档缺陷检测方法，其特征是基于对python语言的静态分析和自然语言处理技术，对python文档中的代码和注释指令中存在的缺陷进行自动检测。涵盖了代码注释中的主要错误类型，包括：自然语言描述相关的反模式，注释中约束条件实现检测，注释中范例代码错误检测，具体步骤为：

1)从源代码包中提取出对外开放的方法，对代码中的方法名进行反模式检测。其中，反模式是指在代码编写过程中，注释，文档，以及命名规则中，与常规设计理念不相符或使得程序难以理解的自然语言描述；

2)从源代码包中提取方法中的参数使用约束以及其相关的异常规范，找出其中是否存在不一致的情况。其中函数签名的语句(即与参数类型和值相关的语句)和异常在编程期间为用户提供了最重要的信息。它们属于方法调用指令类别，代表所有API文档指令的最大部分；

3)从源代码包的注释中提取代码示例，对示例中的方法名进行分析，如果代码中所提及的代码名，不存在于代码中已定义的代码名和代码最新API中所提供的代码名之中，则将它视为代码错误，代码错误可能包括过期API调用、API方法使用错误等。

2.根据权利要求1中的python文档缺陷检测方法，其特征是，在步骤一中，进行方法名的反模式检测；首先从源代码包中提取对外开放的方法，通过python的ast包，将方法解析成抽象语法树，提取出方法名、返回值、注释等相关信息，并与反模式的规则进行比较，如果方法的定义出现了反语言模式，则输出该方法名以及其违背的规则。

3.根据权利要求1中的python文档缺陷检测方法，其特征是，在步骤二中，进行参数约束条件检测；首先从项目源代码中提取约束，通过解析API源代码，对每个方法m，使用python ast模块提取一个ast树，并以(m，p，t，c)的形式来存储异常信息。其中m代表方法名，p代表参数信息，t代表异常类型，c代表异常的触发条件；接下来，删除与参数约束无关的异常，并处理异常传递情况；将异常信息分为四类，分别是：非空、类型限制、范围限制和限定可选值；接着从注释中提取约束，重点是提取关于方法参数描述相关的约束；最后对于每个方法，将来自源代码中的参数约束情况与来自API文档中的参数描述情况进行比较，输出不一致的方法名及相应的参数约束信息和API的参数描述信息。

4.根据权利要求1中的python文档缺陷检测方法，其特征是，在步骤三中，进行代码示例中的代码名错误检测；首先从源代码中提取代码示例，接着从代码中提取抽象语法树，并解析语法树，从中提取Er，Ed和Eapi(其中Er是指代码示例中所提及的代码名，Ed是指代码示例中所定义的代码名，Eapi是指该python框架API参考中对外开放的代码名)；去除Er中无效的代码名后，对Er中剩余的代码名进行检测，如果不存在于Ed与Eapi的并集中，则输出该代码名，并记录相应的代码片段。

Images