Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 1 | \section{Built-in Module \sectcode{sys}} |
| 2 | |
| 3 | \bimodindex{sys} |
| 4 | This module provides access to some variables used or maintained by the |
| 5 | interpreter and to functions that interact strongly with the interpreter. |
| 6 | It is always available. |
| 7 | |
| 8 | \renewcommand{\indexsubitem}{(in module sys)} |
| 9 | \begin{datadesc}{argv} |
| 10 | The list of command line arguments passed to a Python script. |
| 11 | \code{sys.argv[0]} is the script name. |
| 12 | If no script name was passed to the Python interpreter, |
| 13 | \code{sys.argv} is empty. |
| 14 | \end{datadesc} |
| 15 | |
| 16 | \begin{datadesc}{builtin_module_names} |
| 17 | A list of strings giving the names of all modules that are compiled |
| 18 | into this Python interpreter. (This information is not available in |
| 19 | any other way --- \code{sys.modules.keys()} only lists the imported |
| 20 | modules.) |
| 21 | \end{datadesc} |
| 22 | |
| 23 | \begin{datadesc}{exc_type} |
| 24 | \dataline{exc_value} |
| 25 | \dataline{exc_traceback} |
| 26 | These three variables are not always defined; they are set when an |
| 27 | exception handler (an \code{except} clause of a \code{try} statement) is |
| 28 | invoked. Their meaning is: \code{exc_type} gets the exception type of |
| 29 | the exception being handled; \code{exc_value} gets the exception |
| 30 | parameter (its \dfn{associated value} or the second argument to |
| 31 | \code{raise}); \code{exc_traceback} gets a traceback object which |
| 32 | encapsulates the call stack at the point where the exception |
| 33 | originally occurred. |
| 34 | \end{datadesc} |
| 35 | |
| 36 | \begin{funcdesc}{exit}{n} |
| 37 | Exit from Python with numeric exit status \var{n}. This is |
| 38 | implemented by raising the \code{SystemExit} exception, so cleanup |
| 39 | actions specified by \code{finally} clauses of \code{try} statements |
| 40 | are honored, and it is possible to catch the exit attempt at an outer |
| 41 | level. |
| 42 | \end{funcdesc} |
| 43 | |
| 44 | \begin{datadesc}{exitfunc} |
| 45 | This value is not actually defined by the module, but can be set by |
| 46 | the user (or by a program) to specify a clean-up action at program |
| 47 | exit. When set, it should be a parameterless function. This function |
| 48 | will be called when the interpreter exits in any way (but not when a |
| 49 | fatal error occurs: in that case the interpreter's internal state |
| 50 | cannot be trusted). |
| 51 | \end{datadesc} |
| 52 | |
| 53 | \begin{datadesc}{last_type} |
| 54 | \dataline{last_value} |
| 55 | \dataline{last_traceback} |
| 56 | These three variables are not always defined; they are set when an |
| 57 | exception is not handled and the interpreter prints an error message |
| 58 | and a stack traceback. Their intended use is to allow an interactive |
| 59 | user to import a debugger module and engage in post-mortem debugging |
Guido van Rossum | 16d6e71 | 1994-08-08 12:30:22 +0000 | [diff] [blame] | 60 | without having to re-execute the command that caused the error (which |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 61 | may be hard to reproduce). The meaning of the variables is the same |
| 62 | as that of \code{exc_type}, \code{exc_value} and \code{exc_tracaback}, |
| 63 | respectively. |
| 64 | \end{datadesc} |
| 65 | |
| 66 | \begin{datadesc}{modules} |
| 67 | Gives the list of modules that have already been loaded. |
| 68 | This can be manipulated to force reloading of modules and other tricks. |
| 69 | \end{datadesc} |
| 70 | |
| 71 | \begin{datadesc}{path} |
| 72 | A list of strings that specifies the search path for modules. |
| 73 | Initialized from the environment variable \code{PYTHONPATH}, or an |
| 74 | installation-dependent default. |
| 75 | \end{datadesc} |
| 76 | |
| 77 | \begin{datadesc}{ps1} |
| 78 | \dataline{ps2} |
| 79 | Strings specifying the primary and secondary prompt of the |
| 80 | interpreter. These are only defined if the interpreter is in |
| 81 | interactive mode. Their initial values in this case are |
| 82 | \code{'>>> '} and \code{'... '}. |
| 83 | \end{datadesc} |
| 84 | |
| 85 | \begin{funcdesc}{settrace}{tracefunc} |
| 86 | Set the system's trace function, which allows you to implement a |
| 87 | Python source code debugger in Python. The standard modules |
| 88 | \code{pdb} and \code{wdb} are such debuggers; the difference is that |
| 89 | \code{wdb} uses windows and needs STDWIN, while \code{pdb} has a |
| 90 | line-oriented interface not unlike dbx. See the file \file{pdb.doc} |
| 91 | in the Python library source directory for more documentation (both |
| 92 | about \code{pdb} and \code{sys.trace}). |
| 93 | \end{funcdesc} |
| 94 | \ttindex{pdb} |
| 95 | \ttindex{wdb} |
| 96 | \index{trace function} |
| 97 | |
| 98 | \begin{funcdesc}{setprofile}{profilefunc} |
| 99 | Set the system's profile function, which allows you to implement a |
| 100 | Python source code profiler in Python. The system's profile function |
| 101 | is called similarly to the system's trace function (see |
| 102 | \code{sys.settrace}), but it isn't called for each executed line of |
| 103 | code (only on call and return and when an exception occurs). Also, |
| 104 | its return value is not used, so it can just return \code{None}. |
| 105 | \end{funcdesc} |
| 106 | \index{profile function} |
| 107 | |
| 108 | \begin{datadesc}{stdin} |
| 109 | \dataline{stdout} |
| 110 | \dataline{stderr} |
| 111 | File objects corresponding to the interpreter's standard input, |
| 112 | output and error streams. \code{sys.stdin} is used for all |
| 113 | interpreter input except for scripts but including calls to |
| 114 | \code{input()} and \code{raw_input()}. \code{sys.stdout} is used |
| 115 | for the output of \code{print} and expression statements and for the |
| 116 | prompts of \code{input()} and \code{raw_input()}. The interpreter's |
| 117 | own prompts and (almost all of) its error messages go to |
| 118 | \code{sys.stderr}. \code{sys.stdout} and \code{sys.stderr} needn't |
| 119 | be built-in file objects: any object is acceptable as long as it has |
| 120 | a \code{write} method that takes a string argument. |
| 121 | \end{datadesc} |
| 122 | |
| 123 | \begin{datadesc}{tracebacklimit} |
| 124 | When this variable is set to an integer value, it determines the |
| 125 | maximum number of levels of traceback information printed when an |
| 126 | unhandled exception occurs. The default is 1000. When set to 0 or |
| 127 | less, all traceback information is suppressed and only the exception |
| 128 | type and value are printed. |
| 129 | \end{datadesc} |