Skip to main content

%SYS.Python

Class %SYS.Python Extends %Library.SystemBase [ Final ]

Provides utilities for loading and using Python modules, running Python commands, and starting the Python shell. For information on working with Python within IRIS, see Using Embedded Python.

Parameters​

%MODULENAME​

Parameter %MODULENAME [ Internal ] = 13;

Properties​

ModDesc​

Property ModDesc As %CPP.LongLong [ Internal, Private ];

UID​

Property UID As %CPP.Integer [ Internal, Private ];

Methods​

Import​

ClassMethod Import(name As %String) As %CPP.LongLong [ Language = cpp ]

Loads a Python module and returns a handle to that module. On failure, this method returns 0. Typically you use this method to bind the module to a variable, which you then use to call code within the module. For example: set mypython = ##class(%SYS.Python).Import("package.subpackage.name") write mypython.helloWorld()

%DispatchGetProperty​

Method %DispatchGetProperty(name As %String) As %Integer [ Internal, Language = cpp ]

Get a python object attribute.

%DispatchSetProperty​

Method %DispatchSetProperty(propName As %Library.String, value As %Library.String) [ Internal, Language = cpp ]

Get a python object attribute.

Run​

ClassMethod Run(cmd As %String) As %Integer [ Language = cpp ]

Runs one or more Python commands; to run multiple commands, separate the commands with a new line, $char(10). This method returns 0 on success or -1 on failure.

Path​

ClassMethod Path() As %Integer [ Internal, Language = cpp ]

Get current run time setting for PythonPath, if a new value is specified it overwrites the run time value (used by config mgr).

ConfigureAutoML​

ClassMethod ConfigureAutoML(pathelement As %String) As %Integer [ Internal, Language = cpp ]

An API that affects just the current process. The specified string argument will be added to sys.path relative to the instance dir on the next load of embedded python. Without args, returns the current string. With a string argument, this also loads OS Default libpython after it sets sys.path. This API is used in IML classes with "lib/automl" to reflect where the numpy is in ML enabled kits. Blocks IML from working if a non default python is already in the process (Also see AllowAutoML() ).

AllowAutoML​

ClassMethod AllowAutoML(allow As %Integer) As %Integer [ Internal, Language = cpp ]

Set an integer in system memory. Without args, return the current integer. If the integer is 1, AutoML ( ConfigureAutoML() ) will be allowed to start trying to run a non default python like the one in the CPF, for example. This is quite likely to result in AutoML errors unless what you are doing has been integrated by Intersystems.

IRISInsidePython​

ClassMethod IRISInsidePython() As %Integer [ Internal, Language = cpp ]

FT counter of irispython activations

PythonInsideIRIS​

ClassMethod PythonInsideIRIS() As %Integer [ Internal, Language = cpp ]

FT counter of libpython.so/.dll activations

IrisPlatform​

ClassMethod IrisPlatform() As %String [ Language = cpp ]

Returns platform (kit) identifier used in creation of IRIS kits and also in EP iris_site.py

GetPythonInfo​

ClassMethod GetPythonInfo(ByRef info) As %Integer

Returns descriptive general information about process and system wide python and python related CPF settings. Informational names/API compatibility not guaranteed.

GetPythonVersion​

ClassMethod GetPythonVersion() As %String

Returns descriptive version information about the python currently loaded in the process. Example: "3.10.12 (main, Jun 11 2023, 05:26:28) [GCC 11.4.0]" on Ubuntu 22. If python is not loaded it will return "Not Loaded". Does not Load Python.

GetCompileTimeVersion​

ClassMethod GetCompileTimeVersion() As %Integer [ Internal, Language = cpp ]

Returns short form python version present on the build machine used to compile IRIS

GetCompileTimeVersionFull​

ClassMethod GetCompileTimeVersionFull() As %Integer [ Internal, Language = cpp ]

Returns full form python version present on the build machine used to compile IRIS

