.\" This manpage has been automatically generated by docbook2man 
.\" from a DocBook document.  This tool can be found at:
.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> 
.\" Please send any bug reports, improvements, comments, patches, 
.\" etc. to Steve Cheng <steve@ggi-project.org>.
.TH "REGINA-PYTHON" "1" "28 May 2012" "" "The Regina Handbook"

.SH NAME
regina-python \- Regina's command-line Python interface
.SH SYNOPSIS

\fBregina-python\fR [ \fB-q, --quiet\fR | \fB-v, --verbose\fR ] [ \fB-n, --nolibs\fR ] [ \fB-a, --noautoimport\fR ]


\fBregina-python\fR [ \fB-q, --quiet\fR | \fB-v, --verbose\fR ] [ \fB-n, --nolibs\fR ] [ \fB-a, --noautoimport\fR ] [ \fB-i, --interactive\fR ] \fB\fIscript\fB\fR [ \fB\fIscript-args\fB\fR ]

.SH "DESCRIPTION"
.PP
Regina is a software package for studying 3-manifold triangulations
and normal surfaces.  Other key features include
angle structures, census enumeration, combinatorial
recognition of triangulations, and high-level tasks such as
3-sphere recognition and connected sum decomposition.
Regina comes with a full graphical user interface, and also offers
Python bindings and a low-level C++ programming interface.
.PP
This command starts an interactive Python session for
Regina.  This will be a command-line Python session, with direct
text input/output and no graphical user interface.
All of the objects, clases and methods from Regina's mathematical
engine will be made available through the module
\fIregina\fR, which will be imported on startup
(effectively running import regina).
Moreover, unless the option \fB--noautoimport\fR is
passed, all of Regina's objects, classes and methods will be
imported directly into the current namespace
(effectively running
from regina import\~*).
.PP
If you have frequently-used code, you can store it in a
\fIuser library\fR\&.
At the beginning of each Python session, Regina will automatically
run all of the code in all of your user libraries.
The list of user libraries will be read from the text file
\fI~/.regina-libs\fR, which should contain one
library filename per line.  Blank lines and lines beginning with a
hash (#) will be ignored.  You can also configure this list of
libraries through the graphical user interface: see the
Python options page.
.PP
Instead of starting an interactive Python session, you can pass a
Python script (with arguments if desired).  In this case Regina
will run the script (after first importing the
\fIregina\fR module and loading any user libraries).
If you pass \fB--interactive\fR, Regina will leave you
at a Python prompt once the script finishes;
otherwise it will exit Python and return you to the command line.
.SH "OPTIONS"
.TP
\fB-q\fR
.TP
\fB--quiet\fR
Start in quiet mode.  No output will be produced except
for serious errors.  In particular, warnings will be suppressed.

This is equivalent to setting the environment variable
\fIREGINA_VERBOSITY\fR=0\&.
.TP
\fB-v\fR
.TP
\fB--verbose\fR
Start in verbose mode.  Additional diagnostic
information will be output.

This is equivalent to setting the environment variable
\fIREGINA_VERBOSITY\fR=2\&.
.TP
\fB-n\fR
.TP
\fB--nolibs\fR
Do not load any user libraries when the session starts.
User libraries are discussed in the overview above.
.TP
\fB-a\fR
.TP
\fB--noautoimport\fR
Still import the \fIregina\fR module,
but do not automatically import all of Regina's objects,
classes and methods into the current namespace
(that is, do not run
from regina import\~*).
This means that (for example) the main 3-manifold triangulation class
must be accessed as regina.NTriangulation, not
just NTriangulation\&.
.TP
\fB-i\fR
.TP
\fB--interactive\fR
Run the script in interactive mode.  After executing the
given script, Regina will leave you in the Python interpreter
to run your own additional commands.

This option is only available when a script is passed.
If no script is passed, \fBregina-python\fR will
always start in interactive mode.
.SH "ENVIRONMENT VARIABLES"
.PP
The following environment variables influence the behaviour of
this program.  Each variable can also be set in the local
configuration file \fI~/.regina-python\fR using a line
of the form
\fIoption\fR=\fIvalue\fR\&.
Environment variables will take precedence over values in
the configuration file.
.TP
\fB\fIREGINA_VERBOSITY\fB\fR
Specifies how much output should be generated.
Recognised values are:
.RS
.TP
\fB0\fR
Display errors only; this is equivalent to passing the option
\fB--quiet\fR\&.
.TP
\fB1\fR
Display errors and warnings; this is the default.
.TP
\fB2\fR
Display errors, warnings and diagnostic output; this is
equivalent to passing the option \fB--verbose\fR\&.
.RE
.TP
\fB\fIREGINA_PYTHON\fB\fR
The command used to start the Python interpreter.
By default, Regina tries to run the same version of Python
that it was built against.

In general you should use the same version of Python that Regina
was built against; otherwise Python might not be able to load the
\fIregina\fR module.

In normal situations you should never need to set this option yourself.
.TP
\fB\fIREGINA_HOME\fB\fR
The directory in which Regina's data files are installed.  This
should be the directory containing the \fIinternal/\fR
subdirectory, the \fIexamples/\fR subdirectory and so on.

If you are running Regina directly out of the source tree, this
defaults to the top-level source directory.  If you are running
Regina from a proper installation, this defaults to the corresponding
installation directory.

In normal situations you should never need to set this option yourself.
.sp
.RS
.B "Warning:"
When running from a proper installation,
the default \fIREGINA_HOME\fR is
hard-wired into the startup script (it is set at compile time).
If you install Regina into one directory but then move it by
hand into another, the default \fIREGINA_HOME\fR
will be incorrect.
.RE
.TP
\fB\fIREGINA_PYLIBDIR\fB\fR
The directory containing the Python module
\fIregina.so\fR\&.

If you are running Regina directly out of the source tree, this
defaults to a directory within this source tree.  If you are
running Regina from a proper installation, this defaults to the
corresponding installation directory.

In normal situations you should never need to set this option yourself.
.sp
.RS
.B "Warning:"
Like \fIREGINA_HOME\fR,
when running from a proper installation
the default \fIREGINA_PYLIBDIR\fR is
hard-wired into the startup script.
If you install Regina into one directory but then move it by
hand into another, the default \fIREGINA_PYLIBDIR\fR
will be incorrect.
.RE
.SH "MACOS\\~X USERS"
.PP
If you downloaded a drag-and-drop app bundle, this utility is
shipped inside it.  If you dragged Regina to the main
Applications folder, you can run it as
/Applications/Regina.app/Contents/MacOS/regconcat\&.
.SH "WINDOWS USERS"
.PP
The command \fBregina-python\fR is not available under
\fBWindows\fR\&.  However, you can still use Python scripting in Regina's
graphical user interface, by opening a graphical Python console or
using script packets.
.SH "SEE ALSO"
.PP
regina-gui\&.
.PP
Regina comes with thorough API documentation,
which describes in detail all of the objects, classes and methods that
Regina makes available to Python.
You can access this documentation via
Help->Python API Reference in the graphical user interface, or read it online
at \fBhttp://regina.sourceforge.net/engine-docs/\fR\&.
.SH "AUTHOR"
.PP
Many people have been involved in the development
of Regina; see the users' handbook for a full list of credits.