Doc/lib/libsys.tex

   1 \section{Built-in Module \module{sys}}
   2 \label{module-sys}
   3
   4 \bimodindex{sys}
   5 This module provides access to some variables used or maintained by the
   6 interpreter and to functions that interact strongly with the interpreter.
   7 It is always available.
   8
   9
  10 \begin{datadesc}{argv}
  11   The list of command line arguments passed to a Python script.
  12   \code{argv[0]} is the script name (it is operating system
  13   dependent whether this is a full pathname or not).
  14   If the command was executed using the \samp{-c} command line option
  15   to the interpreter, \code{argv[0]} is set to the string
  16   \code{"-c"}.
  17   If no script name was passed to the Python interpreter,
  18   \code{argv} has zero length.
  19 \end{datadesc}
  20
  21 \begin{datadesc}{builtin_module_names}
  22   A tuple of strings giving the names of all modules that are compiled
  23   into this Python interpreter.  (This information is not available in
  24   any other way --- \code{modules.keys()} only lists the imported
  25   modules.)
  26 \end{datadesc}
  27
  28 \begin{funcdesc}{exc_info}{}
  29 This function returns a tuple of three values that give information
  30 about the exception that is currently being handled.  The information
  31 returned is specific both to the current thread and to the current
  32 stack frame.  If the current stack frame is not handling an exception,
  33 the information is taken from the calling stack frame, or its caller,
  34 and so on until a stack frame is found that is handling an exception.
  35 Here, ``handling an exception'' is defined as ``executing or having
  36 executed an except clause.''  For any stack frame, only
  37 information about the most recently handled exception is accessible.
  38
  39 If no exception is being handled anywhere on the stack, a tuple
  40 containing three \code{None} values is returned.  Otherwise, the
  41 values returned are
  42 \code{(\var{type}, \var{value}, \var{traceback})}.
  43 Their meaning is: \var{type} gets the exception type of the exception
  44 being handled (a string or class object); \var{value} gets the
  45 exception parameter (its \dfn{associated value} or the second argument
  46 to \keyword{raise}, which is always a class instance if the exception
  47 type is a class object); \var{traceback} gets a traceback object (see
  48 the Reference Manual) which encapsulates the call stack at the point
  49 where the exception originally occurred.
  50 \obindex{traceback}
  51
  52 \strong{Warning:} assigning the \var{traceback} return value to a
  53 local variable in a function that is handling an exception will cause
  54 a circular reference. This will prevent anything referenced by a local
  55 variable in the same function or by the traceback from being garbage
  56 collected.  Since most functions don't need access to the traceback,
  57 the best solution is to use something like
  58 \code{type, value = sys.exc_info()[:2]}
  59 to extract only the exception type and value.  If you do need the
  60 traceback, make sure to delete it after use (best done with a
  61 \keyword{try} ... \keyword{finally} statement) or to call
  62 \function{exc_info()} in a function that does not itself handle an
  63 exception.
  64 \end{funcdesc}
  65
  66 \begin{datadesc}{exc_type}
  67 \dataline{exc_value}
  68 \dataline{exc_traceback}
  69 \deprecated {1.5}
  70             {Use \function{exc_info()} instead.}
  71 Since they are global variables, they are not specific to the current
  72 thread, so their use is not safe in a multi-threaded program.  When no
  73 exception is being handled, \code{exc_type} is set to \code{None} and
  74 the other two are undefined.
  75 \end{datadesc}
  76
  77 \begin{datadesc}{exec_prefix}
  78 A string giving the site-specific
  79 directory prefix where the platform-dependent Python files are
  80 installed; by default, this is also \code{"/usr/local"}.  This can be
  81 set at build time with the \code{-}\code{-exec-prefix} argument to the
  82 \program{configure} script.  Specifically, all configuration files
  83 (e.g. the \file{config.h} header file) are installed in the directory
  84 \code{exec_prefix + "/lib/python\var{version}/config"}, and shared library
  85 modules are installed in
  86 \code{exec_prefix + "/lib/python\var{version}/lib-dynload"},
  87 where \var{version} is equal to \code{version[:3]}.
  88 \end{datadesc}
  89
  90 \begin{funcdesc}{exit}{n}
  91   Exit from Python with numeric exit status \var{n}.  This is
  92   implemented by raising the \exception{SystemExit} exception, so cleanup
  93   actions specified by finally clauses of \keyword{try} statements
  94   are honored, and it is possible to catch the exit attempt at an outer
  95   level.
  96 \end{funcdesc}
  97
  98 \begin{datadesc}{exitfunc}
  99   This value is not actually defined by the module, but can be set by
 100   the user (or by a program) to specify a clean-up action at program
 101   exit.  When set, it should be a parameterless function.  This function
 102   will be called when the interpreter exits in any way (except when a
 103   fatal error occurs: in that case the interpreter's internal state
 104   cannot be trusted).
 105 \end{datadesc}
 106
 107 \begin{funcdesc}{getrefcount}{object}
 108 Return the reference count of the \var{object}.  The count returned is
 109 generally one higher than you might expect, because it includes the
 110 (temporary) reference as an argument to \code{getrefcount()}.
 111 \end{funcdesc}
 112
 113 \begin{datadesc}{last_type}
 114 \dataline{last_value}
 115 \dataline{last_traceback}
 116 These three variables are not always defined; they are set when an
 117 exception is not handled and the interpreter prints an error message
 118 and a stack traceback.  Their intended use is to allow an interactive
 119 user to import a debugger module and engage in post-mortem debugging
 120 without having to re-execute the command that caused the error.
 121 (Typical use is \samp{import pdb; pdb.pm()} to enter the post-mortem
 122 debugger; see the chapter ``The Python Debugger'' for more
 123 information.)
 124 \refstmodindex{pdb}
 125
 126 The meaning of the variables is the same
 127 as that of the return values from \function{exc_info()} above.
 128 (Since there is only one interactive thread, thread-safety is not a
 129 concern for these variables, unlike for \code{exc_type} etc.)
 130 \end{datadesc}
 131
 132 \begin{datadesc}{modules}
 133   This is a dictionary that maps module names to modules which have
 134   already been loaded.  This can be manipulated to force reloading of
 135   modules and other tricks.  Note that removing a module from this
 136   dictionary is \emph{not} the same as calling
 137   \function{reload()}\bifuncindex{reload} on the corresponding module
 138   object.
 139 \end{datadesc}
 140
 141 \begin{datadesc}{path}
 142 \indexiii{module}{search}{path}
 143   A list of strings that specifies the search path for modules.
 144   Initialized from the environment variable \code{\$PYTHONPATH}, or an
 145   installation-dependent default.
 146
 147 The first item of this list, \code{path[0]}, is the
 148 directory containing the script that was used to invoke the Python
 149 interpreter.  If the script directory is not available (e.g.  if the
 150 interpreter is invoked interactively or if the script is read from
 151 standard input), \code{path[0]} is the empty string, which directs
 152 Python to search modules in the current directory first.  Notice that
 153 the script directory is inserted \emph{before} the entries inserted as
 154 a result of \code{\$PYTHONPATH}.
 155 \end{datadesc}
 156
 157 \begin{datadesc}{platform}
 158 This string contains a platform identifier, e.g. \code{'sunos5'} or
 159 \code{'linux1'}.  This can be used to append platform-specific
 160 components to \code{path}, for instance.
 161 \end{datadesc}
 162
 163 \begin{datadesc}{prefix}
 164 A string giving the site-specific directory prefix where the platform
 165 independent Python files are installed; by default, this is the string
 166 \code{"/usr/local"}.  This can be set at build time with the
 167 \code{-}\code{-prefix} argument to the \program{configure} script.  The main
 168 collection of Python library modules is installed in the directory
 169 \code{prefix + "/lib/python\var{version}"} while the platform
 170 independent header files (all except \file{config.h}) are stored in
 171 \code{prefix + "/include/python\var{version}"},
 172 where \var{version} is equal to \code{version[:3]}.
 173
 174 \end{datadesc}
 175
 176 \begin{datadesc}{ps1}
 177 \dataline{ps2}
 178 \index{interpreter prompts}
 179 \index{prompts, interpreter}
 180   Strings specifying the primary and secondary prompt of the
 181   interpreter.  These are only defined if the interpreter is in
 182   interactive mode.  Their initial values in this case are
 183   \code{'>>> '} and \code{'... '}.  If a non-string object is assigned
 184   to either variable, its \function{str()} is re-evaluated each time
 185   the interpreter prepares to read a new interactive command; this can
 186   be used to implement a dynamic prompt.
 187 \end{datadesc}
 188
 189 \begin{funcdesc}{setcheckinterval}{interval}
 190 Set the interpreter's ``check interval''.  This integer value
 191 determines how often the interpreter checks for periodic things such
 192 as thread switches and signal handlers.  The default is \code{10}, meaning
 193 the check is performed every 10 Python virtual instructions.  Setting
 194 it to a larger value may increase performance for programs using
 195 threads.  Setting it to a value \code{<=} 0 checks every virtual instruction,
 196 maximizing responsiveness as well as overhead.
 197 \end{funcdesc}
 198
 199 \begin{funcdesc}{settrace}{tracefunc}
 200   Set the system's trace function, which allows you to implement a
 201   Python source code debugger in Python.  See section ``How It Works''
 202   in the chapter on the Python Debugger.
 203 \end{funcdesc}
 204 \index{trace function}
 205 \index{debugger}
 206
 207 \begin{funcdesc}{setprofile}{profilefunc}
 208   Set the system's profile function, which allows you to implement a
 209   Python source code profiler in Python.  See the chapter on the
 210   Python Profiler.  The system's profile function
 211   is called similarly to the system's trace function (see
 212   \function{settrace()}), but it isn't called for each executed line of
 213   code (only on call and return and when an exception occurs).  Also,
 214   its return value is not used, so it can just return \code{None}.
 215 \end{funcdesc}
 216 \index{profile function}
 217 \index{profiler}
 218
 219 \begin{datadesc}{stdin}
 220 \dataline{stdout}
 221 \dataline{stderr}
 222   File objects corresponding to the interpreter's standard input,
 223   output and error streams.  \code{stdin} is used for all
 224   interpreter input except for scripts but including calls to
 225   \function{input()}\bifuncindex{input} and
 226   \function{raw_input()}\bifuncindex{raw_input}.  \code{stdout} is used
 227   for the output of \keyword{print} and expression statements and for the
 228   prompts of \function{input()} and \function{raw_input()}.  The interpreter's
 229   own prompts and (almost all of) its error messages go to
 230   \code{stderr}.  \code{stdout} and \code{stderr} needn't
 231   be built-in file objects: any object is acceptable as long as it has
 232   a \method{write()} method that takes a string argument.  (Changing these
 233   objects doesn't affect the standard I/O streams of processes
 234   executed by \function{os.popen()}, \function{os.system()} or the
 235   \function{exec*()} family of functions in the \module{os} module.)
 236 \refstmodindex{os}
 237 \end{datadesc}
 238
 239 \begin{datadesc}{tracebacklimit}
 240 When this variable is set to an integer value, it determines the
 241 maximum number of levels of traceback information printed when an
 242 unhandled exception occurs.  The default is \code{1000}.  When set to
 243 0 or less, all traceback information is suppressed and only the
 244 exception type and value are printed.
 245 \end{datadesc}
 246
 247 \begin{datadesc}{version}
 248 A string containing the version number of the Python interpreter.
 249 \end{datadesc}