PythonEnv
PythonEnv [/P=pathName /Z[=z]] [activate = envPathStr, venv = argumentStr]
The PythonEnv operation provides some basic environment management features for Python environments.
Only a single keyword is allowed at a time. If no keywords are provided, PythonEnv creates the string variable S_PythonEnvInfo, which contains information about the currently active Python environment, as well as V_PythonRunning, which is set to 1 if the Python Interpreter is currently running.
Flags
| /P = pathName | Specifies the folder to use as the working directory. pathName is the name of an existing symbolic path. | ||||
| /Z [= z] | Suppress error generation. Use this if you want to handle errors yourself. | ||||
| |||||
| /Z alone has the same effect as /Z=1. | |||||
Parameters
| activate = envPathStr | Activates the Python environment located at the full or relative path envPathStr. If envPathStr is a relative path, it will be relative to the symbolic path provided by the /P flag or, if the /P flag was omitted, the user's home directory (e.g. C:/Users/<username>). | |
| Activating an environment is equivalent to changing the environment setting in Python→Settings. Information about the environment that was activated can be found in the output string variable S_PythonEnvInfo. | ||
| venv = argumentStr | Creates a new virtual Python environment using the venv package. argumentStr can be any valid venv argument, in accordance with their documentation (https://docs.python.org/3/library/venv.html). | |
| If the /P flag was provided, that path will be used as the working directory for running venv. As a result, that is the directory that will contain the virtual environment if a full path was not provided in argumentStr. | ||
| The Python version used for the virtual environment will be the base Python version of the currently active Python environment. Note, the newly created virtual environment must be activated using the activate keyword, or selected in Python→Settings, before it can be used. | ||
| Information about the virtual environment that was created can be found in the output string variable S_PythonEnvInfo. | ||
Output Variables
| S_PythonEnvInfo | This string variable contains a key-value list of information about the currently active Python environment or the environment that was just created, depending on which keyword was used. | |
| V_PythonRunning | This numeric variable is set to 1 if the Python Interpreter is currently running, otherwise it is set to 0. | |
| V_Flag | Set to 0 if the operation succeed or to a non-zero error code. | |
Keyword-value pairs for S_PythonEnvInfo:
| Keyword | Value |
|---|---|
| NAME | Name of environment, if it has one. Base Python installations do not have environment names. |
| VERSION | Python version number. |
| HOME | Full path to the Python home folder. |
| LIBRARY | Full path to the Python library used by the environment. |
| SITEPACKAGES | Full path to the site-packages folder. |
Creating a new virtual environment
A simple example of creating a virtual environment:
// The new virtual environment will be created as C:/MyProject/imageAnalysis
NewPath/O environmentPath, "C:/MyProject"
PythonEnv/P = environmentPath venv = "imageAnalysis"
Alternatively, the full path can be used to create the environment:
PythonEnv venv = "C:/MyProject/imageAnalysis"
For help on using venv, either visit https://docs.python.org/3/library/venv.html or, to view help documentation within Igor, run:
PythonEnv venv = "-h"
Activating a new virtual environment
After creating the environment, it will automatically be added to Igor's list of manually configured environments, which can be viewed in the Python category of Miscellaneous Settings.
Once the environment is configured, you can activate it by either selecting it in the Python category of Miscellaneous Settings, or you can use the activate keyword with the PythonEnv operation:
PythonEnv/P = environmentPath activate = "imageAnalysis"
Alternatively, the full path can be used to activate the environment:
PythonEnv activate = "C:/MyProject/imageAnalysis"
If a virtual environment was created using tools outside of Igor, you can still activate it, and it will be automatically added to Igor's list of manually configured environments.
With the environment activated, any future calls to the Python or PythonFile operation, or any use of the Python Console, will be run using this environment. However, once any Python code is executed from Igor, activating a new environment will not take effect until Igor is restarted.