Skip to main content

Native SDK for Python Quick Reference

This is a quick reference for the InterSystems IRIS Native SDK for Python, providing information on the following classes:

Typecast Methods and Supported Datatypes

The Native SDK supports datatypes bool, bytes, bytearray, Decimal, float, int, str IRISList, and None.

In many cases, a class will have a generic method (frequently named get()) that returns a default value type, plus a set of typecast methods that work exactly like the generic method but also cast the return value to a specific datatype. For example, IRIS.get() is followed by typecast methods getBoolean(), getBytes(), and so forth.

To avoid lengthening this quick reference with dozens of nearly identical listings, all typecast methods are listed collectively after the generic version (for example, IRIS.get() Typecast Methods).

Sets of typecast methods are available for IRIS.classMethodValue(), IRIS.function(), IRIS.get(), IRISList.get(), IRISObject.get(), IRISObject.invoke(), and IRISReference.getValue().

iris Package Methods

The iris package includes method connect() for creating a connection, and createIris() for creating a new instance of class IRIS that uses the connection. A connected instance of iris.IRIS is required to use the Native SDK.

Creating a Connection in Python

The following code demonstrates how to open a database connection and create an instance of iris.IRIS named irispy. Most examples in this document will assume that a connected instance of irispy already exists.

import iris

# Open a connection to the server
args = {'hostname':'127.0.0.1', 'port':52773,
    'namespace':'USER', 'username':'_SYSTEM', 'password':'SYS'
}
conn = iris.connect(**args)
# Create an iris object
irispy = iris.createIRIS(conn)

See the following section for detailed information about iris.connect() and iris.createIRIS().

iris Package Method Details

connect()

iris.connect() returns a new IRISConnection object and attempts to create a new connection to the database. The object will be open if the connection was successful. Throws an exception if a connection cannot be established.

  iris.connect(hostname,port,namespace,username,password,timeout,sharedmemory,logfile)
  iris.connect(connectionstr,username,password,timeout,sharedmemory,logfile)

The hostname, port, namespace, timeout, and logfile from the last successful connection attempt are saved as properties of the connection object.

parameters:

Parameters may be passed by position or keyword.

  • hostnamestr specifying the server URL

  • portint specifying the superserver port number

  • namespacestr specifying the namespace on the server

  • The following parameter can be used in place of the hostname, port, and namespace arguments:

    • connectionstrstr of the form hostname:port/namespace.

  • usernamestr specifying the user name

  • passwordstr specifying the password

  • timeout (optional) — int specifying maximum number of milliseconds to wait while attempting the connection. Defaults to 10000.

  • sharedmemory (optional) — specify bool True to attempt a shared memory connection when the hostname is localhost or 127.0.0.1. Specify False to force a connection over TCP/IP. Defaults to True.

  • logfile (optional) — str specifying the client-side log file path. The maximum path length is 255 ASCII characters.

createIRIS()

iris.createIRIS() returns a new instance of IRIS that uses the specified IRISConnection. Throws an exception if the connection is closed.

    iris.createIRIS(conn)

returns: a new instance of iris.IRIS

parameter:

  • conn — an IRISConnection object that provides the server connection

Class iris.IRIS

To use the Native SDK, your application must create an instance of IRIS with a connection to the database. Instances of IRIS are created by calling iris package method createIris().

IRIS Method Details

classMethodValue()

IRIS.classMethodValue() calls a class method, passing zero or more arguments and returns the value as a type corresponding to the datatype of the ObjectScript return value. Returns None if the ObjectScript return value is an empty string ($$$NULLOREF). See “Calling Class Methods from Python” for details and examples.

  classMethodValue (className, methodName, args)

returns: bool, bytes, bytes, int, float, Decimal, str IRISList, or None. See classMethodValue() Typecast Methods for ways to return a specific type.

parameters:

  • class_name — fully qualified name of the class to which the called method belongs.

  • method_name — name of the class method.

  • *args — zero or more method arguments. Arguments of types bool, bytes, Decimal, float, int, str and IRISList are projected as literals. All other types are projected as proxy objects.

Also see classMethodVoid(), which is similar to classMethodValue() but does not return a value.

classMethodValue() Typecast Methods

