Package ptolemy.actor.lib.python

Class PythonScript

  • All Implemented Interfaces:
    java.lang.Cloneable, Actor, Executable, FiringsRecordable, Initializable, TypedActor, Changeable, Debuggable, DebugListener, Derivable, Instantiable, ModelErrorHandler, MoMLExportable, Moveable, Nameable
    public class PythonScript
extends TypedAtomicActor
    An actor of this class executes a Python script. There are two versions of this actor provided in the Vergil libraries. The one called "PythonActor" has an input port and an output port; to view or edit its Python script, look inside the actor. The second version is called "PythonScript" and has no ports; to view or edit its Python script, select Configure (or double click on the icon).

    Upon creation, this actor has no ports, and no parameters other than script; The script parameter has visibility EXPERT, and therefore does not normally show up in a configure dialog for the actor. To make the script visible and editable, you have two options. Including an instance of an attribute of class TextEditorConfigureFactory (with its attributeName parameter set to script) results in behavior like that of the Vergil "PythonScript." That is, to edit the script, you Configure the actor. If instead you include an instance of TextEditorTableauFactory, then to edit the script you look inside the actor. Use the latter if you wish to add additional attributes to the actor and hide the script from the users. Use the former if the script is the main means by which users interact with the actor.

    The functionality of an actor of this type is given by a Python script. As an example, a simplified version of the Scale actor can be implemented by the following script:

     1.  class Main :
 2.    "scale"
 3.    def fire(self) :
 4.      if not self.input.hasToken(0) :
 5.        return
 6.      s = self.scale.getToken()
 7.      t = self.input.get(0)
 8.      self.output.broadcast(s.multiply(t))

    Line 1 defines a Python class Main, which matches the value of the jythonClassName parameter. An instance of this class is created when the actor is initialized. Line 2 is a description of the purpose of the script. Lines 3-8 define the fire() method, which is called by the fire() method of this actor. In the method body, input and output are ports that have to have been added to the actor, and scale is a parameter that has to have been added to the actor (these can be added in the XML that defines the actor instance in an actor library). The Main class can provide other methods in the Executable interface as needed.

    In the script, use self.actor to access the actor. For example, self.actor.getDirector() returns the current director of the actor. For debugging, use self.actor.debug(someMessage). The final message sent to the debug listeners of the actor will have the string "From script: " inserted at the beginning. To avoid generating the debug message when there are no listeners, use:

     if self.actor.isDebugging() :
 self.actor.debug(someMessage)

    To use a Jython module, it is necessary to create a .py file located in a location where Jython can find it. The Jython sys.path variable contains the Jython path. One way to get the value of the sys.path variable is to enable debugging on the actor by right clicking and selecting "Listen to Actor", which will cause the preinitialize() method to print the contents of sys.path to standard out. Another way to get the value of sys.path is to run the Ptolemy model at ptolemy/actor/lib/python/test/PythonSysPath. For example, under Mac OS X for the ptII user, sys.path includes /Users/ptII/lib/Lib. So, create that directory if necessary and place the .py file in that directory, for example /Users/ptII/lib/Lib/PtPythonSquare.py

    class Main :
  "Read the input and send the square to the output"
  def fire(self) :
    token = self.input.get(0)
    self.output.broadcast(token.multiply(token))
    return

    Then set jythonClassName to the name of the Jython class, for example PtPythonSquare.Main. (Note that the jythonClassName parameter should be set to the value of the Jython class name before changing the script parameter to import a Jython module.)

    Then set script to to:

     import PtPythonSquare
 PtPythonSquare = reload(PtPythonSquare)

    This class relies on Jython, which is a Java implementation of Python.

    As of November, 2011 $PTII/lib/jython.jar was based on Jython 2.5.2.

    See Python and Kepler notes.

    Since:
    Ptolemy II 2.3
    Version:
    $Id$
    Author:
    Xiaojun Liu
    Pt.AcceptedRating:
    Red (reviewmoderator)
    Pt.ProposedRating:
    Yellow (liuxj)

    • Field Detail

      • jythonClassName

        public StringAttribute jythonClassName
        The Jython class name to be invoked. The default value is "Main", which indicates that the script parameter should define a class named "Main". If the script parameter imports a Jython module, for example: "import Foo", then Foo.py should define a class named "Main" and this parameter should have the value "Foo.Main". If the value of this parameter is anything other than "Main", then preinitialize() will reread the script. This is how Jython modules can be used. Note that the jythonClassName parameter should be set to the value of the Jython class name before changing the script parameter to import a Jython module.

      • script

        public StringAttribute script
        The script that specifies the function of this actor. The default value is a script that copies the input to the output.

    • Constructor Detail

      • PythonScript

        public PythonScript​(CompositeEntity container,
                    java.lang.String name)
             throws NameDuplicationException,
                    IllegalActionException
        Construct an actor with the given container and name. In addition to invoking the base class constructor, create the script parameter, and initialize the script to provide an empty template.
        Parameters:
        container - The container.
        name - The name of this actor.
        Throws:
        NameDuplicationException - If the container already has an actor with this name.
        IllegalActionException - If the actor cannot be contained by the proposed container.

    • Method Detail

      • debug

        public void debug​(java.lang.String message)
        Send the message to all registered debug listeners. In the script, use self.actor.debug() to call this method.
        Parameters:
        message - The debug message.

      • isDebugging

        public boolean isDebugging()
        Return true if this actor has at least one debug listener.
        Returns:
        True if this actor has at least one debug listener.

      • postfire

        public boolean postfire()
                 throws IllegalActionException
        Invoke the postfire() method if defined in the script. Return true when the method return value is not zero, or the method does not return a value, or the method is not defined in the script.
        Specified by:
        postfire in interface Executable
        Overrides:
        postfire in class AtomicActor<TypedIOPort>
        Returns:
        False if postfire() is defined in the script and returns 0, true otherwise.
        Throws:
        IllegalActionException - If there is any error in calling the postfire() method defined by the script.

      • prefire

        public boolean prefire()
                throws IllegalActionException
        Invoke the prefire() method if defined in the script. Return true when the method return value is not zero, or the method does not return a value, or the method is not defined in the script.
        Specified by:
        prefire in interface Executable
        Overrides:
        prefire in class AtomicActor<TypedIOPort>
        Returns:
        False if prefire() is defined in the script and returns 0, true otherwise.
        Throws:
        IllegalActionException - If there is any error in calling the prefire() method.

      • preinitialize

        public void preinitialize()
                   throws IllegalActionException
        Create an instance of the parameter named by the jythonClassName parameter that is defined in the script. Add all parameters and ports of this actor as attributes of the object, so that they become accessible to the methods defined in the script.
        Specified by:
        preinitialize in interface Initializable
        Overrides:
        preinitialize in class AtomicActor<TypedIOPort>
        Throws:
        IllegalActionException - If there is any error in creating an instance of the class named by the jythonClassName class defined in the script.

      • stop

        public void stop()
        Invoke the stop() method if defined in the script. Ignore any error in calling the method.
        Specified by:
        stop in interface Executable
        Overrides:
        stop in class AtomicActor<TypedIOPort>