Python users

Regina's calculation engine is provided as a shared C++ library, and this API documentation describes the native C++ interface for working with this library.

Regina also provides a Python module, which wraps many of the classes, functions, methods and so on from this library so that Python users can access them.

Python users should read this documentation as follows:

- Standard C++ types become native Python types. For example, the C++ type `std::string` becomes the native Python string type.
- Everything within the C++ namespace regina becomes part of the Python module regina. For example, the C++ class regina::Triangulation<3> becomes the Python class regina.Triangulation3.
- Regina's most important C++ classes and functions are wrapped in Python. However, not all classes and functions are wrapped. If a class or function is not available in Python then you will see a bold Python: note indicating this. See for instance the class Bitmask, or the function duplicate().
- Most of Regina's classes and functions have the same interface in both C++ and Python, but occasionally there are differences. Again, you will see a bold Python: note indicating this. See for instance the method Triangulation<3>::tetrahedra(), or the global function writeResUsage().

### Testing equality

It is important to understand how Python's equality tests `x == y` and `x is y` operate under Python.

If x is a Python variable representing one of Regina's objects, then internally x stores a reference to one of Regina's native C++ objects. Importantly, there may be many different Python variables that all stores references to the same underlying C++ object.

This means that the Python test `x is y` is unreliable. If `x is y` returns `True` then certainly x and y refer to the same C++ object; however, if `x is y` returns `False` then it is still possible that they refer to the same C++ object.

The solution is to always use the test `x == y`. Regina offers three types of classes, and these behave differently under Python:

- Some classes use comparison by value. Here `x == y` tests whether the contents of x and y are mathematically equivalent. Examples of such classes are Integer, Rational, and AbelianGroup.

  These classes all provide C++ comparison operators == and !=. You can read the documentation for these operators to understand exactly what mathematical condition(s) are being tested.

- Some classes use comparison by reference. Here `x == y` tests whether x and y refer to the same underlying C++ object. This is similar to how the test `x is y` would behave in a native Python application. Examples of such classes are Triangulation<3> and Tetrahedron<3>.

  These classes do not provide C++ comparison operators == or !=.

- Some classes are never instantiated, and so can never be compared at all. These classes typically contain only static methods. Examples of such classes are Example<dim> and Locale.

If you wish to find out how a particular class C behaves, you can examine the attribute `C.equalityType`. This will return one of the values `BY_VALUE`, `BY_REFERENCE` or `NEVER_INSTANTIATED` respectively:

>>> print Triangulation3.equalityType
BY_REFERENCE

Copyright © 1999-2016, The Regina development team
This software is released under the GNU General Public License, with some additional permissions; see the source code for details.
For further information, or to submit a bug or other problem, please contact Ben Burton (bab@maths.uq.edu.au).