All of the IRIS.classMethodValue() typecast methods listed below work exactly like IRIS.classMethodValue(), but also cast the return value to a specific type. They all return None if the ObjectScript return value is an empty string ($$$NULLOREF). See “Calling Class Methods from Python” for details and examples.

  classMethodBoolean (className, methodName, args)
  classMethodBytes (className, methodName, args)
  classMethodDecimal (className, methodName, args)
  classMethodFloat (className, methodName, args)
  classMethodInteger (className, methodName, args)
  classMethodIRISList (className, methodName, args)
  classMethodString (className, methodName, args)
  classMethodObject (className, methodName, args)

returns: bool, bytes, bytes, int, float, Decimal, str IRISList, Object, or None.

parameters:

  • class_name — fully qualified name of the class to which the called method belongs.

  • method_name — name of the class method.

  • *args — zero or more method arguments of supported types. Arguments of types bool, bytes, Decimal, float, int, str and IRISList are projected as literals. All other types are projected as proxy objects.

Also see classMethodVoid(), which is similar to classMethodValue() but does not return a value.

classMethodVoid()

IRIS.classMethodVoid() calls an ObjectScript class method with no return value, passing zero or more arguments. See “Calling Class Methods from Python” for details and examples.

   classMethodVoid (className, methodName, args) 

parameters:

  • class_name — fully qualified name of the class to which the called method belongs.

  • method_name — name of the class method.

  • *args — zero or more method arguments of supported types. Arguments of types bool, bytes, Decimal, float, int, str and IRISList are projected as literals. All other types are projected as proxy objects.

This method assumes that there will be no return value, but can be used to call any class method. If you use classMethodVoid() to call a method that returns a value, the method will be executed but the return value will be ignored.

close()

IRIS.close() closes the IRIS object.

  close () 
function()

IRIS.function() calls a function, passing zero or more arguments and returns the value as a type corresponding to the datatype of the ObjectScript return value. Returns None if the ObjectScript return value is an empty string ($$$NULLOREF). See “Calling Functions and Procedures from Python” for details and examples.

  function (functionName, routineName, args) 

returns: bool, bytes, bytes, int, float, Decimal, str IRISList, Object, or None. See function() Typecast Methods for ways to return a specific type.

parameters:

  • function_name — name of the function to call.

  • routine_name — name of the routine containing the function.

  • *args — zero or more method arguments of supported types. Arguments of types bool, bytes, Decimal, float, int, str and IRISList are projected as literals. All other types are projected as proxy objects.

Also see procedure(), which is similar to function() but does not return a value.

function() Typecast Methods

All of the IRIS.function() typecast methods listed below work exactly like IRIS.function(), but also cast the return value to a specific type. They all return None if the ObjectScript return value is an empty string ($$$NULLOREF). See “Calling Functions and Procedures from Python” for details and examples.

  functionBoolean (functionName, routineName, args)
  functionBytes (functionName, routineName, args)
  functionDecimal (functionName, routineName, args)
  functionFloat (functionName, routineName, args)
  functionInteger (functionName, routineName, args)
  functionIRISList (functionName, routineName, args)
  functionString (functionName, routineName, args)
  functionObject (functionName, routineName, args) 

returns: bool, bytes, bytes, int, float, Decimal, str IRISList, Object, or None

parameters:

  • function_name — name of the function to call.

  • routine_name — name of the routine containing the function.

  • *args — zero or more method arguments of supported types. Arguments of types bool, bytes, Decimal, float, int, str and IRISList are projected as literals. All other types are projected as proxy objects.

Also see procedure(), which is similar to function() but does not return a value.

get()

IRIS.get() returns the value of the global node as a type corresponding to the ObjectScript datatype of the property. Returns None if the node is an empty string, is valueless, or does not exist.

  get (globalName, subscripts) 

returns: bool, bytes, int, float, Decimal, str IRISList, Object, or None. See get() Typecast Methods for ways to return other types.

parameters:

  • global_name — global name

  • *subscripts — zero or more subscripts specifying the target node

get() Typecast Methods

All of the IRIS.get() typecast methods listed below work exactly like IRIS.get(), but also cast the return value to a specific type. They all return None if the node is an empty string, is valueless, or does not exist.

  getBoolean (globalName, subscripts)
  getBytes (globalName, subscripts)
  getDecimal (globalName, subscripts)
  getFloat (globalName, subscripts)
  getInteger (globalName, subscripts)
  getIRISList (globalName, subscripts)
  getString (globalName, subscripts)
  getObject (globalName, subscripts)

