第一章 嵌入式Python概述（一）

嵌入式 Python 允许将 Python 与 IRIS 数据平台的本地编程语言 ObjectScript 一起使用。当使用嵌入式 Python 在 IRIS 类中编写方法时，Python 源代码与编译后的 ObjectScript 代码一起编译为在服务器上运行的目标代码。与使用网关或 Python的 Native SDK 相比，这允许更紧密的集成。还可以导入 Python 包，无论它们是自定义的还是公开的，并在ObjectScript 代码中使用它们。 Python 对象是 ObjectScript 中的一等公民，反之亦然。

• 使用来自 ObjectScript 的 Python 库 - 此方案假设 ObjectScript 开发人员，并且希望利用 Python 开发人员社区可用的众多 Python 库的强大功能。
• 从 Python 调用 IRIS API — 此方案假定您是一名 Python 开发人员，对 IRIS 不熟悉，并且想知道如何访问 API。
• 一起使用 ObjectScript 和 Python — 这个场景假设在一个由 ObjectScript 和 Python 开发人员组成的混合团队中，并且想知道如何一起使用这两种语言。

将需要 2021.2 或更高版本的正在运行的 IRIS 实例，以及取决于操作系统的一些先决条件。还需要知道如何访问终端，即 IRIS 命令行工具。

本文档中的一些示例使用来自 GitHub 上 Samples-Data 存储库的类：https://github.com/intersystems/Samples-Data。 建议创建一个名为 SAMPLES 的专用命名空间并将样本加载到该命名空间中。如果想查看或修改示例代码，则需要设置集成开发环境 (IDE)。推荐使用 Visual Studio Code。

本篇并不试图提供嵌入式 Python 或使用 IRIS 进行编程的全面概述。

使用 ObjectScript 中的 Python 库

使用 Embedded Python，ObjectScript 开发人员可以轻松地使用来自 IRIS 的众多可用 Python 库（通常称为“包”）中的任何一种，从而无需开发自定义库来复制现有功能。 IRIS 在 <installdir>/mgr/python 目录中查找已安装的 Python 包

从 ObjectScript 准备 Python 包以供使用是一个两步过程：

1. 从命令行，从 Python 包索引（或其他索引）安装所需的包。
2. 在 ObjectScript 中，导入已安装的包以加载包并将其作为对象返回。然后，可以像使用实例化的 ObjectScript 类一样使用该对象。

安装 Python 包

在将 Python 包与 Embedded Python 一起使用之前，请从命令行安装。使用的命令会有所不同，具体取决于使用的是 Windows 还是基于 UNIX 的系统。 建议将软件包安装到目录 <installdir>/mgr/python。

在 Windows 上，使用 <installdir>/bin 目录中的 irispip 命令：irispip install --target <installdir>\mgr\python <package>.

例如，可以在 Windows 机器上安装 numpy 包，如下所示：

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

在基于 UNIX 的系统上，使用 pip3 命令：pip3 install --target <installdir>/mgr/python <package>。

例如，可以在 Linux 机器上安装 numpy 包，如下所示：

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

注意：如果基于 UNIX 的系统没有安装 pip3，请使用系统的包管理器安装包 python3-pip。

导入 Python 包

%SYS.Python 类包含从 ObjectScript 使用 Python 所需的功能。可以在任何 ObjectScript 上下文中使用 %SYS.Python，例如类、终端会话或 SQL。

要从 ObjectScript 导入 Python 包或模块，请使用 %SYS.Python.Import() 方法。

例如，假设在 USER 命名空间中，以下命令会在终端中导入数学模块：

USER>set pymath = ##class(%SYS.Python).Import("math")

数学模块与标准 Python 版本打包在一起，因此无需在导入之前安装它。通过在 pymath 对象上调用 zwrite，可以看到它是内置数学模块的一个实例：

USER>zwrite pymath
pymath=1@%SYS.Python  ; <module 'math' (built-in)>  ; <OREF>

注意：包是 Python 模块的集合，但是当导入包时，创建的对象始终是模块类型。

现在，可以像访问任何 ObjectScript 对象一样访问数学模块属性和方法：

USER>write pymath.pi
3.141592653589793116
USER>write pymath.factorial(10)
3628800

示例

此示例使用 geopy 包来访问 OpenStreetMap 的 Nominatim 地理编码工具。地理编码是获取基于文本的位置描述（例如地址或地名）并返回地理坐标（例如纬度和经度）以精确定位地球表面位置的过程。

首先，从命令行安装 geopy，如下 Windows 示例所示：

C:\InterSystems\IRIS\bin>irispip install --target C:\InterSystems\IRIS\mgr\python geopy
Collecting geopy
  Using cached geopy-2.2.0-py3-none-any.whl (118 kB)
Collecting geographiclib<2,>=1.49
  Using cached geographiclib-1.52-py3-none-any.whl (38 kB)
Installing collected packages: geographiclib, geopy
Successfully installed geographiclib-1.52 geopy-2.2.0

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

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

然后在终端中运行以下命令来导入和使用模块：

USER>set geopy = ##class(%SYS.Python).Import("geopy")
 
USER>set args = { "user_agent": "Embedded Python" }
 
USER>set geolocator = geopy.Nominatim(args...)
 
USER>set flatiron = geolocator.geocode("175 5th Avenue NYC")
 
USER>write flatiron.address
Flatiron Building, 175, 5th Avenue, Flatiron District, Manhattan, New York County, New York, 10010, United States
USER>write flatiron.latitude _ "," _ flatiron.longitude
40.74105919999999514,-73.98964162240997666
USER>set cityhall = geolocator.reverse("42.3604099,-71.060181")
 
USER>write cityhall.address
Government Center, Cambridge Street, Downtown Crossing, West End, Boston, Suffolk County, Massachusetts, 02203, United States

此示例将 geopy 模块导入 ObjectScript。然后它使用 Nominatim 模块创建一个地理定位器对象。该示例使用地理定位器的 geocode() 方法在给定字符串的情况下查找地球上的位置。然后它调用 reverse() 方法来查找给定纬度和经度的地址。

需要注意的一点是 Nominatim() 采用命名关键字参数，ObjectScript 不直接支持这种结构。解决方案是创建一个包含参数列表的 JSON 对象（在这种情况下将 user_agent 关键字设置为值“嵌入式 Python”），然后使用 args... 语法将其传递给方法。

与前面示例中导入的数学模块相比，对 geopy 对象调用 zwrite 表明它是安装在 C:\InterSystems\iris\mgr\python 中的 geopy 包的一个实例：

USER>zwrite geopy
geopy=2@%SYS.Python  ; <module 'geopy' from 'c:\\intersystems\\iris\\mgr\\python\\geopy\\__init__.py'>  ; <OREF>