Dsconfig

这是一个用于管理Tango设备服务器配置的命令行工具。它可在python 2.7以及3.6及更高版本上运行。

该项目目标是提供以方便的方式配置Tango数据库的工具。目前重点关注支持Excel文件作为输入（"xls2json"），但应支持其他格式。

主要思路是解析输入文件并将其转换为由模式指定的中间JSON格式。然后可以将此文件提供给"json2tango"工具，该工具尝试通过添加、修改或删除服务器、设备和属性来使数据库内容匹配。

JSON格式易于创建，并由许多工具和语言支持，因此应能从各种来源轻松生成。一旦拥有此类文件，配置Tango数据库应是一件简单的事情。

发布版本

当需要发布新软件包时，当前流程如下

• 确保所有新内容都在main分支中，并且管道是绿色的。
• 在setup.py中增加版本号（尝试使用"semver"逻辑），并在CHANGELOG.md中添加条目。
• 在仓库中创建具有相同版本号的标签。
• CI中应该有一个新的构建管道，以手动触发的步骤上传到PyPI结束。

完成！您的新版本应该很快就会在PyPI上可用。

注意事项

在开始使用此工具之前，有一些事情需要注意。

• dsconfig的基本思想是幂等性。这意味着再次应用相同的dsconfig文件不应该产生任何变化。其目的是使其不仅可用于更新配置，而且能够检查自上次应用以来是否发生了任何变化。因此，该工具试图找出达到预期状态所需的最小数据库操作集。

• TANGO对名称（例如设备属性）是大小写不敏感的。但有些情况下这会导致混淆的结果。例如，TANGO保留上次写入时使用的格式，这意味着相同的名称可能在不同的位置以不同的格式存在。dsconfig试图优雅地处理这种情况，但这很复杂（例如，所有相关的字符串比较都需要以不区分大小写的方式进行），而且肯定会有一些边缘情况，其行为是意外的。如果您遇到这种情况，请报告。

JSON格式

这是一个示例格式，带有注释（请注意，JSON实际上不支持注释，所以不要复制粘贴这个！）

{
    // these lines are meta information and are ignored so far
    "_version": 1,
    "_source": "ConfigInjectorDiag.xls",
    "_title": "MAX-IV Tango JSON intermediate format",
    "_date": "2014-11-03 17:45:04.258926",

    // here comes the actual Tango data
    // First, server instances and devices...
    "servers": {
        "some-server/instance": {
            "SomeDeviceClass": {
                "some/device/1": {
                    "properties": {
                        "someImportantProperty": [
                            "foo",
                            "bar"
                        ],
                        "otherProperty": ["7"]
                    },
                    "attribute_properties": {
                        "anAttribute": {
                            "min_value": ["-5"],
                            "unit": ["mV"]
                        }
                    }
                }
            }
        }
    },
    // Here you can list your class properties
    "classes": {
        "SomeDeviceClass": {
            "properties": {
                "aClassProperty": ["67.4"]
            }
        }
    }
}

注意，所有属性都作为字符串列表给出。这是Tango DB表示它们的方式，这样我们就可以更容易地比较事物。