returns: bool, bytes, int, float, Decimal, str IRISList, Object, or None

parameters:

  • global_name — global name

  • *subscripts — zero or more subscripts specifying the target node

Also see deprecated typecast method getLong().

getAPIVersion() [static]

IRIS.getAPIVersion() returns the version string for this version of the Native SDK. Also see getServerVersion().

  getAPIVersion () 

returns: str

getLong() [deprecated]

IRIS.getLong() The Python long type is no longer required in Python 3. Please use IRIS.get() typecast method getInteger(), which supports the same precision.

getServerVersion()

IRIS.getServerVersion() returns the version string for the currently connected InterSystems IRIS server. Also see getAPIVersion().

  getServerVersion () 

returns: str

getTLevel()

IRIS.getTLevel() returns the number of nested transactions currently open in the session (1 if the current transaction is not nested, and 0 if there are no transactions open). This is equivalent to fetching the value of the ObjectScript $TLEVEL special variable. See “Processing Transactions in Python” for details and examples.

  getTLevel () 

returns: int

increment()

IRIS.increment() increments the global node with the value argument and returns the new value of the global node. If there is no existing node at the specified address, a new node is created with the specified value. This method uses a very fast, thread-safe atomic operation to change the value of the node, so the node is never locked. See “Processing Transactions in Python” for details and examples.

  increment (value, globalName, subscripts) 

returns: float

parameters:

  • valueint or float number to increment by

  • global_name — global name

  • *subscripts — zero or more subscripts specifying the target node

Common usage for $INCREMENT is to increment a counter before adding a new entry to a database. $INCREMENT provides a way to do this very quickly, avoiding the use of the LOCK command. See “$INCREMENT and Transaction Processing” in the ObjectScript Reference.

isDefined()

IRIS.isDefined() returns a value that indicates whether a node has a value, a child node, or both.

  isDefined (globalName, subscripts)

returns: one of the following int values:

  • 0 if the node does not exist.

  • 1 if the node has a value but no child nodes.

  • 10 if the node is valueless but has one or more child nodes.

  • 11 if it has a both a value and child nodes.

parameters:

  • global_name — global name

  • *subscripts — zero or more subscripts specifying the target node

iterator() [deprecated]

IRIS.iterator() is deprecated; use node() instead. See Class iris.LegacyIterator for information about continued functionality in existing applications.

kill()

IRIS.kill() deletes the specified global node and all of its subnodes. If there is no node at the specified address, the command will do nothing. It will not throw an <UNDEFINED> exception.

  kill (globalName, subscripts) 

parameters:

  • global_name — global name

  • *subscripts — zero or more subscripts specifying the target node

lock()

IRIS.lock() locks the global. This method performs an incremental lock (you must call the releaseAllLocks() method first if you want to unlock all prior locks). Throws a <TIMEOUT> exception if the timeout value is reached waiting to acquire the lock. See “Concurrency Control with Python” for more information.

  lock (lock_mode, timeout, lock_reference, subscripts) 

parameters:

  • lock_mode — one of the following strings: "S" for shared lock, "E" for escalating lock, "SE" for both, or "" for neither. An empty string is the default mode (unshared and non-escalating).

  • timeout — number of seconds to wait to acquire the lock

  • lock_reference — a string starting with a circumflex (^) followed by the global name (for example, ^myGlobal, not just myGlobal).

    NOTE: Unlike the global_name parameter used by most methods, the lock_reference parameter must be prefixed by a circumflex. Only lock() and unlock() use lock_reference instead of global_name.

  • *subscripts — zero or more subscripts specifying the target node

See “LOCK” in the ObjectScript Reference for detailed information on locks.

nextSubscript()

IRIS.nextSubscript() accepts a node address and returns the subscript of the next sibling node in collation order. Returns None if there are no more nodes in the specified direction. This method is similar to $ORDER in ObjectScript.

  nextSubscript (reversed, globalName, subscripts) 

returns: bytes, int, str, or float (next subscript in the specified direction)

parameters:

  • reversed — boolean true indicates that nodes should be traversed in reverse collation order.

  • global_name — global name

  • *subscripts — zero or more subscripts specifying the target node

Also see node(), which returns an object that iterates over children of a specified node (unlike nextSubscript(), which allows you to iterate over nodes on the same level as the specified node).

node()

