Caveats and Traps

Python scripting gives you direct access to Regina's mathematical core, and as such requires some care. Probably the easiest way to crash Regina is to bring up a Python console and do something untoward (like gluing together two tetrahedra that belong to different triangulations). Please tread gently.

In particular, you should note the following issues:

Uneditable Packets

If you cannot edit a packet within Regina, there is generally a reason for this. For instance, a normal surface list needs its parent triangulation to remain fixed, which means that any triangulation with normal surface lists beneath it will be uneditable.

You should not use Python as a way to get around this barrier. Instead you can work around the problem by cloning the packet and editing the clone instead.

International and Special Characters

If you use special characters (such as accented letters, other international characters, exotic punctuation, mathematical symbols and so on), you need to think about text encodings when passing strings between Python and Regina.

If you only ever deal with plain ASCII text (plain English letters, digits and basic punctuation), you do not need to worry about text encodings at all (and you can stop reading this section).

Regina uses UTF-8 throughout for special characters. If you ever pass a string into one of Regina's functions, any special characters must be encoded in UTF-8; conversely, when a string is returned from a function you should assume that any special characters are encoded in UTF-8.

Python, on the other hand, does not use UTF-8 strings by default. See the Python UTF-8 HOWTO for more information on how to work with UTF-8 strings in Python.

As a single exception: for file names, Regina uses whatever encoding the operating system expects. Any files names that you pass to Regina will be sent through to low-level C/C++ I/O routines without any changes or re-encoding.