SoftwareX 7（2018）347原始软件出版物QCOBJ一个Python包，用于处理数量感知配置文件R. Vidmar，N.克雷亚蒂OGS-Istituto Nazionale di Oceanografia e di Geofisica Sperimentale，Borgo Grotta Gigante 42 c，Sconico，的里雅斯特，意大利ar t i cl e i nf o文章历史记录：2018年1月23日收到收到修订版2018年10关键词：Python单元配置文件a b st ra ct我们提出了一个Python包，以帮助科学家和研究人员添加物理量的配置文件，他们在他们的计算机程序中使用参数值根据用户定义的规格进行验证，以确保它们在正确的范围内，并最终转换为所需的测量单位。我们还添加了一个图形用户界面来显示和修改配置文件内容，并突出显示它们之间的差异版权所有2018作者。由爱思唯尔公司出版这是CC BY-NC-ND下的开放获取文章许可证（http://creativecommons.org/licenses/by-nc-nd/4.0/）。代码元数据当前代码版本1.2指向用于此代码版本的代码/存储库的永久链接https://github.com/ElsevierSoftwareX/SOFTX-D-18-00013法律代码许可证MIT许可证使用git的代码版本控制系统使用Python的软件代码语言、工具和服务编译要求，操作环境依赖性在Ubuntu上测试应该在Linux，Windows和Mac OS上工作取决于ConfigObj，Pint.用于GUI的PyQt/PySide如果可用，链接到开发人员文档/手册https://bvidmar.bitbucket.io/qcobj问题支持电子邮件rvidmar@inogs.it1. 介绍科学家经常使用配置文件（cfg文件）来设置计算机程序或模拟的参数和初始条件当这些参数不限于数字或字符串，而是表示物理量时，必须考虑它们的测量单位。研究人员习惯于用手工或借助计算机程序来转换导出的物理量，但这种操作减慢了过程，并且固有地容易出错。我们开发了一个软件包来解决这个问题，将测量单位和维度集成到参数中。这种方法确保使用此包的程序将始终获得所请求范围内的数字，并使用正确的测量单位，而与配置文件中使用的单位无关。*通讯作者。电子邮件地址：rvidmar@inogs.it（R. Vidmar）。https://doi.org/10.1016/j.softx.2018.10.0032. 代码设计科学工作意味着编写许多行代码，研究人员试图利用他们的成果，创建由cfg文件驱动的可重用代码。这些基本上是文本文件，其中键与值相关联，这些值可以是数字或符号。通常可以添加注释来解释关键字的含义和其他对最终用户有用的信息允许Python程序员利用cfg文件的标准 包 是 ConfigParser [1] 和 ConfigObj [2] 。 当 需 要 根 据 一 个 名 为configspec的规范文件验证一个cfg文件时，通常首选ConfigObj，该规范文件定义了允许的数据类型和关键字范围，还可以设置默认值。因此，cfg文件只需要指定与默认值不同的值。然而，当程序使用各种物理量时，用户必须注意将它们转换为cfg文件中指定的编号，该编号将根据XNUS规范进行验证。例如，如果一个程序（以及cfg文件）需要以帕斯卡表示的压力，而用户需要mbar或atm，则用户负责进行正确的转换。2352-7110/©2018作者。由爱思唯尔公司出版这是一篇基于CC BY-NC-ND许可证（http://creativecommons.org/licenses/by-nc-nd/4.0/）的开放获取文章可在ScienceDirect上获得目录列表SoftwareX期刊主页：www.elsevier.com/locate/softx348R. Vidmar，N.Creati/SoftwareX 7（2018）347我们发现这个过程耗时且容易出错，因为它需要经常检查正确开发和测试的函数，而问题通常在单位转换中我们的解决方案是将物理量集成到配置文件中。存在许多管理物理单位操作的Python库，但我们发现Pint [3]是最容易阅读的，因为它有一个干净的语法来指定单位。Pint集成了单元解析：识别单元的前缀和复数形式，而无需显式定义它们。换句话说：由于前缀kilo和单位meter已经定义，Pint理解公里。Pint还可以处理以字符串形式提供的单位，我们选择的主要原因最终我们创 建了一个Python 库，或者更 恰当地说，一个集成ConfigObj和Pint的包，我们称之为QCOBJ。在本文中，我们参考1.2版本。QCOBJ由三个主要类组成。2.1. Q_这是物理量容器类。它提供了所有方法来操作定义物理量的字符串，并支持不同单位之间的转换它还实现了以清晰的人类可读形式表示它们的方法。只有当它们具有相同的维度时，才可以添加或比较Q_instances2.2. 验证人Certifier类是原始ConfigObj Validator类的扩展，它理解为物理量创建的新语法。它是一个透明层，用于访问存储为字符串的数据并使其可用于程序。它还确保cfg文件中使用的值在尺寸上是正确的，当它们错误时会引发异常如果用户规范定义了最小值和/或最大值，并且用户提供的值超出了此范围，则也会引发异常2.3. QConfigObj它扩展了ConfigObj类，添加了方法来集成Certifier。当验证器实例提供给该类的空实例时，可以创建默认的cfgQConfigObj也有方法将用户定义的数量转换为在QConfigspec中使用的例如，在mspec中以m/s为单位定义速度的关键字总是可以转换为m/s，即使其值在cfg中设置为knots，或者在程序执行期间设置为任何其他速度测量单位。QConfigObj有一个保留的关键字“文件”，它允许包含一个文件列表长的配置文件，数百或数千行，因此可以分割成更小的单元，从而提高可读性和重用。2.4. 图形用户界面（GUI）在比较长的cfg文件时，我们注意到发现它们之间的差异相当困难。标准工具[4]可以用来比较文件，但这些工具也突出了缩进和注释行的差异，因此我们发现它们相当不可用。包中包含的CfgGui类定义了一个简单的小部件来处理这类配置文件。我们为小部件选择了一个树形图表示，因为配置文件是按节组织的，并且可以嵌套到任何级别。这个类已经在一个名为cfggui.py的简单GUI应用程序中使用，该应用程序旨在查看、编辑和比较我们的cfg文件。图 1是cfggui.py显示的cfg文件的展开树视图。值根据其数据类型进行着色：数量为红色，布尔值为绿色，字符串为蓝色。其他数据类型为黑色。小部件中不显示注释行，以便仅将注意力集中值和单位可以点击编辑，超出范围的值或尺寸错误的单位不接受。将鼠标悬停在一个值上会弹出一个帮助工具提示窗口，其中描述了关键字（来自RISKSpec文件）、其数据类型和允许的范围。菜单栏中的File menu允许加载和保存cfg文件，但也可以在启动应用程序时将输入文件指定为命令行上的参数CfgGui小部件还可以并排显示两个cfg文件，如图所示。 2，并允许扩展和压缩的每一个单一的部分，以及同步滚动。值再次根据其数据类型着色，并且突出显示它们之间的差异，恢复背景色和前景色。还支持两个以上文件的比较我们的实现使用模型-视图-控制器（MVC）[5]模式，在Python文献[6] [7]中提供的许多GUI工具包中，我们坚持使用PyQt/PySide [8][9]，因为它们提供了更大的灵活性和用户控制。从用户的角度来看，PyQt和PySide几乎是相同的，PyQt是一个更加成熟，高效和稳定的项目。QCOBJ包含一个兼容性模块，让用户在运行时自由选择3. 安装QCOBJ 托 管 在 https://bitbucket.org/bvidmar/qcobj 上 ， 但 使 用PyQt的默认版本也可以使用命令pip从PyPi安装python3 -m pip install qcobj4. 使用由于我们想在程序中一次性定义所需的测量单位，并且能够在我们的cfg文件中使用任何尺寸正确的单位，因此我们必须首先创建一个定义关键字（用于变量），测量单位（用于数量）以及可选的有效范围。只要我们有一个Pint spec文件，任何cfg都可以根据它进行验证，并在我们的Python程序中使用，该程序将处理Pint数量而不是数字。4.1. 安装spec文件这个文件定义了有效的关键字、变量的类型以及可选的有效范围，因为QCOBJ是ConfigObj的子类这些关键字可以按层次形式组织成节和子节Configspec文件可以用任何文本编辑器编写，但我们提供了一个实用函数makeSpec，它可以通过一个简短的Python脚本帮助构建具有正确语法和缩进的configspec因此，每个节/子节都可以填充一个有序的Python字典，其中每个关键字都与定义注释，单位（根据Pintsyn- tax），默认值和范围的字典相清单1：示例目录中configspecMaker.py的片段12345l e v e l= 1secname =（R. Vidmar，N.Creati/SoftwareX 7（2018）347349图1.一、 一个使用CfgGui类的简单应用。678910111213141516171819例如，清单1中第10行的关键字roomTemp定义了一个温度，它可以假定为18到26摄氏度之间的任何值，默认值为20摄氏度然后，清单1第19行的makeSpec函数处理同一清单第3行的subsection实例，在subspec字符串中保留清单2中出现的具有正确语法和适当缩进的内容。这将是我们的第二个规格。清单2： 节片段示例123456789清单3是一个示例的RISPspec文件。清单3：Rightspec.cfg123456789default = False）），（units=（、单位=0）），（units =25）），）的情况）subspec = makeSpec（secname，subsection，l e v e l）##此文件的标题、日期、作者和版本#描述=字符串（默认值=...电压=数量（单位=V，最小值=0，最大值=100，默认值=#更多配置文件列表，以空格分隔Files= string（default=m2/kg2'）【原料】#启用sugarsugar= boolean（default= False）#两种水果任你选择fruits= string_list（default= list（apple，orange））# 室温室温=数量（单位=摄氏度，最小值=18，最大值=26，默认值=#一些十进制值（欢迎浮动，一如既往）fraction= float（最小值=0，最大值=1，默认值=0.25）350R. Vidmar，N.Creati/SoftwareX 7（2018）347图二、两个cfg文件比较的扩展树视图，其中差异以反向文本/背景颜色突出显示。10111213141516171819第7行的数量定义了关键词UG的测量单位，因此也定义了它的物理尺寸。接受的数量以及它们的别名在品脱单位定义文件中定义，但用户可以轻松编辑此文本文件以添加任何其他所需的单位。可以像第6行那样指定每个量的下限和上限，将检查实际配置文件中定义的值是否在定义的范围内的职责留给Certifier类特别章节许多定义共享相同关键字和规范的子节，并将在同样的方式。4.2. cfg文件我们的程序将使用的实际cfg文件可以使用任何编辑器从头开始创建，但我们建议使用以下命令编辑从相应的配置文件Python-m qcobj。qconfigobj- 不配置规格cfg此命令将在当前目录中保留template.cfg的默认值，以便用户将请求的值分配给关键字来重命名和定制如果物理量的数值在尺寸上是正确的，并且如果转换为物理量规范中已经指定的单位，则物理量在允许的范围内（如果定义），则可以将物理量指定为任何测量单位例如，电压可以被指定为电压=12.6 V#或电压=12.6V#或电压=12.6欧姆毫安压力可以用帕斯卡或帕或牛顿/米 **2或力_千克/厘米 **2表示。Python脚本可以通过以下方式访问配置文件内容【原料】...室温=数量（单位=摄氏度，最小值=18，最大值=26，默认值=[[Regions]]...#更多类似的章节可以添加不同的名称[[[许多 ]]]...#恒温T=数量（单位=摄氏度，默认值=R. Vidmar，N.Creati/SoftwareX 7（2018）347351从Qcobj导入qconfigogijqcobj = qconfigobj。QConfigObj（“my_project . cfg“，配置规范=”配置规范。cfg“）一旦QCOBJ对象被实例化，其中的物理量可以用标准ConfigObj语法访问ingredients = qcobj [#被一验证数量，常温罐被#转换到任何其他单位和最终i t s # value i savailable for or computation absoluteRoomTemperature =roomTemperature. to（. 幅度#增加温度absoluteRoomTemperature += 5。2#转换现在T H I S 电子邮件 * 到i t s物理数量#作为在产品规格：在T H I ScasedegC无环隙的#th d my_project. 中菲e单位用于newTempQuantity = qconfigobj。q Like（absoluteRoomTemperature，ingredients，roomTempqconfigobj包还提供了一个实用函数val，该函数返回cfg中定义的数量的大小，该大小已被转换为RISK规范中定义的单位。例如，如果配置文件acspec.cfg只包含以下行：压力=量（单位=Pa，default=0 Pa）cfgacfg.cfg文件包含：压力= 10 atm以下脚本将打印转换为Pa的压力该包的完整文档以及其中的所有类和函数都可以在该包的/doc目录中以pdf格式获得，也可以在https://bvidmar.bitbucket.io/qcobj上以HTML格式在线获得。/examples目录也包含一些脚本来学习基本用法。5. 最后发言在开发地球动力学并行数值模拟套件的过程中，已经对QCOBJ进行了评估和调整[10]。我们发现它在管理计算所需的数百个物理量（参数）方面有很大的帮助，它的使用解决了单位转换的麻烦过程，为研究留下了更多的时间CfgGui是比较驱动具有数百个参数的模型的cfg文件所必需的确认我们感谢Hernán Grecco为帮助我们取得这一成果所花费的时间和精力。引用[1]兰加十四点二解析器-解析文件解析器; 2017，https：//docs.python.org/3/library/configparser.html。[2]Foord M，Larosa N，Dennis R，Courtwright E.https://configobj.readthedocs.io，2014年。[3]格雷科河Pint：makes units easy; 2017，https://pint.readthedocs.io/.[4]Wikipedia.文件比较工具的比较-维基百科; 2017，https：//en.wikipedia.org/wiki/Comparison_of_file_comparison_tools网站。[5]Wikipedia. Model-view-controller-Wikipedia; 2017，https://en.wikipedia.org/wiki/Model-view-controller.[6]阿尔维斯湾GuiProgramming - Python Wiki; 2017，https://wiki.python.org/moin/GuiProgramming.[7]波罗湾PyGTK，PyQT，Tkinter和wxPython比较; 2017，http：//ojs.pythonpapers.org/index.php/tpp/article/download/61/57。[8]江岸电脑有限公司Riverbank-软件-PyQt-什么是PyQt？2017年，中国科学院出版社。https://riverbankcomputing.com/software/pyqt/[9]Qt公司PySide-Qt Wiki; 2017，https://wiki.qt.io/PySide.[10] 尼古拉·克雷蒂，罗伯托·维德马，保罗·斯特扎伊.在HPC中使用Python进行地球动力学模拟In：Kathryn Huff，James Bergstra，editor.2015年第14届Pythonin Science会议论文集p. 158比63从QCOBJ。 克塞西戈比进口QConfigObj，val qcobj =QConfigObj（“acfg . cfg“，配置规范=”acspec. cfg“）print（val（qcobj，’ pressure ’ )
我的内容管理
展开
