diff options
Diffstat (limited to 'Doc/lib/libsys.tex')
| -rw-r--r-- | Doc/lib/libsys.tex | 582 |
1 files changed, 0 insertions, 582 deletions
diff --git a/Doc/lib/libsys.tex b/Doc/lib/libsys.tex deleted file mode 100644 index 4ab3247..0000000 --- a/Doc/lib/libsys.tex +++ /dev/null @@ -1,582 +0,0 @@ -\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[0]} is - the empty string. -\end{datadesc} - -\begin{datadesc}{byteorder} - An indicator of the native byte order. This will have the value - \code{'big'} on big-endian (most-significant byte first) platforms, - and \code{'little'} on little-endian (least-significant byte first) - platforms. - \versionadded{2.0} -\end{datadesc} - -\begin{datadesc}{subversion} - A triple (repo, branch, version) representing the Subversion - information of the Python interpreter. - \var{repo} is the name of the repository, \code{'CPython'}. - \var{branch} is a string of one of the forms \code{'trunk'}, - \code{'branches/name'} or \code{'tags/name'}. - \var{version} is the output of \code{svnversion}, if the - interpreter was built from a Subversion checkout; it contains - the revision number (range) and possibly a trailing 'M' if - there were local modifications. If the tree was exported - (or svnversion was not available), it is the revision of - \code{Include/patchlevel.h} if the branch is a tag. Otherwise, - it is \code{None}. - \versionadded{2.5} -\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{funcdesc}{_current_frames}{} - Return a dictionary mapping each thread's identifier to the topmost stack - frame currently active in that thread at the time the function is called. - Note that functions in the \refmodule{traceback} module can build the - call stack given such a frame. - - This is most useful for debugging deadlock: this function does not - require the deadlocked threads' cooperation, and such threads' call stacks - are frozen for as long as they remain deadlocked. The frame returned - for a non-deadlocked thread may bear no relationship to that thread's - current activity by the time calling code examines the frame. - - This function should be used for internal and specialized purposes - only. - \versionadded{2.5} -\end{funcdesc} - -\begin{datadesc}{dllhandle} - Integer specifying the handle of the Python DLL. - Availability: Windows. -\end{datadesc} - -\begin{funcdesc}{displayhook}{\var{value}} - If \var{value} is not \code{None}, this function prints it to - \code{sys.stdout}, and saves it in \code{__builtin__._}. - - \code{sys.displayhook} is called on the result of evaluating an - expression entered in an interactive Python session. The display of - these values can be customized by assigning another one-argument - function to \code{sys.displayhook}. -\end{funcdesc} - -\begin{funcdesc}{excepthook}{\var{type}, \var{value}, \var{traceback}} - This function prints out a given traceback and exception to - \code{sys.stderr}. - - When an exception is raised and uncaught, the interpreter calls - \code{sys.excepthook} with three arguments, the exception class, - exception instance, and a traceback object. In an interactive - session this happens just before control is returned to the prompt; - in a Python program this happens just before the program exits. The - handling of such top-level exceptions can be customized by assigning - another three-argument function to \code{sys.excepthook}. -\end{funcdesc} - -\begin{datadesc}{__displayhook__} -\dataline{__excepthook__} - These objects contain the original values of \code{displayhook} and - \code{excepthook} at the start of the program. They are saved so - that \code{displayhook} and \code{excepthook} can be restored in - case they happen to get replaced with broken objects. -\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 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} - - \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{exctype, 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.} \note{Beginning - with Python 2.2, such cycles are automatically reclaimed when garbage - collection is enabled and they become unreachable, but it remains more - efficient to avoid creating cycles.} -\end{funcdesc} - -\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{pyconfig.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{funcdesc}{getcheckinterval}{} - Return the interpreter's ``check interval''; - see \function{setcheckinterval()}. - \versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{getdefaultencoding}{} - Return the name of the current default string encoding used by the - Unicode implementation. - \versionadded{2.0} -\end{funcdesc} - -\begin{funcdesc}{getdlopenflags}{} - Return the current value of the flags that are used for - \cfunction{dlopen()} calls. The flag constants are defined in the - \refmodule{dl} and \module{DLFCN} modules. - Availability: \UNIX. - \versionadded{2.2} -\end{funcdesc} - -\begin{funcdesc}{getfilesystemencoding}{} - Return the name of the encoding used to convert Unicode filenames - into system file names, or \code{None} if the system default encoding - is used. The result value depends on the operating system: -\begin{itemize} -\item On Windows 9x, the encoding is ``mbcs''. -\item On Mac OS X, the encoding is ``utf-8''. -\item On \UNIX, the encoding is the user's preference - according to the result of nl_langinfo(CODESET), or \constant{None} - if the \code{nl_langinfo(CODESET)} failed. -\item On Windows NT+, file names are Unicode natively, so no conversion - is performed. \function{getfilesystemencoding()} still returns - \code{'mbcs'}, as this is the encoding that applications should use - when they explicitly want to convert Unicode strings to byte strings - that are equivalent when used as file names. -\end{itemize} - \versionadded{2.3} -\end{funcdesc} - -\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{funcdesc}{getrecursionlimit}{} - Return the current value of the recursion limit, the maximum depth - of the Python interpreter stack. This limit prevents infinite - recursion from causing an overflow of the C stack and crashing - Python. It can be set by \function{setrecursionlimit()}. -\end{funcdesc} - -\begin{funcdesc}{_getframe}{\optional{depth}} - Return a frame object from the call stack. If optional integer - \var{depth} is given, return the frame object that many calls below - the top of the stack. If that is deeper than the call stack, - \exception{ValueError} is raised. The default for \var{depth} is - zero, returning the frame at the top of the call stack. - - This function should be used for internal and specialized purposes - only. -\end{funcdesc} - -\begin{funcdesc}{getwindowsversion}{} - Return a tuple containing five components, describing the Windows - version currently running. The elements are \var{major}, \var{minor}, - \var{build}, \var{platform}, and \var{text}. \var{text} contains - a string while all other values are integers. - - \var{platform} may be one of the following values: - - \begin{tableii}{l|l}{constant}{Constant}{Platform} - \lineii{0 (VER_PLATFORM_WIN32s)} {Win32s on Windows 3.1} - \lineii{1 (VER_PLATFORM_WIN32_WINDOWS)}{Windows 95/98/ME} - \lineii{2 (VER_PLATFORM_WIN32_NT)} {Windows NT/2000/XP} - \lineii{3 (VER_PLATFORM_WIN32_CE)} {Windows CE} - \end{tableii} - - This function wraps the Win32 \cfunction{GetVersionEx()} function; - see the Microsoft documentation for more information about these - fields. - - Availability: Windows. - \versionadded{2.3} -\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{funcdesc}{intern}{string} - Enter \var{string} in the table of ``interned'' strings and return - the interned string -- which is \var{string} itself or a copy. - Interning strings is useful to gain a little performance on - dictionary lookup -- if the keys in a dictionary are interned, and - the lookup key is interned, the key comparisons (after hashing) can - be done by a pointer compare instead of a string compare. Normally, - the names used in Python programs are automatically interned, and - the dictionaries used to hold module, class or instance attributes - have interned keys. \versionchanged[Interned strings are not - immortal (like they used to be in Python 2.2 and before); - you must keep a reference to the return value of \function{intern()} - around to benefit from it]{2.3} -\end{funcdesc} - -\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 chapter~\ref{debugger}, ``The - Python Debugger,'' for more information.) - - 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}{maxunicode} - An integer giving the largest supported code point for a Unicode - character. The value of this depends on the configuration option - that specifies whether Unicode characters are stored as UCS-2 or - UCS-4. -\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. -\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}, plus an - installation-dependent default. - - As initialized upon program startup, - 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}. - - A program is free to modify this list for its own purposes. - - \versionchanged[Unicode strings are no longer ignored]{2.3} -\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{pyconfig.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{100}, - meaning the check is performed every 100 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}{setdefaultencoding}{name} - Set the current default string encoding used by the Unicode - implementation. If \var{name} does not match any available - encoding, \exception{LookupError} is raised. This function is only - intended to be used by the \refmodule{site} module implementation - and, where needed, by \module{sitecustomize}. Once used by the - \refmodule{site} module, it is removed from the \module{sys} - module's namespace. -% Note that \refmodule{site} is not imported if -% the \programopt{-S} option is passed to the interpreter, in which -% case this function will remain available. - \versionadded{2.0} -\end{funcdesc} - -\begin{funcdesc}{setdlopenflags}{n} - Set the flags used by the interpreter for \cfunction{dlopen()} - calls, such as when the interpreter loads extension modules. Among - other things, this will enable a lazy resolving of symbols when - importing a module, if called as \code{sys.setdlopenflags(0)}. To - share symbols across extension modules, call as - \code{sys.setdlopenflags(dl.RTLD_NOW | dl.RTLD_GLOBAL)}. Symbolic - names for the flag modules can be either found in the \refmodule{dl} - module, or in the \module{DLFCN} module. If \module{DLFCN} is not - available, it can be generated from \file{/usr/include/dlfcn.h} - using the \program{h2py} script. - Availability: \UNIX. - \versionadded{2.2} -\end{funcdesc} - -\begin{funcdesc}{setprofile}{profilefunc} - Set the system's profile function,\index{profile function} which - allows you to implement a Python source code profiler in - Python.\index{profiler} See chapter~\ref{profile} for more - information 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, but the return event is reported - even when an exception has been set). The function is - thread-specific, but there is no way for the profiler to know about - context switches between threads, so it does not make sense to use - this in the presence of multiple threads. - Also, its return value is not used, so it can simply return - \code{None}. -\end{funcdesc} - -\begin{funcdesc}{setrecursionlimit}{limit} - Set the maximum depth of the Python interpreter stack to - \var{limit}. This limit prevents infinite recursion from causing an - overflow of the C stack and crashing Python. - - The highest possible limit is platform-dependent. A user may need - to set the limit higher when she has a program that requires deep - recursion and a platform that supports a higher limit. This should - be done with care, because a too-high limit can lead to a crash. -\end{funcdesc} - -\begin{funcdesc}{settrace}{tracefunc} - Set the system's trace function,\index{trace function} which allows - you to implement a Python source code debugger in Python. See - section \ref{debugger-hooks}, ``How It Works,'' in the chapter on - the Python debugger.\index{debugger} The function is - thread-specific; for a debugger to support multiple threads, it must - be registered using \function{settrace()} for each thread being - debugged. \note{The \function{settrace()} function is intended only - for implementing debuggers, profilers, coverage tools and the like. - Its behavior is part of the implementation platform, rather than - part of the language definition, and thus may not be available in - all Python implementations.} -\end{funcdesc} - -\begin{funcdesc}{settscdump}{on_flag} - Activate dumping of VM measurements using the Pentium timestamp - counter, if \var{on_flag} is true. Deactivate these dumps if - \var{on_flag} is off. The function is available only if Python - was compiled with \longprogramopt{with-tsc}. To understand the - output of this dump, read \file{Python/ceval.c} in the Python - sources. - \versionadded{2.4} -\end{funcdesc} - -\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. \code{stdout} is - used for the output of \keyword{print} and expression statements. - 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.) -\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 \code{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}{api_version} - The C API version for this interpreter. Programmers may find this useful - when debugging version conflicts between Python and extension - modules. \versionadded{2.3} -\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}{warnoptions} - This is an implementation detail of the warnings framework; do not - modify this value. Refer to the \refmodule{warnings} module for - more information on the warnings framework. -\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} - - -\begin{seealso} - \seemodule{site} - {This describes how to use .pth files to extend \code{sys.path}.} -\end{seealso} |