第六章 使用嵌入式 Python （三）

从 ObjectScript 调用嵌入式 Python 代码

使用 Python 库

嵌入式 Python 让可以轻松访问数以千计的有用库。通常称为“包”，它们需要从 Python 包索引 (PyPI) 安装到 <installdir>/mgr/python 目录中，然后才能使用。

例如，ReportLab Toolkit 是一个用于生成 PDF 和图形的开源库。以下命令使用软件包安装程序 irispip 在 Windows 系统上安装 ReportLab：

C:\InterSystems\IRIS\bin>irispip install --target C:\InterSystems\IRIS\mgr\python reportlab

在基于 UNIX 的系统上，使用：

$ pip3 install --target /InterSystems/IRIS/mgr/python reportlab

安装包后，可以使用 %SYS.Python 类的 Import() 方法在ObjectScript 代码中使用它。

给定一个文件位置，以下 ObjectScript 方法 CreateSamplePDF() 创建一个示例 PDF 文件并将其保存到该位置。

Class Demo.PDF
{

ClassMethod CreateSamplePDF(fileloc As %String) As %Status
{
    set canvaslib = ##class(%SYS.Python).Import("reportlab.pdfgen.canvas")
    set canvas = canvaslib.Canvas(fileloc)
    do canvas.drawImage("C:\Sample\isc.png", 150, 600)
    do canvas.drawImage("C:\Sample\python.png", 150, 200)
    do canvas.setFont("Helvetica-Bold", 24)
    do canvas.drawString(25, 450, "InterSystems IRIS & Python. Perfect Together.")
    do canvas.save()
}

}

该方法的第一行从 ReportLab 的 pdfgen 子包中导入 canvas.py 文件。第二行代码实例化一个 Canvas 对象，然后继续调用它的方法，这与调用任何 IRIS 对象的方法很相似。

然后，可以以通常的方式调用该方法：

do ##class(Demo.PDF).CreateSamplePDF("C:\Sample\hello.pdf")

调用用 Python 编写的 IRIS 类的方法

可以使用嵌入式 Python 在 IRIS 类中编写方法，然后从 ObjectScript 调用它，就像调用用 ObjectScript 编写的方法一样。

下一个示例使用 usaddress-scourgify 库，可以从 Windows 上的命令行安装，如下所示：

C:\InterSystems\IRIS\bin>irispip install --target C:\InterSystems\IRIS\mgr\python usaddress-scourgify

在基于 UNIX 的系统上，使用：

$ pip3 install --target /InterSystems/IRIS/mgr/python usaddress-scourgify

下面的演示类包含美国地址部分的属性和一个用 Python 编写的方法，该方法使用 usaddress-scourgify 根据美国邮政服务标准对地址进行规范化。

Class Demo.Address Extends %Library.Persistent
{

Property AddressLine1 As %String;

Property AddressLine2 As %String;

Property City As %String;

Property State As %String;

Property PostalCode As %String;

Method Normalize(addr As %String) [ Language = python ]
{

    from scourgify import normalize_address_record
    normalized = normalize_address_record(addr)

    self.AddressLine1 = normalized['address_line_1']
    self.AddressLine2 = normalized['address_line_2']
    self.City = normalized['city']
    self.State = normalized['state']
    self.PostalCode = normalized['postal_code']
}

}

给定地址字符串作为输入，类的 Normalize() 实例方法规范化地址并将每个部分存储在 Demo.Address 对象的各种属性中。

可以按如下方式调用该方法：

USER>set a = ##class(Demo.Address).%New()

USER>do a.Normalize("One Memorial Drive, 8th Floor, Cambridge, Massachusetts 02142")

USER>zwrite a
a=3@Demo.Address  <OREF>
+----------------- general information ---------------
|      oref value: 3
|      class name: Demo.Address
| reference count: 2
+----------------- attribute values ------------------
|       %Concurrency = 1  <Set>
|       AddressLine1 = "ONE MEMORIAL DR"
|       AddressLine2 = "FL 8TH"
|               City = "CAMBRIDGE"
|         PostalCode = "02142"
|              State = "MA"
+-----------------------------------------------------

运行用 Python 编写的 SQL 函数或存储过程

当使用嵌入式 Python 创建 SQL 函数或存储过程时， IRIS 会投影一个具有可从 ObjectScript 调用的方法的类，就像使用任何其他方法一样。

例如，本文档前面示例中的 SQL 函数会生成一个类 User.functzconvert，它有一个 tzconvert() 方法。从 ObjectScript 调用它，如下所示：

USER>zwrite ##class(User.functzconvert).tzconvert($zdatetime($h,3),"US/Eastern","UTC")
"2021-10-20 15:09:26"

这里，$zdatetime($h,3) 用于将当前日期和时间从 $HOROLOG 格式转换为 ODBC 日期格式。

运行任意 Python 命令

有时，当开发或测试嵌入式 Python 代码时，从 ObjectScript 运行任意 Python 命令会很有帮助。可以使用 %SYS.Python 类的 Run() 方法来执行此操作。

也许想测试本文档前面使用的 usaddress_scourgify 包中的 normalize_address_record() 函数，但不记得它是如何工作的。可以使用 %SYS.Python.Run() 方法从终端输出函数的帮助，如下所示：

USER>set rslt = ##class(%SYS.Python).Run("from scourgify import normalize_address_record")

USER>set rslt = ##class(%SYS.Python).Run("help(normalize_address_record)")      
Help on function normalize_address_record in module scourgify.normalize:
normalize_address_record(address, addr_map=None, addtl_funcs=None, strict=True)
    Normalize an address according to USPS pub. 28 standards.

    Takes an address string, or a dict-like with standard address fields
    (address_line_1, address_line_2, city, state, postal_code), removes
    unacceptable special characters, extra spaces, predictable abnormal
    character sub-strings and phrases, abbreviates directional indicators
    and street types.  If applicable, line 2 address elements (ie: Apt, Unit)
    are separated from line 1 inputs.
.
.
.

%SYS.Python.Run() 方法在成功时返回 0，在失败时返回 -1。