IRIS.node() returns an IRISGlobalNode object that allows you to iterate over children of the specified node. An IRISGlobalNode behaves like a virtual dictionary representing the immediate children of a global node. It is iterable, reversable, indexable and sliceable.

def  node (self, globalName, subscripts) 

parameters:

  • global_name — global name

  • *subscripts — zero or more subscripts specifying the target node

Also see nextSubscript(), which allows you to iterate over nodes on the same level as the specified node (unlike node(), which iterates over children of a specified node).

procedure()

IRIS.procedure() calls an ObjectScript procedure or function, passing zero or more arguments and returning nothing (also see IRIS.function()). See “Calling Functions and Procedures from Python” for details and examples.

  procedure (procedureName, routineName, args) 

parameters:

  • procedureName — name of the procedure to call.

  • routine_name — name of the routine containing the procedure.

  • *args — zero or more method arguments. Arguments of types bool, bytes, Decimal, float, int, str and IRISList are projected as literals. All other types are projected as proxy objects.

This method assumes that there will be no return value, but can be used to call any function. If you use procedure() to call a function that returns a value, the function will be executed but the return value will be ignored.

releaseAllLocks()

IRIS.releaseAllLocks() releases all locks associated with the session. See “Concurrency Control with Python” for more information.

  releaseAllLocks () 
set()

IRIS.set() assigns value as the current node value. The new value may be bool, bytes, bytearray, Decimal, float, int, str, or IRISList,.

  set (value, globalName, subscripts) 

parameters:

  • value — new value of the global node

  • global_name — global name

  • *subscripts — zero or more subscripts specifying the target node

tCommit()

IRIS.tCommit() commits the current transaction. See “Processing Transactions in Python” for details and examples.

  tCommit () 
tRollback()

IRIS.tRollback() rolls back all open transactions in the session. See “Processing Transactions in Python” for details and examples.

  tRollback () 
tRollbackOne()

IRIS.tRollbackOne() rolls back the current level transaction only. This is intended for nested transactions, when the caller only wants to roll back one level. If this is a nested transaction, any higher-level transactions will not be rolled back. See “Processing Transactions in Python” for details and examples.

  tRollbackOne () 
tStart()

IRIS.tStart() starts or opens a transaction. See “Processing Transactions in Python” for details and examples.

  tStart () 
unlock()

IRIS.unlock() decrements the lock count on the specified lock, and unlocks it if the lock count is 0. To remove a shared or escalating lock, you must specify the appropriate lockMode ("S" for shared, "E" for escalating lock). See “Concurrency Control with Python” for more information.

  unlock (lock_mode, lock_reference, subscripts) 

parameters:

  • lock_mode — one of the following strings: "S" for shared lock, "E" for escalating lock, "SE" for both, or "" for neither. An empty string is the default mode (unshared and non-escalating).

  • lock_reference — a string starting with a circumflex (^) followed by the global name (for example, ^myGlobal, not just myGlobal).

    NOTE: Unlike the global_name parameter used by most methods, the lock_reference parameter must be prefixed by a circumflex. Only lock() and unlock() use lock_reference instead of global_name.

  • *subscripts — zero or more subscripts specifying the target node

Class iris.IRISList

Class iris.IRISList implements a Python interface for InterSystems $LIST serialization. IRISList is a Native SDK supported type (see “Typecast Methods and Supported Datatypes”).

IRISList Constructors

The IRISList constructor takes the following parameters:

  IRISList(buffer = None, locale = "latin-1", is_unicode = True, compact_double = False)

parameters:

  • buffer — optional list buffer, which can be an instance of IRISList or a byte array in $LIST format (returned by Native SDK methods such as IRIS.getBytes()).

  • locale — optional str indicating locale setting for buffer.

  • is_unicode — optional bool indicating if buffer is Unicode.

  • compact_double — optional bool indication if compact doubles are enabled.

Instances of IRISList can be created in the following ways:

  • Create an empty IRISList

      list = IRISList()
  • Create a copy of another IRISList

      listcopy = IRISList(myOtherIRISList)
  • Construct an instance from a $LIST formatted byte array, such as that returned by IRIS.getBytes() and numerous other iris methods.

      globalBytes = myIris.getBytes("myGlobal",1)
      listFromByte = IRISList(globalBytes)

Many methods in the iris package return IRISList, which is one of the Native SDK supported types.

IRISList Method Details

add()

IRISList.add() appends a value to the end of the IRISList and returns the IRISList object.

  add (value) 

