PythonFile

PythonFile [/Z] file = fileStr [, var = {pyVarStr, igorVar}, array = {pyArrayStr, igorWave}, args = argListStr]

The PythonFile operation executes an entire .py file from top to bottom. Note, this does not import the file as a module, so a programmer can change the script and immediately run the new code without restarting the Python Interpreter.

Parameters

file = fileStr	Python file to execute. This can either be the name of a file on the Python path, or the full path to the file. If you use a full path for fileStr, see Path Separators for details on forming the path. fileStr must include the file extension (.py). This keyword is required.
var = {pyVarStr, igorVar}	Assigns the named Python numeric or string variable to the Igor numeric or string variable igorVar. igorVar cannot be the full path to a global variable. To assign to a global variable, you must first declare it locally using NVAR (numeric variables) or SVAR (string variables).
array = {pyArrayStr, igorWave}
	Assigns the named Python array-like object to the Igor wave igorWave.
	igorWave must already exist, and can be either a local wave reference or the full path to a wave. Both global and free waves are supported. See Returning Python variables to Igor below for more information.
	Array-like objects include NumPy arrays, lists, tuples, or built in Python arrays (array.array).
args = argListStr	String list specifying a list of arguments to provide to the Python script.
	Individual arguments should be separated by whitespace (tabs or spaces). Each argument will be inserted as an entry in the sys.argv Python list, which can then be parsed in the Python script itself. Igor expressions or functions that return a string can also be used. Note, strings that contain numeric values must be converted back to numeric types after parsing them in the Python script.

Flags

/Z	Do not report any errors. Error messages will still be printed to the Python Console and stored in S_PythonError.

Output Variables

V_flag	Error code, set to zero if there was no error.
S_PythonError	If a Python error occurred, this string will be set to Python's traceback message.
	Only Python errors will set this string, an Igor-related error will not. For example, syntax errors in the Python code being executed will set S_PythonError. However, if a variable or wave doesn't exist while using the var or array keywords, it will not be set since that is not a Python error, but an Igor error.

Details

PythonFile is analogous to running a Python file from the system command prompt, as in:

python myScript.py

As such, PythonFile sets the Python global variable __name__ to '__main__', which can act as a guard for code that will only run when the script is executed by PythonFile, but not when it is imported as a module. See Examples, which illustrate the difference between importing and executing a file.

Object lifetime

Any global Python variables that are created during code execution will be persistent for the lifetime of the Igor instance. As a result, subsequent calls to the Python and PythonFile operations can use any previously created variables or imported libraries. Similarly, any code run through the Python Console will also have access to imported libraries or variables created from the operation, and vice versa.

When running a Python script, note that variables created within a method are garbage collected when execution returns, and thus cannot be returned to Igor. In order to return a Python variable to Igor, it must be created with global scope.

Returning Python variables to Igor

If the var or array keyword was used, Igor attempts to assign a Python object to an existing Igor object. Igor will not create the new object for you. The Python and Igor types must be compatible for this to succeed. See Python to Igor Type Conversions for descriptions of compatible objects. See the Returning Python variables to Igor help section in Python for an in-depth discussion and examples.

Restarting the Python Interpreter

Opening a new Igor experiment without closing Igor will not reset the Python interpreter. In order to get a completely clean Python session, or to change Python environments, you must restart Igor.

Error handling

Errors that occur during Python code execution will be relayed to Igor as runtime errors. The error message will contain the Python traceback message, which is also printed to the Python Console. Like any other Igor runtime error, Python runtime errors can be caught in a try-catch-endtry construct:

# Python
# scriptThatContainsError.py
print('this is missing a parentheses'  # produces a runtime error

// Igor
try
	// Run a script that will produce a syntax error
	PythonFile file = "scriptThatContainsError.py"; AbortOnRTE
catch
	Print GetRTErrMessage()       // print the error message, which indicates SyntaxError
	Variable err = GetRTError(1)  // clear the error	
endtry

Any errors that occur during Python execution will be written to the Python Console, and also stored in the S_PythonError string.

V_flag is set to a non-zero error code if any errors occurred. This can be used to retrieve the traceback message from Python. For example:

// Run a script that will produce a syntax error
PythonFile/Z file = "scriptThatContainsError.py"
if (V_flag)
	Print S_PythonError
endif

Examples

Running a Python file with arguments:

# Python
# myScript.py
import sys

def doAnalysis(arg):
	# do analysis routine...
	return arg * 2

if __name__ == '__main__':
	arg1 = float(sys.argv[1])  # convert the argument from a string to a float
	result = doAnalysis(arg1)  # 'result' is a global variable

// Igor	
Variable result
PythonFile file = "myScript.py", var = {"result", result}, args = "3.141"
Print result   // prints 6.282

Importing versus executing a Python file:

# Python
# myScript.py
if __name__ == '__main__':
	print('executed script')
else:
	print('imported as a module')

// Igor	
Python execute = "import myScript"  // prints 'imported as a module'
PythonFile file = "myScript.py"     // prints 'executed script'

See Also

Python, PythonEnv, Python Overview, Python Module Reference