Mercurial > cpython-lru_cache-weakref

annotate Doc/libsys.tex @ 6719:faebc1940432 legacy-trunk

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