returns: self (the IRISList object)

parameters:

  • value — a value of any supported type, or an array or collection of values. Each element of an array or collection will be appended individually. Instances of IRISList are always appended as a single element.

The add() method never concatenates two instances of IRISList. However, you can use IRISList.toArray() to convert an IRISList to an array. Calling add() on the resulting array will append each element separately.

clear()

IRISList.clear() resets the list by removing all elements from the list, and returns the IRISList object.

  clear () 

returns: self (the IRISList object)

count()

IRISList.count() returns the number of data elements in the list.

  count () 

returns: int

equals()

IRISList.equals() compares the specified irislist2 with this instance of IRISList, and returns true if they are identical. To be equal, both lists must contain the same number of elements in the same order with identical serialized values.

  equals (irislist2) 

returns: bool

parameters:

  • irislist2 — instance of IRISList to compare.

get()

IRISList.get() moves the list cursor to the specified index (if one is specified) and returns the element at the cursor as an Object. Throws IndexOutOfBoundsException if the index is out of range (less then 1 or past the end of the list). Returns None if

  get (index) 

returns: bool, bytes, bytes, int, float, Decimal, str IRISList, Object, or None

parameters:

  • index — optional int specifying the index (one-based) of the new cursor location

get() Typecast Methods

All of the IRISList.get() typecast methods listed below work exactly like IRISList.get(), but also cast the return value to a specific type. They all throw IndexOutOfBoundsException if the index is out of range (less then 1 or past the end of the list).

  getBoolean (index)
  getBytes (index)
  getDecimal (index)
  getFloat (index)
  getInteger (index)
  getIRISList (index)
  getString (index) 

returns: bool, bytes, bytes, int, float, Decimal, str IRISList, Object, or None

parameters:

  • index — optional int specifying the index (one-based) of the new cursor location

remove()

IRISList.remove() removes the element at index from the list and returns the IRISList object.

  remove (index) 

returns: self (the IRISList object)

parameters:

  • indexint specifying the index (one-based) of the element to remove

set()

IRISList.set() replaces the list element at index with value and returns the IRISList object.

If value is an array, each array element is inserted into the list, starting at index, and any existing list elements after index are shifted to make room for the new values.

If index is beyond the end of the list, value will be stored at index and the list will be padded with nulls up to that position. Throws IndexOutOfBoundsException if index is less than 1.

  set (index, value) 

returns: self (the IRISList object)

parameters:

  • indexint specifying the index (one-based) of the list element to be set

  • valueObject value or Object array to insert at index. Objects can be any supported type.

size()

IRISList.size() returns the byte length of the serialized value for this IRISList.

  size () 

returns: int

Class iris.IRISConnection

Instances of IRISConnection are created by calling package method iris.connect(). See “iris Package Methods” for details about creating and using connections.

close()

IRISConnection.close() closes the connection to the iris instance if it is open. Does nothing if the connection is already closed.

   connection.close()

returns: self

isClosed()

IRISConnection.isClosed() returns True if the connection was successful, or False otherwise.

   connection.isClosed()

returns: bool

isUsingSharedMemory()

IRISConnection.isUsingSharedMemory() returns True if the connection is open and using shared memory.

   connection.isUsingSharedMemory()

returns: bool

Properties

The hostname, port, namespace, timeout, and logfile from the last successful connection attempt are saved as properties of the connection object.

Class iris.IRISObject

Class iris.IRISObject provides methods to work with External Server inverse proxy objects (see “Using Python Inverse Proxy Objects” for details and examples).

If the called method or function returns an object that is a valid OREF, an inverse proxy object (an instance of IRISObject) for the referenced object will be generated and returned. For example, classMethodObject() will return a proxy object for an object created by %New(). also true of classMethodValue????

IRISObject Constructor

The IRISObject constructor takes the following parameters:

  IRISObject(connection, oref)

parameters:

  • connection — an IRISConnection object

  • oref — the OREF of the database object to be controlled.

IRISObject Method Details

close()

IRISObject.close() releases this instance of IRISObject.

  close () 

returns: self

get()

IRISObject.get() fetches a property value of the proxy object. Returns None for IRIS empty string ($$$NULLOREF); otherwise, returns a variable of a type corresponding to the ObjectScript datatype of the property.

  get (propertyName)  

returns: bool, bytes, bytes, int, float, Decimal, str IRISList, Object, or None