注意：现在格式定义得更宽松了；允许将服务器和实例名称分成单独的级别，如下所示

    "servers": {
        "some-server": {
            "instance": {
                "SomeDeviceClass": ...

注意：在设备中省略“properties”意味着在应用配置时工具将忽略任何现有的属性。否则，新配置中未指定的属性将被清除。一个空的属性对象（“properties”：{}）意味着将清理任何现有属性。同样适用于“attribute_properties”。

受保护属性

一些属性被认为是“受保护”的，这意味着如果它们在新配置中不存在，则不会删除。这包括Tango用于配置内部功能（如轮询、事件和记录）的属性。假设它们可以通过其他方式配置，并且不应自动清除。可以通过指定空列表作为值显式删除单个受保护属性。还有一个标志--cleanup-protected-props，意味着受保护属性被像正常属性一样处理。

受保护属性的列表可以在dsconfig/tangodb.py中找到。

xls2json

此工具将Excel文件（格式正确）转换为dsconfig JSON文件。

支持的XLS格式几乎与dsgenerator格式相同，有一些变化

• 现在可以在任何数量的页面上分散服务器定义，并通过给xls2json工具提供它们的名称来选择性地使用这些定义的子集。
• 列名（每个列的第一行）现在是重要的，因此它们的顺序可以放宽。但是，与“标准”工作表有一些不同；“ServerName”应该是“Server”，“Devices”应该是“Device”，在“ParamConfig”标签中，“Parameter”现在应该是“Attribute”。这些更改是为了保持一致性。
• 添加了一些功能以提高灵活性；请参阅“test/files/test.xls”中的示例Excel文件。

将Excel文件转换为JSON的方法如下

xls2json config.xls

这将输出结果JSON数据到stdout。如果有错误或警告，它们将打印到stderr。要将JSON保存到文件，只需重定向输出。

默认情况下，所有表格都会被处理。如果您只想包含其中的一些，请在命令中包含表格名称作为进一步参数。

xls2json config.xls sheet1 sheet2

"Dynamics" 和 "ParamConfig" 表格被特殊处理，因为它们的格式不同。对动态公式进行了某些语法检查，以确保它们可以编译。失败信息会打印到标准错误，并且跳过相应的属性，因此请小心（请参阅 -f 标志以覆盖此行为）。

命令相当详细，默认情况下会愉快地跳过包含不完整信息的行。请确保检查标准错误输出以获取有关此问题的提示。最后，命令会打印一行统计数据，列出它找到的服务器数量等。这被视为一个有用的检查。同时，请检查 JSON 结果以查看是否有意义。

有用的标志（请参阅 --help）

• --fatal (-f) 表示命令将任何解析失败视为致命错误并退出，而不是像通常那样跳过行。如果您不喜欢宽松的默认行为，请使用它。

json2tango

此工具读取一个 JSON 文件（如果没有给出文件名，则从标准输出读取），验证它，并根据需要配置相应的 Tango 数据库。默认情况下，它将仅检查当前 DB 状态，进行比较，并打印出将要执行的操作，而不会更改任何内容。这应该是第一步，以便在将错误永久写入 DB 之前捕获错误。

json2tango config.json

仔细检查此命令的输出。红色表示删除，绿色表示添加，黄色表示更改。请注意，属性在数据库中以字符串列表的形式存储，因此不要因为您的数值属性以字符串形式出现而感到困惑。

[提示：如果您不确定发生了什么，在执行任何非平凡更改之前，检查 -d 参数的输出（见下文）是个好主意。它通常不如正常的 diff 输出易于阅读，但保证是准确的。]

在末尾打印不同数据库操作数量的摘要。这应该很有用，通常您对例如应该添加多少设备等有一个很好的概念。

一旦您确信操作是正确的，请将 "-w" 标志添加到命令行（这可以在末尾或任何地方）。现在，命令将实际上在 Tango 数据库中执行操作。

为了安全起见，程序还将更改前的 DB 状态写入一个临时 JSON 文件（这与 -d 标志的输出相同）。原则上，应该可以通过将输入 JSON 文件与临时文件交换来撤销所做的更改。这是一个新功能，尚未在许多情况下进行测试，因此不要依赖它。

请注意，此工具原则上只关心您 JSON 文件中定义的服务器实例。数据库中的所有其他服务器保持不变。例外情况是，如果您的 JSON 包含在 DB 中但位于不同服务器中的设备，这些设备将被移动到新服务器。如果任何原始服务器在没有设备的情况下变为空，则将删除它。目前没有其他方法可以使用 dsconfig 删除服务器。

一些有用的标志（请参阅 --help 获取完整列表）

• --write (-w) 是执行对数据库进行任何操作所需的。这意味着命令将执行将 DB 带到描述的状态所需的操作。如果状态已经正确，则不会执行任何操作。

• --update (-u) 表示“没有”将删除（请小心，见以下注意事项），只有更改或添加。例外情况是您设备的任何现有重复项。此外，这也仅适用于整个属性，而不是单个行。因此，如果您的 JSON 中某个属性有行被删除，则将从 DB 中删除整个属性，而不管 --update 标志如何。

• --include (-i) [实验性] 允许您在应用配置之前对其进行筛选。您提供一个由“术语” (server/class/device/property) 和正则表达式组成的筛选器，两者之间用冒号分隔。例如：“--include=device:VAC/IP.*01”。这将导致命令只应用与匹配正则表达式的那些设备相关的配置。可以添加多个include，只需附加更多的"--include=..."语句即可。

• --exclude (-x) [实验性] 与--include类似，但它是从配置中删除匹配的部分。

一些不太有用的标志

• --no-validation (-v) 跳过JSON验证步骤。如果您知道自己在做什么，这可能很有用，因为验证非常严格，而工具本身则更宽容。但请注意，您将独自面对意外行为！修复您的JSON可能是一个更好的选择。

• --dbcalls (-d) 打印出执行更改时已执行或将要执行的TANGO数据库API调用。这主要用于调试问题。由于这是实际执行的命令列表，因此可以保证它与现实相符。

• --sleep (-s) 调整db调用之间的等待时间。默认值为0.01秒。这旨在减轻TANGO DB服务的负载，但可以设置为0，以便尽可能快地完成配置。

• --input (-p) 告诉命令简单地打印配置文件，但应用任何筛选器之后。这可以用于检查筛选结果。如果没有使用筛选器，它将只打印您提供的输入文件。此标志跳过所有数据库操作，因此可以“离线”使用。

• --json (-j) [实验性] 以JSON格式打印diff的表示形式，而不是默认的“用户友好”输出。如果输出要由另一个程序消费，这可能更方便，因为JSON易于解析。有关JSON格式的示例，请参阅json2tango测试。由于此功能被视为“实验性”，格式可能在未来的版本中更改。

其他功能

数据库转储

通常非常有用能够制作配置当前状态的“快照”，例如，用于安全存储或用于脚本中。dsconfig中有一个名为dump的模块允许这样做。

python -m dsconfig.dump

它将当前TANGO数据库的内容输出到stdout。有一些筛选功能允许仅转储所选部分（例如，服务器），如下所示

python -m dsconfig.dump server:LimaCCDs/*

有关更多帮助，请尝试使用--help标志。

查看JSON文件

阅读大型、嵌套的JSON文件可能会很痛苦，但dsconfig有一个解决方案；一个基于终端的分层JSON查看器！如果安装了python包urwid和urwidtrees，可以通过运行以下命令交互式地查看任何JSON文件

python  -m dsconfig.viewer something.json

从开始，一切都是“折叠”的，但您可以使用箭头键导航结构，并使用回车键折叠/展开节点。