Libraries

The System Library

Ignition comes with a group of system functions, called the System Library. Using a system function is simple. For example, the following code will access the value of a Tag.

Pseudocode - Reading a Tag Value

value = system.tag.read("tagPath").value

The scripting appendix is full of built-in functions such as this.

System Library

Watch the video

Python Libraries

Python Libraries are packages of extra functions that expand the functionality of the code and can be imported into a script. We do this by using the import keyword:

Pseudocode - Import a Library

# This pseudo code will import a library, and then call a function of that library.
import myLibrary
 
myLibrary.specialFunction()

The import keyword imports that entire library and allows you to use all of the functions inside of it by calling them off of the imported library. You can also import a piece of a library:

Pseudocode - Import a Function of a Libray

# This pseudo code will import a function from a library, and then call that function.
from myLibrary import specialFunction
 
specialFunction()

Note, that since we are directly importing in the function, we can directly call it instead of having to call it off of the library.

Python Standard Library

Python has an extensive standard library that provides a host of new functionality to the scripting language. The python documentation goes over all of the libraries in its standard library as well as how to use them here: https://docs.python.org/2/library/index.html

Let's take a look at an example of using a common library:

Python - Accessing Files in a Python Standard Library

# The csv library provides an easy way to read csv files, regardless of how they are formatted.
import csv
 
# We first grab our filepath, and feed it into the open function, which opens the file.
filepath = "C:\\test.csv"
csvFile = open(filepath, 'r')
 
# We then pass our opened csv file object into the csv.reader function, which will read the file.
# This can be looped through in a for loop to print every row of the csv.
reader = csv.reader(csvFile)
for row in reader:
    print row

Importing 3rd Party Libraries

In addition to the standard libraries, 3rd party libraries can also be imported into Ignition's scripting environment. A Python Library or individual module file will consist of a python file (.py) that contains the code that implements the functions of the library. You can often find python libraries built by other users on the web, or can even create your own. These files can then be placed into a folder within your Ignition server.

Windows

C:\Program Files\Inductive Automation\Ignition\user-lib\pylib

MacOS

/usr/local/ignition/user-lib/pylib

Linux

/usr/local/bin/ignition/user-lib/pylib

Once the python file is in that folder, you can then import the library into a script just like any of the standard libraries.

caution

Ignition uses Python version 2.7. This means that any imported libraries must be compatible with Python 2.7.

Accessing Java

Scripting in Ignition executes in the java based implementation of Python called Jython. (See Python or Jython?). While this doesn't have any great effect on the Python language itself, one of the great side benefits is that your Python code can seamlessly interact with Java code as if it were Python code. This means that your Python code has access to the entire Java standard library.

To use Java classes, you simply import them as if they were Python modules. For example, the following code will print out all of the files in the user's home directory. This code uses the Java classes java.lang.System and java.io.File to look up the user's home directory and to list the files. Notice that we can even use the Python-style for loop to iterate over a Java sequence.

Python - Accessing Java

# Importing the appropriate java libraries.
from java.lang import System
from java.io import File
 
# Used to look up the files in the users home directory.
homePath = System.getProperty("user.home")
homeDir = File(homePath)
 
# Loops through the list of files and prints them.
for filename in homeDir.list():
   print filename

You can find the reference documentation for the Java standard class library (also known as, the "JavaDocs") at: http://docs.oracle.com/javase/8/docs/api/

Subclassing Java

You can also create Python classes that implement Java interfaces. You do need some understanding of Java and object-oriented programming concepts, which are outside the scope of this manual. To create a Python class that implements a Java interface, you simply use the interface as a superclass for your Python class. For example, we could augment the example above to use the overload java.io.File.list(FilenameFilter). To do this, we'll need to create a FilenameFilter, which is an interface in Java that defines a single function:

boolean accept(File dir, String name)

To implement this interface, we create a Python class that has java.io.FilenameFilter as its superclass, and implements that Java-style function in a Python-esque way.

Python - Implementing Java Interfaces

# Importing the appropriate java libraries.
from java.lang import System
from java.io import *
 
# This sets up an extension filter that can check the file extension. Txt is the default.
class ExtensionFilter(FilenameFilter):
   def __init__(self, extension=".txt"):
      self.extension=extension.lower()
 
   def accept(self, directory, name):
      # make sure that the filename ends in the right extension
      return name.lower().endswith(self.extension)
 
# Used to look up the files in the users home directory.
homePath = System.getProperty("user.home")
homeDir = File(homePath)
 
# Prints out all .txt files. Txt is provided if nothing is specified.
for filename in homeDir.list(ExtensionFilter()):
   print filename
 
# Prints out all .pdf files.
for filename in homeDir.list(ExtensionFilter(".pdf")):
   print filename