\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 theinterpreter 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-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}   If \function{exc_clear()} is called, this function will return three  \code{None} values until either another exception is raised in the  current thread or the execution stack returns to a frame where  another exception is being handled.   \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{funcdesc}{exc_clear}{}  This function clears all information relating to the current or last  exception that occurred in the current thread.  After calling this  function, \function{exc_info()} will return three \code{None} values until  another exception is raised in the current thread or the execution stack  returns to a frame where another exception is being handled.   This function is only needed in only a few obscure situations.  These  include logging and error handling systems that report information on the  last or current exception.  This function can also be used to try to free  resources and trigger object finalization, though no guarantee is made as  to what objects will be freed, if any.\versionadded{2.3}\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{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{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.}  \deprecated{2.4}{Use \refmodule{atexit} instead.}\end{datadesc} \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{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.  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}, 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}

Lines 1–500 of 617. Load more