| \section{\module{sys} --- |
| System-specific parameters and functions} |
| |
| \declaremodule{builtin}{sys} |
| \modulesynopsis{Access system-specific parameters and functions.} |
| |
| This module provides access to some variables used or maintained by the |
| interpreter and to functions that interact strongly with the interpreter. |
| It is always available. |
| |
| |
| \begin{datadesc}{argv} |
| The list of command line arguments passed to a Python script. |
| \code{argv[0]} is the script name (it is operating system |
| dependent whether this is a full pathname or not). |
| If the command was executed using the \programopt{-c} command line |
| option to the interpreter, \code{argv[0]} is set to the string |
| \code{'-c'}. |
| If no script name was passed to the Python interpreter, |
| \code{argv} has zero length. |
| \end{datadesc} |
| |
| \begin{datadesc}{byteorder} |
| An indicator of the native byte order. This will have the value |
| \code{'big'} on big-endian (most-signigicant byte first) platforms, |
| and \code{'little'} on little-endian (least-significant byte first) |
| platforms. |
| \versionadded{2.0} |
| \end{datadesc} |
| |
| \begin{datadesc}{builtin_module_names} |
| A tuple of strings giving the names of all modules that are compiled |
| into this Python interpreter. (This information is not available in |
| any other way --- \code{modules.keys()} only lists the imported |
| modules.) |
| \end{datadesc} |
| |
| \begin{datadesc}{copyright} |
| A string containing the copyright pertaining to the Python interpreter. |
| \end{datadesc} |
| |
| \begin{datadesc}{dllhandle} |
| Integer specifying the handle of the Python DLL. |
| Availability: Windows. |
| \end{datadesc} |
| |
| \begin{funcdesc}{exc_info}{} |
| This function returns a tuple of three values that give information |
| about the exception that is currently being handled. The information |
| returned is specific both to the current thread and to the current |
| stack frame. If the current stack frame is not handling an exception, |
| the information is taken from the calling stack frame, or its caller, |
| and so on until a stack frame is found that is handling an exception. |
| Here, ``handling an exception'' is defined as ``executing or having |
| executed an except clause.'' For any stack frame, only |
| information about the most recently handled exception is accessible. |
| |
| If no exception is being handled anywhere on the stack, a tuple |
| containing three \code{None} values is returned. Otherwise, the |
| values returned are |
| \code{(\var{type}, \var{value}, \var{traceback})}. |
| Their meaning is: \var{type} gets the exception type of the exception |
| being handled (a string or class object); \var{value} gets the |
| exception parameter (its \dfn{associated value} or the second argument |
| to \keyword{raise}, which is always a class instance if the exception |
| type is a class object); \var{traceback} gets a traceback object (see |
| the Reference Manual) which encapsulates the call stack at the point |
| where the exception originally occurred. |
| \obindex{traceback} |
| |
| \strong{Warning:} assigning the \var{traceback} return value to a |
| local variable in a function that is handling an exception will cause |
| a circular reference. This will prevent anything referenced by a local |
| variable in the same function or by the traceback from being garbage |
| collected. Since most functions don't need access to the traceback, |
| the best solution is to use something like |
| \code{type, value = sys.exc_info()[:2]} |
| to extract only the exception type and value. If you do need the |
| traceback, make sure to delete it after use (best done with a |
| \keyword{try} ... \keyword{finally} statement) or to call |
| \function{exc_info()} in a function that does not itself handle an |
| exception. |
| \end{funcdesc} |
| |
| \begin{datadesc}{exc_type} |
| \dataline{exc_value} |
| \dataline{exc_traceback} |
| \deprecated {1.5} |
| {Use \function{exc_info()} instead.} |
| Since they are global variables, they are not specific to the current |
| thread, so their use is not safe in a multi-threaded program. When no |
| exception is being handled, \code{exc_type} is set to \code{None} and |
| the other two are undefined. |
| \end{datadesc} |
| |
| \begin{datadesc}{exec_prefix} |
| A string giving the site-specific directory prefix where the |
| platform-dependent Python files are installed; by default, this is |
| also \code{'/usr/local'}. This can be set at build time with the |
| \longprogramopt{exec-prefix} argument to the |
| \program{configure} script. Specifically, all configuration files |
| (e.g. the \file{config.h} header file) are installed in the directory |
| \code{exec_prefix + '/lib/python\var{version}/config'}, and shared |
| library modules are installed in \code{exec_prefix + |
| '/lib/python\var{version}/lib-dynload'}, where \var{version} is equal |
| to \code{version[:3]}. |
| \end{datadesc} |
| |
| \begin{datadesc}{executable} |
| A string giving the name of the executable binary for the Python |
| interpreter, on systems where this makes sense. |
| \end{datadesc} |
| |
| \begin{funcdesc}{exit}{\optional{arg}} |
| Exit from Python. This is implemented by raising the |
| \exception{SystemExit} exception, so cleanup actions specified by |
| finally clauses of \keyword{try} statements are honored, and it is |
| possible to intercept the exit attempt at an outer level. The |
| optional argument \var{arg} can be an integer giving the exit status |
| (defaulting to zero), or another type of object. If it is an integer, |
| zero is considered ``successful termination'' and any nonzero value is |
| considered ``abnormal termination'' by shells and the like. Most |
| systems require it to be in the range 0-127, and produce undefined |
| results otherwise. Some systems have a convention for assigning |
| specific meanings to specific exit codes, but these are generally |
| underdeveloped; Unix programs generally use 2 for command line syntax |
| errors and 1 for all other kind of errors. If another type of object |
| is passed, \code{None} is equivalent to passing zero, and any other |
| object is printed to \code{sys.stderr} and results in an exit code of |
| 1. In particular, \code{sys.exit("some error message")} is a quick |
| way to exit a program when an error occurs. |
| \end{funcdesc} |
| |
| \begin{datadesc}{exitfunc} |
| This value is not actually defined by the module, but can be set by |
| the user (or by a program) to specify a clean-up action at program |
| exit. When set, it should be a parameterless function. This function |
| will be called when the interpreter exits. Only one function may be |
| installed in this way; to allow multiple functions which will be called |
| at termination, use the \refmodule{atexit} module. Note: the exit function |
| is not called when the program is killed by a signal, when a Python |
| fatal internal error is detected, or when \code{os._exit()} is called. |
| \end{datadesc} |
| |
| \begin{funcdesc}{getrefcount}{object} |
| Return the reference count of the \var{object}. The count returned is |
| generally one higher than you might expect, because it includes the |
| (temporary) reference as an argument to \function{getrefcount()}. |
| \end{funcdesc} |
| |
| \begin{datadesc}{hexversion} |
| The version number encoded as a single integer. This is guaranteed to |
| increase with each version, including proper support for |
| non-production releases. For example, to test that the Python |
| interpreter is at least version 1.5.2, use: |
| |
| \begin{verbatim} |
| if sys.hexversion >= 0x010502F0: |
| # use some advanced feature |
| ... |
| else: |
| # use an alternative implementation or warn the user |
| ... |
| \end{verbatim} |
| |
| This is called \samp{hexversion} since it only really looks meaningful |
| when viewed as the result of passing it to the built-in |
| \function{hex()} function. The \code{version_info} value may be used |
| for a more human-friendly encoding of the same information. |
| \versionadded{1.5.2} |
| \end{datadesc} |
| |
| \begin{datadesc}{last_type} |
| \dataline{last_value} |
| \dataline{last_traceback} |
| These three variables are not always defined; they are set when an |
| exception is not handled and the interpreter prints an error message |
| and a stack traceback. Their intended use is to allow an interactive |
| user to import a debugger module and engage in post-mortem debugging |
| without having to re-execute the command that caused the error. |
| (Typical use is \samp{import pdb; pdb.pm()} to enter the post-mortem |
| debugger; see the chapter ``The Python Debugger'' for more |
| information.) |
| \refstmodindex{pdb} |
| |
| The meaning of the variables is the same |
| as that of the return values from \function{exc_info()} above. |
| (Since there is only one interactive thread, thread-safety is not a |
| concern for these variables, unlike for \code{exc_type} etc.) |
| \end{datadesc} |
| |
| \begin{datadesc}{maxint} |
| The largest positive integer supported by Python's regular integer |
| type. This is at least 2**31-1. The largest negative integer is |
| \code{-maxint-1} -- the asymmetry results from the use of 2's |
| complement binary arithmetic. |
| \end{datadesc} |
| |
| \begin{datadesc}{modules} |
| This is a dictionary that maps module names to modules which have |
| already been loaded. This can be manipulated to force reloading of |
| modules and other tricks. Note that removing a module from this |
| dictionary is \emph{not} the same as calling |
| \function{reload()}\bifuncindex{reload} on the corresponding module |
| object. |
| \end{datadesc} |
| |
| \begin{datadesc}{path} |
| \indexiii{module}{search}{path} |
| A list of strings that specifies the search path for modules. |
| Initialized from the environment variable \envvar{PYTHONPATH}, or an |
| installation-dependent default. |
| |
| The first item of this list, \code{path[0]}, is the |
| directory containing the script that was used to invoke the Python |
| interpreter. If the script directory is not available (e.g. if the |
| interpreter is invoked interactively or if the script is read from |
| standard input), \code{path[0]} is the empty string, which directs |
| Python to search modules in the current directory first. Notice that |
| the script directory is inserted \emph{before} the entries inserted as |
| a result of \envvar{PYTHONPATH}. |
| \end{datadesc} |
| |
| \begin{datadesc}{platform} |
| This string contains a platform identifier, e.g. \code{'sunos5'} or |
| \code{'linux1'}. This can be used to append platform-specific |
| components to \code{path}, for instance. |
| \end{datadesc} |
| |
| \begin{datadesc}{prefix} |
| A string giving the site-specific directory prefix where the platform |
| independent Python files are installed; by default, this is the string |
| \code{'/usr/local'}. This can be set at build time with the |
| \longprogramopt{prefix} argument to the |
| \program{configure} script. The main collection of Python library |
| modules is installed in the directory \code{prefix + |
| '/lib/python\var{version}'} while the platform independent header |
| files (all except \file{config.h}) are stored in \code{prefix + |
| '/include/python\var{version}'}, where \var{version} is equal to |
| \code{version[:3]}. |
| \end{datadesc} |
| |
| \begin{datadesc}{ps1} |
| \dataline{ps2} |
| \index{interpreter prompts} |
| \index{prompts, interpreter} |
| Strings specifying the primary and secondary prompt of the |
| interpreter. These are only defined if the interpreter is in |
| interactive mode. Their initial values in this case are |
| \code{'>>> '} and \code{'... '}. If a non-string object is assigned |
| to either variable, its \function{str()} is re-evaluated each time |
| the interpreter prepares to read a new interactive command; this can |
| be used to implement a dynamic prompt. |
| \end{datadesc} |
| |
| \begin{funcdesc}{setcheckinterval}{interval} |
| Set the interpreter's ``check interval''. This integer value |
| determines how often the interpreter checks for periodic things such |
| as thread switches and signal handlers. The default is \code{10}, meaning |
| the check is performed every 10 Python virtual instructions. Setting |
| it to a larger value may increase performance for programs using |
| threads. Setting it to a value \code{<=} 0 checks every virtual instruction, |
| maximizing responsiveness as well as overhead. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{setprofile}{profilefunc} |
| Set the system's profile function, which allows you to implement a |
| Python source code profiler in Python. See the chapter on the |
| Python Profiler. The system's profile function |
| is called similarly to the system's trace function (see |
| \function{settrace()}), but it isn't called for each executed line of |
| code (only on call and return and when an exception occurs). Also, |
| its return value is not used, so it can just return \code{None}. |
| \end{funcdesc} |
| \index{profile function} |
| \index{profiler} |
| |
| \begin{funcdesc}{settrace}{tracefunc} |
| Set the system's trace function, which allows you to implement a |
| Python source code debugger in Python. See section ``How It Works'' |
| in the chapter on the Python Debugger. |
| \end{funcdesc} |
| \index{trace function} |
| \index{debugger} |
| |
| \begin{datadesc}{stdin} |
| \dataline{stdout} |
| \dataline{stderr} |
| File objects corresponding to the interpreter's standard input, |
| output and error streams. \code{stdin} is used for all |
| interpreter input except for scripts but including calls to |
| \function{input()}\bifuncindex{input} and |
| \function{raw_input()}\bifuncindex{raw_input}. \code{stdout} is used |
| for the output of \keyword{print} and expression statements and for the |
| prompts of \function{input()} and \function{raw_input()}. The interpreter's |
| own prompts and (almost all of) its error messages go to |
| \code{stderr}. \code{stdout} and \code{stderr} needn't |
| be built-in file objects: any object is acceptable as long as it has |
| a \method{write()} method that takes a string argument. (Changing these |
| objects doesn't affect the standard I/O streams of processes |
| executed by \function{os.popen()}, \function{os.system()} or the |
| \function{exec*()} family of functions in the \refmodule{os} module.) |
| \refstmodindex{os} |
| \end{datadesc} |
| |
| \begin{datadesc}{__stdin__} |
| \dataline{__stdout__} |
| \dataline{__stderr__} |
| These objects contain the original values of \code{stdin}, |
| \code{stderr} and \code{stdout} at the start of the program. They are |
| used during finalization, and could be useful to restore the actual |
| files to known working file objects in case they have been overwritten |
| with a broken object. |
| \end{datadesc} |
| |
| \begin{datadesc}{tracebacklimit} |
| When this variable is set to an integer value, it determines the |
| maximum number of levels of traceback information printed when an |
| unhandled exception occurs. The default is \code{1000}. When set to |
| 0 or less, all traceback information is suppressed and only the |
| exception type and value are printed. |
| \end{datadesc} |
| |
| \begin{datadesc}{version} |
| A string containing the version number of the Python interpreter plus |
| additional information on the build number and compiler used. It has |
| a value of the form \code{'\var{version} (\#\var{build_number}, |
| \var{build_date}, \var{build_time}) [\var{compiler}]'}. The first |
| three characters are used to identify the version in the installation |
| directories (where appropriate on each platform). An example: |
| |
| \begin{verbatim} |
| >>> import sys |
| >>> sys.version |
| '1.5.2 (#0 Apr 13 1999, 10:51:12) [MSC 32 bit (Intel)]' |
| \end{verbatim} |
| \end{datadesc} |
| |
| \begin{datadesc}{version_info} |
| A tuple containing the five components of the version number: |
| \var{major}, \var{minor}, \var{micro}, \var{releaselevel}, and |
| \var{serial}. All values except \var{releaselevel} are integers; the |
| release level is \code{'alpha'}, \code{'beta'}, |
| \code{'candidate'}, or \code{'final'}. The \code{version_info} value |
| corresponding to the Python version 2.0 is |
| \code{(2, 0, 0, 'final', 0)}. |
| \versionadded{2.0} |
| \end{datadesc} |
| |
| \begin{datadesc}{winver} |
| The version number used to form registry keys on Windows platforms. |
| This is stored as string resource 1000 in the Python DLL. The value |
| is normally the first three characters of \constant{version}. It is |
| provided in the \module{sys} module for informational purposes; |
| modifying this value has no effect on the registry keys used by |
| Python. |
| Availability: Windows. |
| \end{datadesc} |