blob: a92201cb2acdd68d1a2043f7f4a8e0c50a8430b2 [file] [log] [blame]
Fred Drake295da241998-08-10 19:42:37 +00001\section{\module{sys} ---
Fred Drakeffbe6871999-04-22 21:23:22 +00002 System-specific parameters and functions}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +00003
Fred Drakeffbe6871999-04-22 21:23:22 +00004\declaremodule{builtin}{sys}
Fred Drake295da241998-08-10 19:42:37 +00005\modulesynopsis{Access system-specific parameters and functions.}
Fred Drakeb91e9341998-07-23 17:59:49 +00006
Guido van Rossum5fdeeea1994-01-02 01:22:07 +00007This module provides access to some variables used or maintained by the
8interpreter and to functions that interact strongly with the interpreter.
9It is always available.
10
Guido van Rossum470be141995-03-17 16:07:09 +000011
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000012\begin{datadesc}{argv}
13 The list of command line arguments passed to a Python script.
Fred Drake0fd72ee1998-03-08 05:43:51 +000014 \code{argv[0]} is the script name (it is operating system
Guido van Rossum470be141995-03-17 16:07:09 +000015 dependent whether this is a full pathname or not).
Fred Drake268df271999-11-09 19:45:59 +000016 If the command was executed using the \programopt{-c} command line
17 option to the interpreter, \code{argv[0]} is set to the string
Fred Drakeb91e9341998-07-23 17:59:49 +000018 \code{'-c'}.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000019 If no script name was passed to the Python interpreter,
Fred Drake0fd72ee1998-03-08 05:43:51 +000020 \code{argv} has zero length.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000021\end{datadesc}
22
23\begin{datadesc}{builtin_module_names}
Guido van Rossum0d2971b1997-01-06 23:01:02 +000024 A tuple of strings giving the names of all modules that are compiled
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000025 into this Python interpreter. (This information is not available in
Fred Drake0fd72ee1998-03-08 05:43:51 +000026 any other way --- \code{modules.keys()} only lists the imported
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000027 modules.)
28\end{datadesc}
29
Guido van Rossum3e5fe421998-06-10 17:57:44 +000030\begin{datadesc}{copyright}
31A string containing the copyright pertaining to the Python interpreter.
32\end{datadesc}
33
Fred Drake38e5d272000-04-03 20:13:55 +000034\begin{datadesc}{dllhandle}
35Integer specifying the handle of the Python DLL.
36Availability: Windows.
37\end{datadesc}
38
Guido van Rossum871cf161997-10-20 22:38:43 +000039\begin{funcdesc}{exc_info}{}
40This function returns a tuple of three values that give information
41about the exception that is currently being handled. The information
42returned is specific both to the current thread and to the current
43stack frame. If the current stack frame is not handling an exception,
44the information is taken from the calling stack frame, or its caller,
45and so on until a stack frame is found that is handling an exception.
46Here, ``handling an exception'' is defined as ``executing or having
Fred Drake0fd72ee1998-03-08 05:43:51 +000047executed an except clause.'' For any stack frame, only
Guido van Rossum871cf161997-10-20 22:38:43 +000048information about the most recently handled exception is accessible.
49
50If no exception is being handled anywhere on the stack, a tuple
51containing three \code{None} values is returned. Otherwise, the
52values returned are
53\code{(\var{type}, \var{value}, \var{traceback})}.
54Their meaning is: \var{type} gets the exception type of the exception
55being handled (a string or class object); \var{value} gets the
56exception parameter (its \dfn{associated value} or the second argument
Fred Drake0fd72ee1998-03-08 05:43:51 +000057to \keyword{raise}, which is always a class instance if the exception
Guido van Rossum871cf161997-10-20 22:38:43 +000058type is a class object); \var{traceback} gets a traceback object (see
59the Reference Manual) which encapsulates the call stack at the point
60where the exception originally occurred.
61\obindex{traceback}
62
63\strong{Warning:} assigning the \var{traceback} return value to a
64local variable in a function that is handling an exception will cause
65a circular reference. This will prevent anything referenced by a local
66variable in the same function or by the traceback from being garbage
67collected. Since most functions don't need access to the traceback,
68the best solution is to use something like
69\code{type, value = sys.exc_info()[:2]}
70to extract only the exception type and value. If you do need the
71traceback, make sure to delete it after use (best done with a
Fred Drake0fd72ee1998-03-08 05:43:51 +000072\keyword{try} ... \keyword{finally} statement) or to call
73\function{exc_info()} in a function that does not itself handle an
74exception.
Guido van Rossum871cf161997-10-20 22:38:43 +000075\end{funcdesc}
76
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000077\begin{datadesc}{exc_type}
78\dataline{exc_value}
79\dataline{exc_traceback}
Fred Drake0fd72ee1998-03-08 05:43:51 +000080\deprecated {1.5}
81 {Use \function{exc_info()} instead.}
82Since they are global variables, they are not specific to the current
Guido van Rossum871cf161997-10-20 22:38:43 +000083thread, so their use is not safe in a multi-threaded program. When no
Fred Drake0fd72ee1998-03-08 05:43:51 +000084exception is being handled, \code{exc_type} is set to \code{None} and
85the other two are undefined.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000086\end{datadesc}
87
Guido van Rossum0a3c7531997-06-02 17:32:41 +000088\begin{datadesc}{exec_prefix}
Fred Drake268df271999-11-09 19:45:59 +000089A string giving the site-specific directory prefix where the
90platform-dependent Python files are installed; by default, this is
91also \code{'/usr/local'}. This can be set at build time with the
Fred Drakeee775a12000-04-11 19:46:40 +000092\longprogramopt{exec-prefix} argument to the
Fred Drake0fd72ee1998-03-08 05:43:51 +000093\program{configure} script. Specifically, all configuration files
94(e.g. the \file{config.h} header file) are installed in the directory
Fred Drake268df271999-11-09 19:45:59 +000095\code{exec_prefix + '/lib/python\var{version}/config'}, and shared
96library modules are installed in \code{exec_prefix +
97'/lib/python\var{version}/lib-dynload'}, where \var{version} is equal
98to \code{version[:3]}.
Guido van Rossum0a3c7531997-06-02 17:32:41 +000099\end{datadesc}
100
Guido van Rossum3e5fe421998-06-10 17:57:44 +0000101\begin{datadesc}{executable}
102A string giving the name of the executable binary for the Python
103interpreter, on systems where this makes sense.
104\end{datadesc}
105
Guido van Rossum04307ce1998-11-23 17:49:53 +0000106\begin{funcdesc}{exit}{\optional{arg}}
107Exit from Python. This is implemented by raising the
108\exception{SystemExit} exception, so cleanup actions specified by
109finally clauses of \keyword{try} statements are honored, and it is
110possible to intercept the exit attempt at an outer level. The
111optional argument \var{arg} can be an integer giving the exit status
112(defaulting to zero), or another type of object. If it is an integer,
113zero is considered ``successful termination'' and any nonzero value is
114considered ``abnormal termination'' by shells and the like. Most
115systems require it to be in the range 0-127, and produce undefined
116results otherwise. Some systems have a convention for assigning
117specific meanings to specific exit codes, but these are generally
118underdeveloped; Unix programs generally use 2 for command line syntax
119errors and 1 for all other kind of errors. If another type of object
120is passed, \code{None} is equivalent to passing zero, and any other
121object is printed to \code{sys.stderr} and results in an exit code of
1221. In particular, \code{sys.exit("some error message")} is a quick
123way to exit a program when an error occurs.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000124\end{funcdesc}
125
126\begin{datadesc}{exitfunc}
127 This value is not actually defined by the module, but can be set by
128 the user (or by a program) to specify a clean-up action at program
129 exit. When set, it should be a parameterless function. This function
Guido van Rossum5fc9c861999-03-25 20:30:00 +0000130 will be called when the interpreter exits. Note: the exit function
131 is not called when the program is killed by a signal, when a Python
132 fatal internal error is detected, or when \code{os._exit()} is called.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000133\end{datadesc}
134
Guido van Rossum6e91c6a1998-02-07 21:17:05 +0000135\begin{funcdesc}{getrefcount}{object}
136Return the reference count of the \var{object}. The count returned is
137generally one higher than you might expect, because it includes the
Fred Drakeb91e9341998-07-23 17:59:49 +0000138(temporary) reference as an argument to \function{getrefcount()}.
Guido van Rossum6e91c6a1998-02-07 21:17:05 +0000139\end{funcdesc}
140
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000141\begin{datadesc}{last_type}
142\dataline{last_value}
143\dataline{last_traceback}
Guido van Rossum871cf161997-10-20 22:38:43 +0000144These three variables are not always defined; they are set when an
145exception is not handled and the interpreter prints an error message
146and a stack traceback. Their intended use is to allow an interactive
147user to import a debugger module and engage in post-mortem debugging
148without having to re-execute the command that caused the error.
Fred Drake0fd72ee1998-03-08 05:43:51 +0000149(Typical use is \samp{import pdb; pdb.pm()} to enter the post-mortem
Guido van Rossum871cf161997-10-20 22:38:43 +0000150debugger; see the chapter ``The Python Debugger'' for more
151information.)
Fred Drake54820dc1997-12-15 21:56:05 +0000152\refstmodindex{pdb}
Guido van Rossum871cf161997-10-20 22:38:43 +0000153
154The meaning of the variables is the same
Fred Drake0fd72ee1998-03-08 05:43:51 +0000155as that of the return values from \function{exc_info()} above.
Guido van Rossum871cf161997-10-20 22:38:43 +0000156(Since there is only one interactive thread, thread-safety is not a
Fred Drake0fd72ee1998-03-08 05:43:51 +0000157concern for these variables, unlike for \code{exc_type} etc.)
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000158\end{datadesc}
159
Guido van Rossum3e5fe421998-06-10 17:57:44 +0000160\begin{datadesc}{maxint}
161The largest positive integer supported by Python's regular integer
162type. This is at least 2**31-1. The largest negative integer is
163\code{-maxint-1} -- the asymmetry results from the use of 2's
164complement binary arithmetic.
165\end{datadesc}
166
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000167\begin{datadesc}{modules}
Fred Drake0fd72ee1998-03-08 05:43:51 +0000168 This is a dictionary that maps module names to modules which have
169 already been loaded. This can be manipulated to force reloading of
170 modules and other tricks. Note that removing a module from this
171 dictionary is \emph{not} the same as calling
172 \function{reload()}\bifuncindex{reload} on the corresponding module
173 object.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000174\end{datadesc}
175
176\begin{datadesc}{path}
Fred Drake2b67bee1998-01-13 18:35:51 +0000177\indexiii{module}{search}{path}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000178 A list of strings that specifies the search path for modules.
Fred Drakeb91e9341998-07-23 17:59:49 +0000179 Initialized from the environment variable \envvar{PYTHONPATH}, or an
Guido van Rossum0a3c7531997-06-02 17:32:41 +0000180 installation-dependent default.
181
Fred Drake0fd72ee1998-03-08 05:43:51 +0000182The first item of this list, \code{path[0]}, is the
Guido van Rossum0a3c7531997-06-02 17:32:41 +0000183directory containing the script that was used to invoke the Python
184interpreter. If the script directory is not available (e.g. if the
185interpreter is invoked interactively or if the script is read from
Fred Drake0fd72ee1998-03-08 05:43:51 +0000186standard input), \code{path[0]} is the empty string, which directs
Guido van Rossum0a3c7531997-06-02 17:32:41 +0000187Python to search modules in the current directory first. Notice that
Fred Drake54820dc1997-12-15 21:56:05 +0000188the script directory is inserted \emph{before} the entries inserted as
Fred Drakeb91e9341998-07-23 17:59:49 +0000189a result of \envvar{PYTHONPATH}.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000190\end{datadesc}
191
Guido van Rossum6b686e91995-07-07 23:00:35 +0000192\begin{datadesc}{platform}
Fred Drake0fd72ee1998-03-08 05:43:51 +0000193This string contains a platform identifier, e.g. \code{'sunos5'} or
194\code{'linux1'}. This can be used to append platform-specific
195components to \code{path}, for instance.
Guido van Rossum0a3c7531997-06-02 17:32:41 +0000196\end{datadesc}
197
198\begin{datadesc}{prefix}
199A string giving the site-specific directory prefix where the platform
200independent Python files are installed; by default, this is the string
Fred Drakeb91e9341998-07-23 17:59:49 +0000201\code{'/usr/local'}. This can be set at build time with the
Fred Drakeee775a12000-04-11 19:46:40 +0000202\longprogramopt{prefix} argument to the
Fred Drake268df271999-11-09 19:45:59 +0000203\program{configure} script. The main collection of Python library
204modules is installed in the directory \code{prefix +
205'/lib/python\var{version}'} while the platform independent header
206files (all except \file{config.h}) are stored in \code{prefix +
207'/include/python\var{version}'}, where \var{version} is equal to
208\code{version[:3]}.
Guido van Rossum6b686e91995-07-07 23:00:35 +0000209\end{datadesc}
210
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000211\begin{datadesc}{ps1}
212\dataline{ps2}
Fred Drakee6cedb31998-04-03 07:05:16 +0000213\index{interpreter prompts}
214\index{prompts, interpreter}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000215 Strings specifying the primary and secondary prompt of the
216 interpreter. These are only defined if the interpreter is in
217 interactive mode. Their initial values in this case are
Guido van Rossumee9f8201997-11-25 21:12:27 +0000218 \code{'>>> '} and \code{'... '}. If a non-string object is assigned
Fred Drake0fd72ee1998-03-08 05:43:51 +0000219 to either variable, its \function{str()} is re-evaluated each time
220 the interpreter prepares to read a new interactive command; this can
221 be used to implement a dynamic prompt.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000222\end{datadesc}
223
Guido van Rossum9c51e411995-01-10 10:50:58 +0000224\begin{funcdesc}{setcheckinterval}{interval}
225Set the interpreter's ``check interval''. This integer value
226determines how often the interpreter checks for periodic things such
Fred Drake0fd72ee1998-03-08 05:43:51 +0000227as thread switches and signal handlers. The default is \code{10}, meaning
Guido van Rossum9c51e411995-01-10 10:50:58 +0000228the check is performed every 10 Python virtual instructions. Setting
229it to a larger value may increase performance for programs using
Guido van Rossumf259efe1997-11-25 01:00:40 +0000230threads. Setting it to a value \code{<=} 0 checks every virtual instruction,
Guido van Rossum9c51e411995-01-10 10:50:58 +0000231maximizing responsiveness as well as overhead.
Guido van Rossum7f49b7a1995-01-12 12:38:46 +0000232\end{funcdesc}
Guido van Rossum9c51e411995-01-10 10:50:58 +0000233
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000234\begin{funcdesc}{setprofile}{profilefunc}
235 Set the system's profile function, which allows you to implement a
Guido van Rossum470be141995-03-17 16:07:09 +0000236 Python source code profiler in Python. See the chapter on the
237 Python Profiler. The system's profile function
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000238 is called similarly to the system's trace function (see
Fred Drake0fd72ee1998-03-08 05:43:51 +0000239 \function{settrace()}), but it isn't called for each executed line of
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000240 code (only on call and return and when an exception occurs). Also,
241 its return value is not used, so it can just return \code{None}.
242\end{funcdesc}
243\index{profile function}
Guido van Rossum470be141995-03-17 16:07:09 +0000244\index{profiler}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000245
Guido van Rossum3e5fe421998-06-10 17:57:44 +0000246\begin{funcdesc}{settrace}{tracefunc}
247 Set the system's trace function, which allows you to implement a
248 Python source code debugger in Python. See section ``How It Works''
249 in the chapter on the Python Debugger.
250\end{funcdesc}
251\index{trace function}
252\index{debugger}
253
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000254\begin{datadesc}{stdin}
255\dataline{stdout}
256\dataline{stderr}
257 File objects corresponding to the interpreter's standard input,
Fred Drake0fd72ee1998-03-08 05:43:51 +0000258 output and error streams. \code{stdin} is used for all
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000259 interpreter input except for scripts but including calls to
Fred Drake0fd72ee1998-03-08 05:43:51 +0000260 \function{input()}\bifuncindex{input} and
261 \function{raw_input()}\bifuncindex{raw_input}. \code{stdout} is used
262 for the output of \keyword{print} and expression statements and for the
263 prompts of \function{input()} and \function{raw_input()}. The interpreter's
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000264 own prompts and (almost all of) its error messages go to
Fred Drake0fd72ee1998-03-08 05:43:51 +0000265 \code{stderr}. \code{stdout} and \code{stderr} needn't
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000266 be built-in file objects: any object is acceptable as long as it has
Fred Drake0fd72ee1998-03-08 05:43:51 +0000267 a \method{write()} method that takes a string argument. (Changing these
Guido van Rossum470be141995-03-17 16:07:09 +0000268 objects doesn't affect the standard I/O streams of processes
Fred Drake0fd72ee1998-03-08 05:43:51 +0000269 executed by \function{os.popen()}, \function{os.system()} or the
Fred Drakeffbe6871999-04-22 21:23:22 +0000270 \function{exec*()} family of functions in the \refmodule{os} module.)
Fred Drake54820dc1997-12-15 21:56:05 +0000271\refstmodindex{os}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000272\end{datadesc}
273
Guido van Rossum3e5fe421998-06-10 17:57:44 +0000274\begin{datadesc}{__stdin__}
275\dataline{__stdout__}
276\dataline{__stderr__}
277These objects contain the original values of \code{stdin},
278\code{stderr} and \code{stdout} at the start of the program. They are
279used during finalization, and could be useful to restore the actual
280files to known working file objects in case they have been overwritten
281with a broken object.
282\end{datadesc}
283
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000284\begin{datadesc}{tracebacklimit}
285When this variable is set to an integer value, it determines the
286maximum number of levels of traceback information printed when an
Fred Drake0fd72ee1998-03-08 05:43:51 +0000287unhandled exception occurs. The default is \code{1000}. When set to
2880 or less, all traceback information is suppressed and only the
289exception type and value are printed.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000290\end{datadesc}
Guido van Rossum0a3c7531997-06-02 17:32:41 +0000291
292\begin{datadesc}{version}
Fred Drake38e5d272000-04-03 20:13:55 +0000293A string containing the version number of the Python interpreter plus
294additional information on the build number and compiler used. It has
295a value of the form \code{'\var{version} (\#\var{build_number},
296\var{build_date}, \var{build_time}) [\var{compiler}]'}. The first
297three characters are used to identify the version in the installation
298directories (where appropriate on each platform). An example:
299
300\begin{verbatim}
301>>> import sys
302>>> sys.version
303'1.5.2 (#0 Apr 13 1999, 10:51:12) [MSC 32 bit (Intel)]'
304\end{verbatim}
305\end{datadesc}
306
307\begin{datadesc}{winver}
308The version number used to form registry keys on Windows platforms.
309This is stored as string resource 1000 in the Python DLL. The value
310is normally the first three characters of \constant{version}. It is
311provided in the \module{sys} module for informational purposes;
312modifying this value has no effect on the registry keys used by
313Python.
314Availability: Windows.
Guido van Rossum0a3c7531997-06-02 17:32:41 +0000315\end{datadesc}