parameters:

  • property_name — name of the property to be returned.

get() Typecast Methods

All of the IRISObject.get() typecast methods listed below work exactly like IRISObject.get(), but also cast the return value to a specific type. They all return None for IRIS empty string ($$$NULLOREF), and otherwise return a value of the specified type.

  getBoolean (propertyName)
  getBytes (propertyName)
  getDecimal (propertyName)
  getFloat (propertyName)
  getInteger (propertyName)
  getIRISList (propertyName)
  getString (propertyName)
  getObject (propertyName)

returns: bool, bytes, bytes, int, float, Decimal, str IRISList, Object, or None

parameters:

  • property_name — name of the property to be returned.

getConnection()

IRISObject.getConnection() returns the current connection as an IRISConnection object.

  getConnection ()

returns: an IRISConnection object

getOREF()

IRISObject.getOREF() returns the OREF of the database object mapped to this IRISObject.

  getOREF ()

returns: OREF

invoke()

IRISObject.invoke() invokes an instance method of the object, returning a variable of a type corresponding to the ObjectScript datatype of the property.

  invoke (methodName, args) 

returns: bool, bytes, bytes, int, float, Decimal, str IRISList, Object, or None

parameters:

  • method_name — name of the instance method to be called.

  • *args — zero or more arguments of supported types.

Also see invokeVoid(), which is similar to invoke() but does not return a value.

invoke() Typecast Methods

All of the IRISObject.invoke() typecast methods listed below work exactly like IRISObject.invoke(), but also cast the return value to a specific type. They all return None for IRIS empty string ($$$NULLOREF), and otherwise return a value of the specified type.

  invokeBoolean (methodName, args)
  invokeBytes (methodName, args)
  invokeDecimal (methodName, args)
  invokeFloat (methodName, args)
  invokeInteger (methodName, args)
  invokeIRISList (methodName, args)
  invokeString (methodName, args)
  invokeObject (methodName, args) 

returns: bool, bytes, bytes, int, float, Decimal, str IRISList, Object, or None

parameters:

  • method_name — name of the instance method to be called.

  • *args — zero or more arguments of supported types.

Also see invokeVoid(), which is similar to invoke() but does not return a value.

invokeVoid()

IRISObject.invokeVoid() invokes an instance method of the object, but does not return a value.

  invokeVoid (methodName, args) 

parameters:

  • method_name — name of the instance method to be called.

  • *args — zero or more arguments of supported types.

set()

IRISObject.set() sets a property of the proxy object.

  set (propertyName, propertyValue)

parameters:

  • property_name — name of the property to which value will be assigned.

  • value — property value to assign. Value can be any supported type.

Class iris.IRISReference

The iris.IRISReference class provides a way to use pass-by-reference arguments when calling database classmethods. See “Passing Arguments by Reference” for details and examples.

IRISReference Constructor

The IRISReference constructor takes the following parameters:

  IRISReference(value, type = None)

parameters:

  • value — initial value of the referenced argument.

  • type — optional Python type used as a type hint for unmarshaling modified value of the argument. Supported types are bool, bytes, bytearray, Decimal, float, int, str IRISList, or None. If None is specified, uses the type that matches the original database type

IRISReference Method Details

get_type() [deprecated]

IRISReference.get_type() is deprecated. Use one of the getValue() Typecast Methods to get a return value of the desired type.

  get_type () 
get_value() [deprecated]

IRISReference.get_value() is deprecated. Use getValue() or the getObject() typecast method instead.

getValue()

IRISReference.getValue() returns the value of the referenced parameter as a type corresponding to the datatype of the database value.

  getValue () 

returns: value of the referenced parameter

getValue() Typecast Methods

All of the IRISReference.getValue() typecast methods listed below work exactly like IRISReference.getValue(), but also cast the return value to a specific type.

  getBoolean ()
  getBytes ()
  getDecimal ()
  getFloat ()
  getInteger ()
  getIRISList ()
  getString ()
  getObject () 

returns: bool, bytes, bytes, int, float, Decimal, str IRISList, Object, or None

set_type() [deprecated]

IRISReference.set_type() is deprecated. There is an option to set the type when calling the IRISReference constructor.

  set_type (type) 
setValue()

IRISReference.setValue() sets the value of the referenced argument.

  setValue (value) 

parameters:

  • value — value of this IRISReference object

