| Python Scripting |
| Prev | Next |
Table of Contents
Regina contains inbuilt scripting, which offers you fine control over the underlying calculation engine and enables you to automate large amounts of processing using the Python programming language. Scripts can be written and run from within Regina, and a well-written script can relieve you of much work that would otherwise have to be painstakingly done by hand through the point-and-click interface.
Scripting is available by several means.
You can run the command-line program regina-python without using the graphical user interface at all. This uses the standard Python command-line interpreter and is quite fast. Since it is purely text based, it also supports the redirection of input and output.
You can bring up a graphical Python console through the
->
menu item or the corresponding toolbar button.
The top-level packet of the current file (if any) will be assigned
to the special variable root.
The currently selected packet (if any) will be assigned to the
special variable selected.
You can create a new script packet. Script packets have the advantage that they can work seamlessly with multiple packets in the same file through the use of script variables. Furthermore, script packets are saved with the data file for later reuse.
The editor for script packets includes a table of variables that will be set each time the script is run. Buttons and menu options are available for running the script or for simply testing whether it compiles.
Each time a script is run, a new graphical Python console is opened. The script is run within this console and the console is then made available to the user for further interaction.
All scripts use the Python scripting language (http://www.python.org/). Within these scripts, Regina objects, classes and methods can be accessed directly as if they were Python objects, classes and methods.
Each of these objects, classes and methods is available in the
module regina. For instance, a new
triangulation can be created by calling
regina.NTriangulation() and a file can be
read by calling regina.readFileMagic(filename).
Wherever Regina gives you access to Python, you may assume that the
regina module has been imported (thus giving you
access to everything contained within it).
You may also assume that all user libraries have been loaded, as
described below.
If you have code that you find yourself writing again and again,
you can put it in a user library. User
libraries are files containing Python code (typically function
definitions) that is run at the beginning of every Python
session, both within the GUI and within the text-based
regina-python.
The list of user libraries can be configured through the
Python options page, or can be
maintained by hand-editing the file ~/.regina-libs as described in the
regina-python
reference.
Regina includes a complete reference for its calculation engine, which describes in detail the objects, classes and methods made available to Python scripts. This documentation is available through the -> menu item.
For those wishing to read this documentation from outside the
program, it is generally installed in
/usr/share/regina/engine-docs/
or /usr/local/share/regina/engine-docs/, although this
may differ with your distribution or installation.
| Prev | Home | Next |
| Exporting | Up | Caveats |