GetCompileTimePath​

ClassMethod GetCompileTimePath() As %Integer [ Internal, Language = cpp ]

Returns python runtime library path on the build machine used to compile IRIS

PythonRuntimeLibraryVersion​

ClassMethod PythonRuntimeLibraryVersion(location As %String) As %Integer [ Internal, Language = cpp ]

Version of Python used by PythonRuntimeLibrary in Major.Minor format: 3.9, 3.11, etc.
Used in properly loading PythonRuntimeLibrary into IRIS.

PythonRuntimeLibrary​

ClassMethod PythonRuntimeLibrary(location As %String) As %Integer [ Internal, Language = cpp ]

The full path (including library name) of the alternate python that you want IRIS to use in %SYS.Python.Shell() and [Language=python] for all new processes.
For example, if you install the optional python 3.11 on Ubuntu 20.04 use:
/lib/x86_64-linux-gnu/libpython3.11.so.1.0
If you install the optional python 3.8 on RH 7.9 use:
/opt/rh/rh-python38/root/usr/lib64/libpython3.8.so
If you do not use a setting here, you'll get the default OS vendor system python.

GetRunningLibrary​

ClassMethod GetRunningLibrary() As %Integer [ Internal, Language = cpp ]

After libpython has been loaded, by whatever means, this returns the actual libpython in use by this process.

PerProcessRuntimeLibrarySet​

ClassMethod PerProcessRuntimeLibrarySet(location As %String) As %Integer [ Internal, Language = cpp ]

Use this to specify what libpython you want to be loaded for just this process by a future PerProcessRuntimeLibraryStart("UserPerProcess") call. Without arguments, it returns the value that you previously set.

PerProcessRuntimeLibraryStart​

ClassMethod PerProcessRuntimeLibraryStart(mode As %String) As %Integer [ Internal, Language = cpp ]

Loads libpython into the current process
"UserPerProcess" will load the libpython you specified with PerProcessLibpythonSet()
"UserSystemWide" will load the libpython you specified with PythonRuntimeLibrary()
"CPF" will load the libpython you specified in the CPF
"OSDefault" will load the default libpython of the OS vendor that was compiled into IRIS
Any other argument acts as "OSDefault"
Without args it returns current flag (a number)

PerProcessRuntimeLibrarySetPathElement​

ClassMethod PerProcessRuntimeLibrarySetPathElement(element As %String) As %Integer [ Internal, Language = cpp ]

Set a string in process memory. Without args, return the current string. When libpython loads in the future, the specified string will be added to sys.path.

PerProcessRuntimeLibrarySetRelativePathElement​

ClassMethod PerProcessRuntimeLibrarySetRelativePathElement(element As %String) As %Integer [ Internal, Language = cpp ]

Set a string in process memory. Without args, return the current string. When libpython loads in the future, the specified string will be added to sys.path relative to the instance dir.

Bytes​

ClassMethod Bytes(cmd As %String) As %CPP.LongLong [ Language = cpp ]

Given an ObjectScript string, returns a Python object of type bytes. The input string cannot contain any wide character.

CallInInit​

ClassMethod CallInInit() [ Internal, Language = cpp ]

An internal methods, finish "callin" initialization

None​

ClassMethod None() As %CPP.LongLong [ Language = cpp ]

Returns the Python **None** value.

True​

ClassMethod True() As %CPP.LongLong [ Language = cpp ]

Returns the Python **True** value.

False​

ClassMethod False() As %CPP.LongLong [ Language = cpp ]

Returns the Python **False** value.

Validate​

ClassMethod Validate() As %Integer [ Internal, Language = cpp ]

Validate the internal state session, returns the number of active python objs. return - if python is not inited or an invalid object is found.

ChangeSignalState​

ClassMethod ChangeSignalState(state As %Integer) As %Integer [ Internal, Language = cpp ]