set_value() [deprecated]

IRISReference.set_value() is deprecated. Use setValue() instead.

Class iris.IRISGlobalNode

IRISGlobalNode provides an iterable interface that behaves like a virtual dictionary representing the immediate children of a global node. It is iterable, sliceable, reversible, and indexable, with support for views and membership tests.

  • IRISGlobalNode supports an iterable interface:

    For example, the following for loop will list the subscripts of all child nodes:

    for x in node:
        print(x)
  • IRISGlobalNode supports views:

    Methods keys(), subscripts(), values(), items(), and nodes() return IRISGlobalNodeView view objects. They provide specific views on the IRISGlobalNode entries which can be iterated over to yield their respective data, and they support membership tests. For example, the items() method returns a view object containing a list of subscript-value pairs:

    for sub, val in node.items():
        print('subscript:',sub,' value:', val)
  • IRISGlobalNode is sliceable:

    Through standard Python slicing syntax, IRISGlobalNode can be iterated over a more restricted ranges of subscripts.

    node[start:stop:step]
    

    This results in a new IRISGlobalNode object with the subscript range limited to from start (inclusive) to stop (exclusive). step can be 1 or -1, meaning traversing in forward direction or in reversed direction.

  • IRISGlobalNode is reversible:

    If the "step" variable is -1 in the slicing syntax, the IRISGlobalNode will iterate backwards - reversed from the standard order. For example, the following statement will traverse the subscripts from 8 (inclusive) to 2 (exclusive):

    for x in node[8:2:-1]: print(x)
    
  • IRISGlobalNode is indexable and supports membership tests

    For example, given a child node with subscript x, the node value can be set with node[x] = y and returned with z = node[x]. A membership test with x in node will return a boolean.

IRISGlobalNode Constructor

Instances of IRISGlobalNode can be created by calls to IRIS.node(), IRISGlobalNode.node(), or IRISGlobalNode.nodes().

IRISGlobalNode Method Details

get()

iris.IRISGlobalNode.get() returns the value of a node at the specified subscript. Returns default_value if the node is valueless or does not exist. .

get (subscript, default_value)

parameters:

  • subscript — subscript of the child node containing the value to retrieve

  • default_value — value to return if there is no value at the specified subscript

items()

iris.IRISGlobalNode.items() returns a view yielding subscript-value tuples for all child nodes of this node.

items ()

returns: IRISGlobalNodeView object yielding subscript-value tuples

keys()

iris.IRISGlobalNode.keys() returns a view yielding subscripts for all child nodes of this node. Identical to subscripts().

keys ()

returns: IRISGlobalNodeView object yielding only subscripts.

node()

iris.IRISGlobalNode.node() returns an IRISGlobalNode object representing the child node at the specified subscript.

node (subscript)

returns: IRISGlobalNode object

parameters:

  • subscript — subscript of the desired child node

nodes()

iris.IRISGlobalNode.nodes() returns a view yielding an IRISGlobalNode object for each child node of this node.

nodes ()

returns: IRISGlobalNodeView object yielding IRISGlobalNode objects

subscripts()

iris.IRISGlobalNode.subscripts() returns a view yielding subscripts for all child nodes of this node. Identical to keys().

subscripts ()

returns: IRISGlobalNodeView object yielding only subscripts.

values()

iris.IRISGlobalNode.values() returns a view yielding values for all child nodes of this node. Returns None if a node does not have a value.

values ()

returns: IRISGlobalNodeView object yielding only values.

Class iris.IRISGlobalNodeView

Class iris.IRISGlobalNodeView implements view objects for IRISGlobalNode which can be iterated over to yield data from the child nodes. IRISGlobalNodeView objects are returned by IRISGlobalNode methods keys(), subscripts(), values(), items(), and nodes().

Legacy Support Classes

These classes have been retained to allow legacy applications to run without alteration. They should never be used in new code, and legacy code should work without any changes.

Class iris.LegacyIterator [deprecated]

This class is included only for backward compatibility. Class iris.LegacyIterator allows code that was written with the deprecated irisnative.Iterator class to continue working without any changes.

New code should always use the iris.IRISGlobalNode class instead.

LegacyIterator Method Details

next() [deprecated]

iterator.next() positions the iterator at the next child node and returns the node value, the node subscript, or a tuple containing both, depending on the currently enabled return type (see below). Throws a StopIteration exception if there are no more nodes in the iteration.

   iterator.next()

