API Documentation


	API Documentation

API Documentation

Regina includes a complete API reference for its calculation engine, which describes in detail the objects, classes and methods that are available through Python. To read this documentation, you can:

read the locally installed documentation by selecting Help→Python API Reference;
read it online through the Regina website;
read it inline from within Python (see below).

Be aware that this API documentation is primarily written for C++ (the main language that Regina is written in). This means:

The documentation uses C++ notation and C++ types, though these are all translated in the natural way to Python (e.g., std::string becomes a Python string, and std::vector becomes a Python list).
Some functions differ in how they are called from C++ versus Python. In such cases you will see the C++ description, but there will also be a “Python” paragraph explaining how things differ in Python.

There are more issues that Python users should be aware of; please do read the summary page in the API documentation that outlines the main differences.

Inline Documentation

Since version; 7.2, Regina now provides Python docstrings for all of its classes and functions. This means that you can get help directly from the Python prompt, as illustrated below.

Be aware, however, that this documentation is extracted automatically from the hand-written C++ API documentation discussed above. Although great attention has been paid to making this extraction as useful and natural as possible, it is still automated. Therefore you will find:

The documentation still uses some C++ terminology (e.g., std::string, pointers and references, move semantics, etc.).
Function arguments are often not named in the synopsis at the beginning of the docstring (you will see them called arg0, arg1, etc.). However, they are named in the detailed descriptions of the arguments that follow.
Some functions differ in how they are called from C++ versus Python (e.g., Tetrahedron3.face(), or Link.rewrite()). In these cases, the detailed hand-written argument descriptions will follow the C++ variant, but the initial synopsis will be written for Python. For clarity, here the arguments in the Python synopsis will be named. Look also for a “Python” paragraph that explains exactly how the C++ and Python versions differ.
Some parts of the documentation are not accessible at all through Python, since they do not correspond to entities that hold docstrings (e.g., class constants such as Perm4::nPerms, or standalone pages such as the discussion on Seifert fibred space notation).

Ultimately, it is the C++ documentation that is authoritative, not the inline Python documentation. Again, remember that you can always read the C++ documentation online.

An example of docstrings for member functions:

>>> help(NormalSurface.components)
Help on instancemethod in module regina.engine:

components(...)
    components(self: regina.NormalSurface) -> List[regina.NormalSurface]
    
    Splits this surface into connected components.
    
    A list of connected components will be returned. These components will
    always be encoded using standard (tri-quad or tri-quad-oct)
    coordinates, regardless of the internal vector encoding that is used
    by this surface.
    
    Precondition:
        This normal surface is embedded (not singular or immersed).
    
    Precondition:
        This normal surface is compact (has finitely many discs).
    
    .. warning::
        This routine explicitly builds the normal discs, and so may run
        out of memory if the normal coordinates are extremely large.
    
    Returns:
        the list of connected components.

An example of docstrings for classes:

>>> help(Crossing)
Help on class Crossing in module regina.engine:

class Crossing(pybind11_builtins.pybind11_object)
 |  Represents a single crossing in a link diagram. The two strands of the
 |  link that run over and under the crossing respectively can be accessed
 |  through routines such as over(), under(), upper(), lower(), and
 |  strand().
 |  
 |  Each crossing has a sign, which is either positive (denoted by +1) or
 |  negative (denoted by -1):
 |  
 |  * In a positive crossing, the upper strand passes over the lower
 |    strand from left to right:
 |  
 |  ```
 |    -----\ /----->
 |          \
 |    -----/ \----->
 |  ```
 |  
 |  * In a negative crossing, the upper strand passes over the lower
 |    strand from right to left:
 |  
 |  ```
 |    -----\ /----->
 |          /
 |    -----/ \----->
 |  ```
 |  
 |  If a link has *n* crossings, then these are numbered 0,...,*n*-1. The
 |  number assigned to this crossing can be accessed by calling index().
 |  Note that crossings in a link may be reindexed when other crossings
 |  are added or removed - if you wish to track a particular crossing
 |  through such operations then you should use a pointer to the relevant
 |  Crossing object instead.
 |  
 |  ... (documentation continues) ...

Prev	Contents	Next
Accessing Regina from Python	Up	Talking with SnapPy