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