Run Python File

Description

Execute the specified file as Python source code.

Available Modules and Functions

Python code executed by Run Python File, Run Python String, a Python File Resource, a Python Image Stimulus, or the expression parser functions py_eval and py_call can make use of both the Python standard library and NumPy. In addition, the following MWorks-specific functions are available:

getvar(name)

Returns the value of an MWorks variable. name is a string containing the name of the variable.

setvar(name, value)

Sets the value of an MWorks variable. name is a string containing the name of the variable, and value is the new value to assign.

getcodec()

Returns the code-to-name mapping for variables (as a dictionary).

get_reverse_codec()

Returns the name-to-code mapping for variables (as a dictionary).

register_event_callback(name, callback)

Registers an event callback function for an MWorks variable. name is a string containing the name of the variable, and callback is a Python function as described below.

register_event_callback(code, callback)

Registers an event callback function for an MWorks variable. code is the integer code corresponding to the variable, and callback is a Python function as described below.

register_event_callback(callback)

Registers an event callback function for all MWorks variables. callback is a Python function as described below. (Note: The callback function will be invoked very, very frequently. Use with caution!)

unregister_event_callbacks()

Unregisters all event callback functions previously registered via Python code.

message(msg)

Generates a normal MWorks message (like Report / Message). msg can be any value, which, after conversion to a string, is used as the text of the message.

warning(msg)

Generates an MWorks warning message. msg can be any value, which, after conversion to a string, is used as the text of the message.

error(msg)

Generates an MWorks error message. msg can be any value, which, after conversion to a string, is used as the text of the message.

Event callback functions are invoked whenever a value is assigned to the variable of interest. They receive a single argument of type Event, which has attributes code, time, and data. The values of code and time are always integers, while the value of data can be a boolean, integer, float, string, list, or dictionary.

All MWorks-specific functions are pre-imported in to the __main__ module, in which the user-provided Python file or string executes. To use them in other modules, import them from mworkscore, e.g.

from mworkscore import getvar, setvar

Execution Environment

All user-provided Python code is executed within Python’s __main__ module. This means that any variables, functions, classes, etc. defined by one Python action or resource file are available to all subsequent ones.

Due to limitations in the Python interpreter, the Python environment is not reset when a new experiment is loaded. If your Python code expects to run in a “clean slate” environment, it will have to perform the necessary cleanup actions itself.

Also, event callback functions are never unregistered automatically. They must be removed explicitly via unregister_event_callbacks().

Signature

action/run_python_file

Required Parameters

path

Filesystem path to the Python source file

Optional Parameters

stop_on_failure

Default

NO

If YES, the experiment will stop automatically if Python execution fails

Placement

Allowed at top level:

No

Allowed parent:

Block, Conditionally Execute Actions (if), List, Protocol, Render Actions, Repeat Actions (while), Schedule Actions, Task System State, Trial, Unconditionally Execute Actions (else), Variable