Open Exchange App Python Gateway Part II: Installation

This series of articles would cover Python Gateway for InterSystems Data Platforms. Execute Python code and more from InterSystems IRIS. This project brings you the power of Python right into your InterSystems IRIS environment:

  • Execute arbitrary Python code
  • Seamlessly transfer data from InterSystems IRIS into Python
  • Build intelligent Interoperability business processes with Python Interoperability Adapter
  • Save, examine, modify and restore Python context from InterSystems IRIS

Other articles

The plan for the series so far (subject to change).

  • Part I: Overview, Landscape and Introduction
  • Part II: Installation and Troubleshooting <-- you're here
  • Part III: Basic functionality
  • Part IV: Interoperability Adapter
  • Part V: Execute function
  • Part VI: Dynamic Gateway
  • Part VII: Proxy Gateway
  • Part VIII: Use cases and ML Toolkit

Installation

This article will help you with installing the Python Gateway.
The are several ways to install and use Python Gateway:

  • Host
    • Windows
    • Linux
    • Mac
  • Docker
    • Pull prebuilt image
    • Build your own image

Regardless of installation method, you'll need the code. The only place to download the code is releases page. It contains tested stable releases, just get the latest one. Currently it's 0.7 but there would be newer ones in the future. Don't clone/download the repository, download latest release.

Host

If you're installing Python Gateway on your host operating system, first (regardless of operating system) you need to install Python.

  1. Install Python 3.6.7 64 bit. It's recommended to install Python into default suggested location.
  2. Install dill module: pip install dill.
  3. Load ObjectScript code (i.e. do $system.OBJ.ImportDir("C:\InterSystems\Repos\Python\isc\py\","*.cls","c",,1)) into Production (Ensemble-enabled) namespace. In case you want to Production-enable existing namespace call: write ##class(%EnsembleMgr).EnableNamespace($Namespace, 1).
  4. Place callout DLL/SO/DYLIB in the bin folder of your InterSystems IRIS installation. Library file should be placed into a path returned by write ##class(isc.py.Callout).GetLib().

Windows

  1. Check that your PYTHONHOME environment variable points to Python 3.6.7.
  2. Check that your SYSTEM PATH environment variable has PYTHONHOME variable (or directory it points to).

Linux

  1. Check that your SYSTEM PATH environment variable has /usr/lib and /usr/lib/x86_64-linux-gnu, preferably at the beginning. Use /etc/environment file to set environment variables.
  2. In cause of errors check Troubleshooting section undefined symbol: _Py_TrueStruct and specify PythonLib property.

Mac

  1. Only python 3.6.7 from Python.org is currently supported. Check PATH variable.

If you modified environment variables restart your InterSystems product.

Docker

There are many advantages to using containers:
- Portability
- Efficiency
- Isolation
- Lightweight
- Immutability

Check this series of articles for more info on Docker.

All Python Gateway docker builds are based on 2019.1 containers.

Pull prebuilt image

Execute: docker run -d -p 52773:52773 --name irispy intersystemscommunity/irispy:latest to pull and run Python Gateway on top of InterSystems IRIS Community Edition. That's it.

Build your own image

To build docker image execute in the repository root: docker build --force-rm --tag intersystemscommunity/irispy:latest .
By default the image is built upon intersystems/iris:2019.1.0.510.0-1 image, however you can change that by providing IMAGE variable.
To build from InterSystems IRIS Community Edition execute: docker build --build-arg IMAGE=store/intersystems/iris:2019.1.0.510.0-community --force-rm --tag intersystemscommunity/irispy:latest .

After that you can run your docker image:

docker run -d \
  -p 52773:52773 \
  -v /<HOST-DIR-WITH-iris.key>/:/mount \
  --name irispy \
  intersystemscommunity/irispy:latest \
  --key /mount/iris.key

If you are running InterSystems IRIS Community Edition based image you can skip providing the key.

Docker notes

Some information about docker:

  • Test process isc.py.test.Process saves image artifact into temp directory. You might want to change that path to a mounted directory. To do that edit annotation for Correlation Matrix: Graph call, specifying valid filepath for f.savefig function.
  • For terminal access execute: docker exec -it irispy sh.
  • Access SMP with SuperUser/SYS or Admin/SYS user/password.
  • To stop container execute: docker stop irispy && docker rm --force irispy.

Validating your installation

After you've installed Python Gateway time to check that it works. Execute this code:

set sc = ##class(isc.py.Callout).Setup() 
set sc = ##class(isc.py.Main).SimpleString("x='HELLO'", "x", , .var)
write var

It should output HELLO - value of Python variable x. If returned status is an error or var is empty, check readme troubleshooting section.

Conclusion

Installing Python Gateway is fast and easy. If you're familiar with Docker get the latest image, otherwise there are kits for the main InterSystems IRIS operating systems: Windows, Linux and Mac. In the next article we would start using Python Gateway.

Illustrated guide

There's also illustrated installation guide in ML Toolkit user group. ML Toolkit user group is a private GitHub repository set up as part of InterSystems corporate GitHub organization. It is addressed to the external users that are installing, learning or are already using ML Toolkit components. To join ML Toolkit user group, please send a short e-mail at the following address: MLToolkit@intersystems.com and indicate in your e-mail the following details (needed for the group members to get to know and identify you during discussions):

  • GitHub username
  • Full Name (your first name followed by your last name in Latin script)
  • Organization (you are working for, or you study at, or your home office)
  • Position (your actual position in your organization, or “Student”, or “Independent”)
  • Country (you are based in)

Also, check the previous part Python Gateway Part I: Introduction