Doc/lib/libsys.tex

   1 \section{\module{sys} ---
   2          System-specific parameters and functions}
   3
   4 \declaremodule{builtin}{sys}
   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 \programopt{-c} command line
  17   option 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 directory prefix where the
  85 platform-dependent Python files are installed; by default, this is
  86 also \code{'/usr/local'}.  This can be set at build time with the
  87 \programopt{-}\programopt{-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
  91 library modules are installed in \code{exec_prefix +
  92 '/lib/python\var{version}/lib-dynload'}, where \var{version} is equal
  93 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}{\optional{arg}}
 102 Exit from Python.  This is implemented by raising the
 103 \exception{SystemExit} exception, so cleanup actions specified by
 104 finally clauses of \keyword{try} statements are honored, and it is
 105 possible to intercept the exit attempt at an outer level.  The
 106 optional argument \var{arg} can be an integer giving the exit status
 107 (defaulting to zero), or another type of object.  If it is an integer,
 108 zero is considered ``successful termination'' and any nonzero value is
 109 considered ``abnormal termination'' by shells and the like.  Most
 110 systems require it to be in the range 0-127, and produce undefined
 111 results otherwise.  Some systems have a convention for assigning
 112 specific meanings to specific exit codes, but these are generally
 113 underdeveloped; Unix programs generally use 2 for command line syntax
 114 errors and 1 for all other kind of errors.  If another type of object
 115 is passed, \code{None} is equivalent to passing zero, and any other
 116 object is printed to \code{sys.stderr} and results in an exit code of
 117 1.  In particular, \code{sys.exit("some error message")} is a quick
 118 way to exit a program when an error occurs.
 119 \end{funcdesc}
 120
 121 \begin{datadesc}{exitfunc}
 122   This value is not actually defined by the module, but can be set by
 123   the user (or by a program) to specify a clean-up action at program
 124   exit.  When set, it should be a parameterless function.  This function
 125   will be called when the interpreter exits.  Note: the exit function
 126   is not called when the program is killed by a signal, when a Python
 127   fatal internal error is detected, or when \code{os._exit()} is called.
 128 \end{datadesc}
 129
 130 \begin{funcdesc}{getrefcount}{object}
 131 Return the reference count of the \var{object}.  The count returned is
 132 generally one higher than you might expect, because it includes the
 133 (temporary) reference as an argument to \function{getrefcount()}.
 134 \end{funcdesc}
 135
 136 \begin{datadesc}{last_type}
 137 \dataline{last_value}
 138 \dataline{last_traceback}
 139 These three variables are not always defined; they are set when an
 140 exception is not handled and the interpreter prints an error message
 141 and a stack traceback.  Their intended use is to allow an interactive
 142 user to import a debugger module and engage in post-mortem debugging
 143 without having to re-execute the command that caused the error.
 144 (Typical use is \samp{import pdb; pdb.pm()} to enter the post-mortem
 145 debugger; see the chapter ``The Python Debugger'' for more
 146 information.)
 147 \refstmodindex{pdb}
 148
 149 The meaning of the variables is the same
 150 as that of the return values from \function{exc_info()} above.
 151 (Since there is only one interactive thread, thread-safety is not a
 152 concern for these variables, unlike for \code{exc_type} etc.)
 153 \end{datadesc}
 154
 155 \begin{datadesc}{maxint}
 156 The largest positive integer supported by Python's regular integer
 157 type.  This is at least 2**31-1.  The largest negative integer is
 158 \code{-maxint-1} -- the asymmetry results from the use of 2's
 159 complement binary arithmetic.
 160 \end{datadesc}
 161
 162 \begin{datadesc}{modules}
 163   This is a dictionary that maps module names to modules which have
 164   already been loaded.  This can be manipulated to force reloading of
 165   modules and other tricks.  Note that removing a module from this
 166   dictionary is \emph{not} the same as calling
 167   \function{reload()}\bifuncindex{reload} on the corresponding module
 168   object.
 169 \end{datadesc}
 170
 171 \begin{datadesc}{path}
 172 \indexiii{module}{search}{path}
 173   A list of strings that specifies the search path for modules.
 174   Initialized from the environment variable \envvar{PYTHONPATH}, or an
 175   installation-dependent default.
 176
 177 The first item of this list, \code{path[0]}, is the
 178 directory containing the script that was used to invoke the Python
 179 interpreter.  If the script directory is not available (e.g.  if the
 180 interpreter is invoked interactively or if the script is read from
 181 standard input), \code{path[0]} is the empty string, which directs
 182 Python to search modules in the current directory first.  Notice that
 183 the script directory is inserted \emph{before} the entries inserted as
 184 a result of \envvar{PYTHONPATH}.
 185 \end{datadesc}
 186
 187 \begin{datadesc}{platform}
 188 This string contains a platform identifier, e.g. \code{'sunos5'} or
 189 \code{'linux1'}.  This can be used to append platform-specific
 190 components to \code{path}, for instance.
 191 \end{datadesc}
 192
 193 \begin{datadesc}{prefix}
 194 A string giving the site-specific directory prefix where the platform
 195 independent Python files are installed; by default, this is the string
 196 \code{'/usr/local'}.  This can be set at build time with the
 197 \programopt{-}\programopt{-prefix} argument to the
 198 \program{configure} script.  The main collection of Python library
 199 modules is installed in the directory \code{prefix +
 200 '/lib/python\var{version}'} while the platform independent header
 201 files (all except \file{config.h}) are stored in \code{prefix +
 202 '/include/python\var{version}'}, where \var{version} is equal to
 203 \code{version[:3]}.
 204 \end{datadesc}
 205
 206 \begin{datadesc}{ps1}
 207 \dataline{ps2}
 208 \index{interpreter prompts}
 209 \index{prompts, interpreter}
 210   Strings specifying the primary and secondary prompt of the
 211   interpreter.  These are only defined if the interpreter is in
 212   interactive mode.  Their initial values in this case are
 213   \code{'>>> '} and \code{'... '}.  If a non-string object is assigned
 214   to either variable, its \function{str()} is re-evaluated each time
 215   the interpreter prepares to read a new interactive command; this can
 216   be used to implement a dynamic prompt.
 217 \end{datadesc}
 218
 219 \begin{funcdesc}{setcheckinterval}{interval}
 220 Set the interpreter's ``check interval''.  This integer value
 221 determines how often the interpreter checks for periodic things such
 222 as thread switches and signal handlers.  The default is \code{10}, meaning
 223 the check is performed every 10 Python virtual instructions.  Setting
 224 it to a larger value may increase performance for programs using
 225 threads.  Setting it to a value \code{<=} 0 checks every virtual instruction,
 226 maximizing responsiveness as well as overhead.
 227 \end{funcdesc}
 228
 229 \begin{funcdesc}{setprofile}{profilefunc}
 230   Set the system's profile function, which allows you to implement a
 231   Python source code profiler in Python.  See the chapter on the
 232   Python Profiler.  The system's profile function
 233   is called similarly to the system's trace function (see
 234   \function{settrace()}), but it isn't called for each executed line of
 235   code (only on call and return and when an exception occurs).  Also,
 236   its return value is not used, so it can just return \code{None}.
 237 \end{funcdesc}
 238 \index{profile function}
 239 \index{profiler}
 240
 241 \begin{funcdesc}{settrace}{tracefunc}
 242   Set the system's trace function, which allows you to implement a
 243   Python source code debugger in Python.  See section ``How It Works''
 244   in the chapter on the Python Debugger.
 245 \end{funcdesc}
 246 \index{trace function}
 247 \index{debugger}
 248
 249 \begin{datadesc}{stdin}
 250 \dataline{stdout}
 251 \dataline{stderr}
 252   File objects corresponding to the interpreter's standard input,
 253   output and error streams.  \code{stdin} is used for all
 254   interpreter input except for scripts but including calls to
 255   \function{input()}\bifuncindex{input} and
 256   \function{raw_input()}\bifuncindex{raw_input}.  \code{stdout} is used
 257   for the output of \keyword{print} and expression statements and for the
 258   prompts of \function{input()} and \function{raw_input()}.  The interpreter's
 259   own prompts and (almost all of) its error messages go to
 260   \code{stderr}.  \code{stdout} and \code{stderr} needn't
 261   be built-in file objects: any object is acceptable as long as it has
 262   a \method{write()} method that takes a string argument.  (Changing these
 263   objects doesn't affect the standard I/O streams of processes
 264   executed by \function{os.popen()}, \function{os.system()} or the
 265   \function{exec*()} family of functions in the \refmodule{os} module.)
 266 \refstmodindex{os}
 267 \end{datadesc}
 268
 269 \begin{datadesc}{__stdin__}
 270 \dataline{__stdout__}
 271 \dataline{__stderr__}
 272 These objects contain the original values of \code{stdin},
 273 \code{stderr} and \code{stdout} at the start of the program.  They are
 274 used during finalization, and could be useful to restore the actual
 275 files to known working file objects in case they have been overwritten
 276 with a broken object.
 277 \end{datadesc}
 278
 279 \begin{datadesc}{tracebacklimit}
 280 When this variable is set to an integer value, it determines the
 281 maximum number of levels of traceback information printed when an
 282 unhandled exception occurs.  The default is \code{1000}.  When set to
 283 0 or less, all traceback information is suppressed and only the
 284 exception type and value are printed.
 285 \end{datadesc}
 286
 287 \begin{datadesc}{version}
 288 A string containing the version number of the Python interpreter.
 289 \end{datadesc}