跳到主要内容

OpcUaVariant

OpcUaVariant 是 OPC UA 的通用值容器, 覆盖 OPC UA 全部内置数据类型. SDK 用它在 Python 与 native 之间传值.

配套

公共属性​

类别属性类型访问说明
状态is_nullboolR是否空
is_scalarboolR是否标量 (= not is_null)
is_arrayboolR是否数组 (当前 SDK 始终 False, 数组通过 Read(ArrayDimensions) 探测)
类型data_typeBuiltinTypeR内置类型枚举 (Boolean / Int32 / Double / String / DateTime / ...)
handleintRC 层 native handle (internal)
值valueAnyRPythonic 解码 (按 data_type 自动转 bool/int/float/str/datetime)

构造​

OpcUaVariant() 创建空 Variant, 然后用 set_* 流式 (链式) 赋值. 用户构造的 Variant 持有 native handle, 必须 close() 或用 with.

from darra_opcua import OpcUaVariant
import datetime as dt

# 标量构造 (流式 setter, 全部返回 self)
OpcUaVariant().set_boolean(True)              # Boolean
OpcUaVariant().set_sbyte(-1)                  # SByte
OpcUaVariant().set_byte(255)                  # Byte
OpcUaVariant().set_int16(42)                  # Int16
OpcUaVariant().set_uint16(42)                 # UInt16
OpcUaVariant().set_int32(42)                  # Int32
OpcUaVariant().set_uint32(42)                 # UInt32
OpcUaVariant().set_int64(42)                  # Int64
OpcUaVariant().set_float(3.14)                # Float
OpcUaVariant().set_double(3.14)               # Double
OpcUaVariant().set_string("hello")            # String
OpcUaVariant().set_datetime(dt.datetime.now(dt.timezone.utc))  # DateTime

数组构造 (待后续 SDK 版本暴露).

读取 (强类型)​

v.as_boolean
v.as_int32
v.as_uint32
v.as_int64
v.as_double          # Float / Double 通用
v.as_string
v.as_datetime
v.value              # Pythonic 自动解码 (按 data_type)

类型不匹配返回 None (不抛异常). 对应 native getter 失败时也返回 None.

ToString / repr​

str(v) 按 data_type 智能格式化:

data_type输出示例
Double3.14
Stringhello
DateTime2026-04-25T12:00:00+00:00 (ISO 8601)
Null<null>
Array(待后续版本)

repr(v): Variant(Double=3.14).

内存所有权​

OpcUaVariant 包装 native handle. 来源决定是否 _owns:

来源_owns谁负责释放
OpcUaVariant() 用户构造True用户 (close / with / dispose)
ua.call(...) 返回True用户 (close / with / dispose)
dv.variant 借用False不需要释放 (跟着 DataValue 释放)
# 用户构造: 必须 dispose
v = OpcUaVariant().set_int32(42)
ua.write("ns=2;s=X", v)
v.close()

# 推荐: with 简写
with OpcUaVariant().set_int32(42) as v:
    ua.write("ns=2;s=X", v)

# call 返回: 也必须 dispose
outputs = ua.call(obj, mtd, [...])
for v in outputs:
    with v:
        print(v.as_int32)

# DataValue 借用: 不要 close
with ua.read("ns=2;s=X") as dv:
    v = dv.variant   # 借用 (_owns=False)
    print(v.as_int32)
    # 不要 v.close() — 数据跟着 dv 一起释放

BuiltinType 完整清单​

from darra_opcua import BuiltinType

BuiltinType.Null         # 0
BuiltinType.Boolean      # 1
BuiltinType.SByte        # 2
BuiltinType.Byte         # 3
BuiltinType.Int16        # 4
BuiltinType.UInt16       # 5
BuiltinType.Int32        # 6
BuiltinType.UInt32       # 7
BuiltinType.Int64        # 8
BuiltinType.UInt64       # 9
BuiltinType.Float        # 10
BuiltinType.Double       # 11
BuiltinType.String       # 12
BuiltinType.DateTime     # 13
BuiltinType.Guid         # 14
BuiltinType.ByteString   # 15
BuiltinType.XmlElement   # 16
BuiltinType.NodeId       # 17
BuiltinType.ExpandedNodeId # 18
BuiltinType.StatusCode   # 19
BuiltinType.QualifiedName # 20
BuiltinType.LocalizedText # 21
BuiltinType.ExtensionObject # 22
BuiltinType.DataValue    # 23
BuiltinType.Variant      # 24
BuiltinType.DiagnosticInfo # 25

ExtensionObject (复杂结构)​

OPC UA Server 自定义 Struct DataType 通过 ExtensionObject 包装. 当前 SDK 提供基础 ExtensionObject 容器, 完整 schema 解析在后续版本.

下一步​