Doc/lib/libsys.tex

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