Python

本页介绍 Python API。适用于所有语言的连接字符串、标签地址和默认值的变更，详见概览页面。

简要说明

PLC4Py API 没有变化。 PlcDriverManager、连接、请求构建器和响应类型都与 0.13.1 相同。在 0.13.1 上运行的代码可以在 1.0.0 上运行。

import asyncio
from plc4py.PlcDriverManager import PlcDriverManager

# unchanged between 0.13.1 and 1.0.0
async def main():
    async with PlcDriverManager().connection("modbus://127.0.0.1:5020") as connection:
        ...

以下变更属于增量变更，或属于运行时行为。

消息嵌套深度受限

生成的解析器会拒绝嵌套类型深度超过 1024 层的消息。若干协议类型包含自身，因此值树的深度由发送方决定，且在线路上每增加一层只需花费一个字节；一旦嵌套过深，曾导致解析器内部耗尽解释器的递归限制——这既不是驱动程序能够报告的解析失败，也不是接收路径能够处理的错误。

如果某个设备的消息确实存在更深的嵌套，请设置 PLC4X_MAX_NESTING_DEPTH 环境变量。该变量在所有 PLC4X 绑定中含义相同；如果其取值不是正数，则保持默认值不变，并输出一条警告。

项目自身测试集中嵌套最深的消息为 36 层，因此该限制只会影响真实设备绝不会发送的情况。

标签地址保持不变

这是 PLC4Py 与 PLC4J 和 PLC4Go 产生差异的地方，值得明确说明。

1.0.0 在所有 Java 和 Go 驱动中统一引入了一种数组记法：选择部分写在类型之前，而 [4] 表示"索引为 4 的元素"。

holding-register:1[0..3]:INT     # PLC4J and PLC4Go in 1.0.0

PLC4Py 并未更新。 其 Modbus 标签模式依然采用旧的“类型后接数量”形式，其中 [4] 表示“四个元素”：

holding-register:1:INT[4]        # PLC4Py, both in 0.13.1 and in 1.0.0

你现有的 PLC4Py 地址可以保持不变地继续工作——但从 Addressing arrays 页面或某个可正常运行的 PLC4J 应用中复制来的地址将无法解析。请把数组记法的相关文档理解为是针对 PLC4J 和 PLC4Go 的，而不是 PLC4Py。

Modbus 数组与字符串

Modbus 寄存器值的打包与解包方式已从 mspec 中移出，转由 ModbusRegisterCodec 实现负责，同时为 Modbus 数据类型新增了 STRING 和 WSTRING。这属于驱动内部的实现细节；标签地址和返回的 PlcValue 类型均未改变。

生成的协议类

如果你直接从 plc4py.protocols.* 导入——这是生成的代码，而非公开 API——请注意 UMAS 常量类已被重命名：

# 0.13.1
from plc4py.protocols.umas.readwrite.UmasConstants import UmasConstants

# 1.0.0
from plc4py.protocols.umas.readwrite.Constants import Constants

使用 PlcDriverManager 和请求构建器编写的应用程序代码不受影响。

构建

PLC4X 的构建已迁移到 Apache Maven 4。只有当你在 PLC4X 源码树中使用 -Pwith-python 构建 PLC4Py 时，这一点才与你有关；在 plc4py 目录中执行 pip install . 的方式没有变化。