Set the signal handling state 0 - swap, 1 - disable swapping iris will notify, to python signal handling

Debugging​

ClassMethod Debugging(state As %Integer) As %Integer [ Internal, Language = cpp ]

If passed true, it doesn't reset the error context before invoking any python feature (enable this before invoking any pdb method).

Builtins​

ClassMethod Builtins(flags As %Integer) As %CPP.LongLong

Loads the Python builtins module and returns a handle to that module. On failure, this method returns 0. Using this method is equivalent to using Import to load the Python builtins module.

SetStdIOMode​

ClassMethod SetStdIOMode(flags As %Integer) As %Integer [ Internal, Language = cpp ]

if flags bit 1 is set, the stderr (fd 2) output will be redirected to stdout (fd 1) if there is a current COS primary device, otherwise it will behave the original way and log it in messages.log

Install​

ClassMethod Install(packages As %String, dir As %String = "") As %Status [ Internal ]

This is deprecated. Please use the pip3 command line to install packages.

Shell​

ClassMethod Shell(vars As %Integer = 0) As %Status

Starts the interactive Python shell. To use this method, you must have USE permission on the %Developer resource. To exit the shell, type the command quit()

If vars is 1, then any OREF variables present in the ObjectScript shell are also available in the Python shell; the reverse is not true.

SetInteractiveMode​

ClassMethod SetInteractiveMode(state As %Integer) As %Integer

Set the mode of python to Interactive meaning that signal handling state swaps will be allowed. Interactive mode has a performance cost, but enables useful features like saving/restoring terminal state and generating better documentation. Returns previous signal state: 0 - swapping allowed, 1 - swapping disabled, -1 - Swapping unapplicable to your platform.

ToListTyped​

ClassMethod ToListTyped(contentList As %CPP.BinList, typeList As %CPP.BinList) As %CPP.LongLong [ Language = cpp ]

Given two ObjectScript lists, returns a Python list that contains the same data as contentList, with each member of the list having the data type specified in typeList. For example, the following code returns a Python list where each member of the list has the value 42, but is represented as ODBCTYPEbit(SQLBIT), ODBCTYPEnumeric(SQLNUMERIC), ODBCTYPEdecimal(SQLDECIMAL), and ODBCTYPEinteger(SQLINTEGER), respectively. More info on the type values can be found in %occODBC.inc as well as:
the docs

Include %occODBC set clist = $lb(42, 42, 42, 42) set tlist = $lb(-7, 2, 3, 4) [or] set tlist = $lb($$$ODBCTYPEbit,$$$ODBCTYPEnumeric,$$$ODBCTYPEdecimal,$$$ODBCTYPEinteger) set plist = ##class(%SYS.Python).ToListTyped(clist, tlist)
This type translation obeys Intersystems SQL Rules, so for the string and binary ODBC types, $C(0) will turn into Python "". For all ODBC types, $lb(,"") will be 2 Python "None" elements.

To2DListTyped​

ClassMethod To2DListTyped(contentList As %Integer, typeList As %Integer) As %CPP.LongLong [ Internal, Language = cpp ]

Takes in a 2D ObjectScript $LIST, and another $LIST with type info for each column in the first $LIST.
Returns a copy of the first $LIST as a python list with matching python types.

The types are the same as for ToListTyped.
set plist = $system.Python.To2DListTyped($lb($lb("philip",21,"electrician"),$lb("mary",22,"plumber")), $lb(12,4,12))

ToList​

ClassMethod ToList(contentList As %CPP.BinList) As %CPP.LongLong [ Language = cpp ]

Given contentList (an ObjectScript list), this method returns a Python list that contains the same data. For example: set clist = $lb(123, 456.789, "hello world") set plist = ##class(%SYS.Python).ToList(clist)
Warning:
Don't pass binary data via this API, Use ToListTyped with one of the binary ODBC types instead.
If you put binary data in this API, IRIS will try to translate it as a UTF8 string.