mirror of https://github.com/python/cpython
193 lines
8.2 KiB
TeX
193 lines
8.2 KiB
TeX
\section{Built-in Module \sectcode{sys}}
|
|
|
|
\bimodindex{sys}
|
|
This module provides access to some variables used or maintained by the
|
|
interpreter and to functions that interact strongly with the interpreter.
|
|
It is always available.
|
|
|
|
\renewcommand{\indexsubitem}{(in module sys)}
|
|
|
|
\begin{datadesc}{argv}
|
|
The list of command line arguments passed to a Python script.
|
|
\code{sys.argv[0]} is the script name (it is operating system
|
|
dependent whether this is a full pathname or not).
|
|
If the command was executed using the \samp{-c} command line option
|
|
to the interpreter, \code{sys.argv[0]} is set to the string
|
|
\code{"-c"}.
|
|
If no script name was passed to the Python interpreter,
|
|
\code{sys.argv} has zero length.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{builtin_module_names}
|
|
A tuple of strings giving the names of all modules that are compiled
|
|
into this Python interpreter. (This information is not available in
|
|
any other way --- \code{sys.modules.keys()} only lists the imported
|
|
modules.)
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{exc_type}
|
|
\dataline{exc_value}
|
|
\dataline{exc_traceback}
|
|
These three variables are not always defined; they are set when an
|
|
exception handler (an \code{except} clause of a \code{try} statement) is
|
|
invoked. Their meaning is: \code{exc_type} gets the exception type of
|
|
the exception being handled; \code{exc_value} gets the exception
|
|
parameter (its \dfn{associated value} or the second argument to
|
|
\code{raise}); \code{exc_traceback} gets a traceback object (see the
|
|
Reference Manual) which
|
|
encapsulates the call stack at the point where the exception
|
|
originally occurred.
|
|
\obindex{traceback}
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{exec_prefix}
|
|
A string giving the site-specific
|
|
directory prefix where the platform-dependent Python files are
|
|
installed; by default, this is also \code{"/usr/local"}. This can be
|
|
set at build time with the \code{--exec-prefix} argument to the
|
|
\code{configure} script. Specifically, all configuration files
|
|
(e.g. the \code{config.h} header file) are installed in the directory
|
|
\code{sys.exec_prefix+"/lib/python\emph{VER}/config"}, and shared library
|
|
modules are installed in
|
|
\code{sys.exec_prefix+"/lib/python\emph{VER}/sharedmodules"},
|
|
where \emph{VER} is equal to \code{sys.version[:3]}.
|
|
\end{datadesc}
|
|
|
|
\begin{funcdesc}{exit}{n}
|
|
Exit from Python with numeric exit status \var{n}. This is
|
|
implemented by raising the \code{SystemExit} exception, so cleanup
|
|
actions specified by \code{finally} clauses of \code{try} statements
|
|
are honored, and it is possible to catch the exit attempt at an outer
|
|
level.
|
|
\end{funcdesc}
|
|
|
|
\begin{datadesc}{exitfunc}
|
|
This value is not actually defined by the module, but can be set by
|
|
the user (or by a program) to specify a clean-up action at program
|
|
exit. When set, it should be a parameterless function. This function
|
|
will be called when the interpreter exits in any way (except when a
|
|
fatal error occurs: in that case the interpreter's internal state
|
|
cannot be trusted).
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{last_type}
|
|
\dataline{last_value}
|
|
\dataline{last_traceback}
|
|
These three variables are not always defined; they are set when an
|
|
exception is not handled and the interpreter prints an error message
|
|
and a stack traceback. Their intended use is to allow an interactive
|
|
user to import a debugger module and engage in post-mortem debugging
|
|
without having to re-execute the command that caused the error (which
|
|
may be hard to reproduce). The meaning of the variables is the same
|
|
as that of \code{exc_type}, \code{exc_value} and \code{exc_tracaback},
|
|
respectively.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{modules}
|
|
Gives the list of modules that have already been loaded.
|
|
This can be manipulated to force reloading of modules and other tricks.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{path}
|
|
A list of strings that specifies the search path for modules.
|
|
Initialized from the environment variable \code{PYTHONPATH}, or an
|
|
installation-dependent default.
|
|
|
|
The first item of this list, \code{sys.path[0]}, is the
|
|
directory containing the script that was used to invoke the Python
|
|
interpreter. If the script directory is not available (e.g. if the
|
|
interpreter is invoked interactively or if the script is read from
|
|
standard input), \code{sys.path[0]} is the empty string, which directs
|
|
Python to search modules in the current directory first. Notice that
|
|
the script directory is inserted {\em before} the entries inserted as
|
|
a result of \code{\$PYTHONPATH}.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{platform}
|
|
This string contains a platform identifier, e.g. \code{sunos5} or
|
|
\code{linux1}. This can be used to append platform-specific
|
|
components to \code{sys.path}, for instance.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{prefix}
|
|
A string giving the site-specific directory prefix where the platform
|
|
independent Python files are installed; by default, this is the string
|
|
\code{"/usr/local"}. This can be set at build time with the
|
|
\code{--prefix} argument to the \code{configure} script. The main
|
|
collection of Python library modules is installed in the directory
|
|
\code{sys.prefix+"/lib/python\emph{VER}"} while the platform
|
|
independent header files (all except \code{config.h}) are stored in
|
|
\code{sys.prefix+"/include/python\emph{VER}"},
|
|
where \emph{VER} is equal to \code{sys.version[:3]}.
|
|
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{ps1}
|
|
\dataline{ps2}
|
|
Strings specifying the primary and secondary prompt of the
|
|
interpreter. These are only defined if the interpreter is in
|
|
interactive mode. Their initial values in this case are
|
|
\code{'>>> '} and \code{'... '}.
|
|
\end{datadesc}
|
|
|
|
\begin{funcdesc}{setcheckinterval}{interval}
|
|
Set the interpreter's ``check interval''. This integer value
|
|
determines how often the interpreter checks for periodic things such
|
|
as thread switches and signal handlers. The default is 10, meaning
|
|
the check is performed every 10 Python virtual instructions. Setting
|
|
it to a larger value may increase performance for programs using
|
|
threads. Setting it to a value $\leq 0$ checks every virtual instruction,
|
|
maximizing responsiveness as well as overhead.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{settrace}{tracefunc}
|
|
Set the system's trace function, which allows you to implement a
|
|
Python source code debugger in Python. See section ``How It Works''
|
|
in the chapter on the Python Debugger.
|
|
\end{funcdesc}
|
|
\index{trace function}
|
|
\index{debugger}
|
|
|
|
\begin{funcdesc}{setprofile}{profilefunc}
|
|
Set the system's profile function, which allows you to implement a
|
|
Python source code profiler in Python. See the chapter on the
|
|
Python Profiler. The system's profile function
|
|
is called similarly to the system's trace function (see
|
|
\code{sys.settrace}), but it isn't called for each executed line of
|
|
code (only on call and return and when an exception occurs). Also,
|
|
its return value is not used, so it can just return \code{None}.
|
|
\end{funcdesc}
|
|
\index{profile function}
|
|
\index{profiler}
|
|
|
|
\begin{datadesc}{stdin}
|
|
\dataline{stdout}
|
|
\dataline{stderr}
|
|
File objects corresponding to the interpreter's standard input,
|
|
output and error streams. \code{sys.stdin} is used for all
|
|
interpreter input except for scripts but including calls to
|
|
\code{input()} and \code{raw_input()}. \code{sys.stdout} is used
|
|
for the output of \code{print} and expression statements and for the
|
|
prompts of \code{input()} and \code{raw_input()}. The interpreter's
|
|
own prompts and (almost all of) its error messages go to
|
|
\code{sys.stderr}. \code{sys.stdout} and \code{sys.stderr} needn't
|
|
be built-in file objects: any object is acceptable as long as it has
|
|
a \code{write} method that takes a string argument. (Changing these
|
|
objects doesn't affect the standard I/O streams of processes
|
|
executed by \code{popen()}, \code{system()} or the \code{exec*()}
|
|
family of functions in the \code{os} module.)
|
|
\stmodindex{os}
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{tracebacklimit}
|
|
When this variable is set to an integer value, it determines the
|
|
maximum number of levels of traceback information printed when an
|
|
unhandled exception occurs. The default is 1000. When set to 0 or
|
|
less, all traceback information is suppressed and only the exception
|
|
type and value are printed.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{version}
|
|
A string containing the version number of the Python interpreter.
|
|
\end{datadesc}
|