returns: node information in one of the following return types:

  • subscript and value (default) — a tuple containing the subscript and value of the next node in the iteration. The subscript is the first element of the tuple and the value is the second. Enable this type by calling items() if the iterator is currently set to a different return type.

  • subscript only — Enable this return type by calling subscripts().

  • value only — Enable this return type by calling values().

startFrom() [deprecated]

iterator.startFrom() returns the iterator with its starting position set to the specified subscript. The iterator will not point to a node until you call next(), which will advance the iterator to the next child node after the position you specify.

   iterator.startFrom(subscript)

returns: calling instance of iterator

parameter:

  • subscript — a single subscript indicating a starting position.

Calling this method with None as the argument is the same as using the default starting position, which is just before the first node, or just after the last node, depending on the direction of iteration.

reversed() [deprecated]

iterator.reversed() returns the iterator with the direction of iteration reversed from its previous setting (direction is set to forward iteration when the iterator is created).

   iterator.reversed()

returns: same instance of iterator

subscripts() [deprecated]

iterator.subscripts() returns the iterator with its return type set to subscripts-only.

   iterator.subscripts()

returns: same instance of iterator

values() [deprecated]

iterator.values() returns the iterator with its return type set to values-only.

   iterator.values()

returns: same instance of iterator

items() [deprecated]

iterator.items() returns the iterator with its return type set to a tuple containing both the subscript and the node value. The subscript is the first element of the tuple and the value is the second. This is the default setting when the iterator is created.

   iterator.items()

returns: same instance of iterator

Legacy Iteration Example

In the following example, iterDogs is set to iterate over child nodes of global array heroes('dogs'). Since the subscripts() method is called when the iterator is created, each call to next() will return only the subscript for the current child node. Each subscript is appended to the output variable, and the entire list will be printed when the loop terminates. A StopIteration exception is thrown when there are no more child nodes in the sequence.

Use next() to list the subscripts under node heroes('dogs')
  # Get a list of child subscripts under node heroes('dogs')
  iterDogs = irispy.iterator('heroes','dogs').subscripts()
  output = "\nSubscripts under node heroes('dogs'): "
  try:
    while True: output += '%s ' % iterDogs.next()
  except StopIteration:  # thrown when there are no more child nodes
    print(output + '\n')

This code prints the following output:

  Subscripts under node heroes('dogs'): Balto Hachiko Lassie Whitefang

class irisnative.IRISNative [deprecated]

This class is included only for backward compatibility. Class irisnative.IRISNative allows code that was written with the deprecated irisnative connection methods to continue working without any changes.

The old createConnection() and createIris() methods are now exposed as iris package methods connect() and createIris() (see “iris Package Methods”), which should always be used in new code.

createConnection() [deprecated]

Replace this method with iris package method iris.connect().

IRISNative.createConnection() attempts to create a new connection to an IRIS instance. Returns a new connection object. The object will be open if the connection was successful, or closed otherwise).

   irisnative.createConnection(hostname,port,namespace,username,password,timeout,sharedmemory,logfile)
   irisnative.createConnection(connectionstr,username,password,timeout,sharedmemory,logfile)

The hostname, port, namespace, timeout, and logfile from the last successful connection attempt are saved as properties of the connection object.

returns: a new instance of connection

parameters: Parameters may be passed by position or keyword.

  • hostnamestr specifying the server URL

  • portint specifying the superserver port number

  • namespacestr specifying the namespace on the server

  • The following parameter can be used in place of the hostname, port, and namespace arguments:

    • connectionstrstr of the form hostname:port/namespace.

  • usernamestr specifying the user name

  • passwordstr specifying the password

  • timeout (optional) — int specifying maximum number of milliseconds to wait while attempting the connection. Defaults to 10000.

  • sharedmemory (optional) — specify bool True to attempt a shared memory connection when the hostname is localhost or 127.0.0.1. Specify False to force a connection over TCP/IP. Defaults to True.

  • logfile (optional) — str specifying the client-side log file path. The maximum path length is 255 ASCII characters.

createIris() [deprecated]

Replace this method with iris package method iris.createIris().

IRISNative.createIris() returns a new instance of IRIS that uses the specified connection. Throws an exception if the connection is closed.

    irisnative.createIris(conn)

returns: a new instance of IRIS

parameter:

  • conn — object that provides the server connection

Feedback