Using the Python Instance Operator

Contents

Introduction
Background
Python Instance Operator Properties
Control Port

Introduction

Use the Python Instance operator to specify and configure the name and features of a constrained local instance execution environment for a set of Python operators. It is the Python operator itself that executes Python code. This Python Instance operator's only purpose is to define an optional local execution environment for one or more Python operators.

Use the following steps:

  1. Place a Python Instance operator on the EventFlow canvas, and give the operator a name, such as ThisInstance.

  2. In the Properties view for the Python Instance operator, select Local in the Instance Type control.

  3. Specify the full path to your preferred Python version in the Executable control.

    To avoid typing the same path in several Python Instance operators, you can optionally use an operator parameter to specify the Python path. In this case, define the operator parameter in a HOCON configuration file of type com.tibco.ep.streambase.configuration.sbengine. Save this file in the project's src/main/configurations folder.

  4. Next, in the Properties view for any actual Python operator:

    1. Select Local in the Instance Type control.

    2. Specify the name you chose in step 1 in the Local Instance Id control.

Background

By default, Python operators run in the global execution environment of the containing EventFlow module.

However, it is possible to use EventFlow concurrency features to run multiple copies of a single module that contains Python operators. In this case, you can use a Python Instance operator to define and name a local execution environment for the Python operators in that concurrent module. In this way, the execution of Python in one concurrent instance of that module does not interfere with other instances.

You can also configure a Python Instance operator with a control port that lets you enable and disable at runtime the execution of Python operators configured to use that Python instance.

Python Instance Operator Properties

This section describes the properties you can set for the Python Instance operator, using the various tabs of the Properties view in StreamBase Studio.

General Tab

Name: Use this required field to specify or change the name of this instance of this component. The name must be unique within the current EventFlow module. The name can contain alphanumeric characters, underscores, and escaped special characters. Special characters can be escaped as described in Identifier Naming Rules. The first character must be alphabetic or an underscore.

Operator: A read-only field that shows the formal name of the operator.

Class name: Shows the fully qualified class name that implements the functionality of this operator. If you need to reference this class name elsewhere in your application, you can right-click this field and select Copy from the context menu to place the full class name in the system clipboard.

Start options: This field provides a link to the Cluster Aware tab, where you configure the conditions under which this operator starts.

Enable Error Output Port: Select this checkbox to add an Error Port to this component. In the EventFlow canvas, the Error Port shows as a red output port, always the last port for the component. See Using Error Ports to learn about Error Ports.

Description: Optionally, enter text to briefly describe the purpose and function of the component. In the EventFlow Editor canvas, you can see the description by pressing Ctrl while the component's tooltip is displayed.

Operator Properties Tab

Property Type Description
Python Configuration Edit Button Shortcut to the StreamBase Configuration File Editor, used for adapter configuration or converting an existing application's adapter-configurations.xml file to HOCON format.
Instance Type radio button

Select Local to define a constrained local Python execution environment named by the EventFlow canvas name of this operator.

Select Global to disable this Python Instance's operator's local execution environment.

Global Instance ID drop-down list Only active when Instance Type specifies Global. In this case, the global Python execution environment is named and defined in this adapter's configuration file, src/main/resources/adapter-configurations.xml. Use the dropdown control to select the name of a global instance defined in configuration.
executable string Specifies the full path to the Python executable to use for all Python operators in the local execution environment defined by this Python Instance operator. If not specified, the operator invokes the command python, which is assumed to be on the PATH. The path can be specified in ${param} form as the name of an operator parameter that specifies the Python path.

Be careful about specifying a different Python executable in this field than the executable you specify in the configuration file for the global environment — unless you explicitly intend to use a different Python version for the global and local cases. For the same reason, be careful about leaving this field blank, which then specifies the first command named python on the PATH.

See Python Versions Supported for example paths.
Working Directory text Applies when Instance Type is Local to specify the working directory for the launched Python processes in this local execution environment. If not specified, processes are started in the same directory as the parent StreamBase process.
Use Temp File check box Applies when Instance Type is Local to indicate that the Python operator's integration layer should create a temporary file with Python code wrapping the interactions with StreamBase instead of pushing it through standard input. The default standard input method works for most Python interpreters and is the default.

Note

You must set this property to false when using IronPython.

Capture Output check box When Instance Type is Local, modifies the stdout and stderr behavior. By default, both are chained to the parent process's stdout and stderr. When running tests that include output, you can set this flag to capture the output.
Enable Control Port check box Enables the control port to allow commands to be sent to this operator. See Control Port below.
Log Level INFO Controls the level of verbosity the adapter uses to issue informational traces to the console. This setting is independent of the containing application's overall log level. Available values, in increasing order of verbosity, are: OFF, ERROR, WARN, INFO, DEBUG, TRACE.

Arguments Tab

Use this tab to specify arguments to be passed to the Python interpreter (not the Python script) to be invoked for all Python operators in the local execution environment defined by this Instance operator.

The usual use for this tab it to pass -u, which forces Python to use unbuffered stdin, stdout, and stderr streams. Consult the following references for information on Python launch parameters:

Environment Tab

Use this tab to specify environment variables to be passed before launching the Python interpreter by all Python operators in the local execution environment defined by this Instance operator. Environment variables specified here can potentially override variables in the platform's environment.

Cluster Aware Tab

Use the settings in this tab to enable this operator or adapter for runtime start and stop conditions in a multi-node cluster. During initial development of the fragment that contains this operator or adapter, and for maximum compatibility with releases before 10.5.0, leave the Cluster start policy control in its default setting, Start with module.

Cluster awareness is an advanced topic that requires an understanding of StreamBase Runtime architecture features, including clusters, quorums, availability zones, and partitions. See Cluster Awareness Tab Settings on the Using Cluster Awareness page for instructions on configuring this tab.

Control Port

If you enable the control port, it accepts a tuple with any structure, but one string field must be named command. The command strings accepted on this control port are:

  • start — Enables the local Python execution environment defined by this Python Instance operator.

  • stop — Disables this operator's local Python execution environment. Any Python operators configured to use this operator's instance return an error instead of processing input tuples while this Python Instance operator is disabled.

Any unrecognized fields in the control port's input tuple are ignored.