29.1.`sys` — 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 isalways available.

sys.abiflags¶: On POSIX systems where Python was built with the standardconfigurescript, this contains the ABI flags as specified byPEP 3149.
New in version 3.2.

sys.argv¶

The list of command line arguments passed to a Python script.argv[0] is thescript name (it is operating system dependent whether this is a full pathname ornot). If the command was executed using the-c command line option tothe interpreter,argv[0] is set to the string'-c'. If no script namewas passed to the Python interpreter,argv[0] is the empty string.

To loop over the standard input, or the list of files given on thecommand line, see thefileinput module.

sys.base_exec_prefix¶: Set during Python startup, beforesite.py is run, to the same value asexec_prefix. If not running in avirtual environment, the values will stay the same; ifsite.py finds that a virtual environment is in use, the values ofprefix andexec_prefix will be changed to point to thevirtual environment, whereasbase_prefix andbase_exec_prefix will remain pointing to the base Pythoninstallation (the one which the virtual environment was created from).
New in version 3.3.

sys.base_prefix¶: Set during Python startup, beforesite.py is run, to the same value asprefix. If not running in avirtual environment, the valueswill stay the same; ifsite.py finds that a virtual environment is inuse, the values ofprefix andexec_prefix will be changed topoint to the virtual environment, whereasbase_prefix andbase_exec_prefix will remain pointing to the base Pythoninstallation (the one which the virtual environment was created from).
New in version 3.3.

sys.byteorder¶: An indicator of the native byte order. This will have the value'big' onbig-endian (most-significant byte first) platforms, and'little' onlittle-endian (least-significant byte first) platforms.

sys.builtin_module_names¶: A tuple of strings giving the names of all modules that are compiled into thisPython interpreter. (This information is not available in any other way —modules.keys() only lists the imported modules.)

sys.call_tracing(func,args)¶: Callfunc(*args), while tracing is enabled. The tracing state is saved,and restored afterwards. This is intended to be called from a debugger froma checkpoint, to recursively debug some other code.

sys.copyright¶: A string containing the copyright pertaining to the Python interpreter.

sys._clear_type_cache()¶

Clear the internal type cache. The type cache is used to speed up attributeand method lookups. Use the functiononly to drop unnecessary referencesduring reference leak debugging.

This function should be used for internal and specialized purposes only.

sys._current_frames()¶

Return a dictionary mapping each thread’s identifier to the topmost stack framecurrently active in that thread at the time the function is called. Note thatfunctions in thetraceback module can build the call stack given such aframe.

This is most useful for debugging deadlock: this function does not require thedeadlocked threads’ cooperation, and such threads’ call stacks are frozen for aslong as they remain deadlocked. The frame returned for a non-deadlocked threadmay bear no relationship to that thread’s current activity by the time callingcode examines the frame.

This function should be used for internal and specialized purposes only.

sys._debugmallocstats()¶

Print low-level information to stderr about the state of CPython’s memoryallocator.

If Python is configured –with-pydebug, it also performs some expensiveinternal consistency checks.

New in version 3.3.

CPython implementation detail: This function is specific to CPython. The exact output format is notdefined here, and may change.

sys.dllhandle¶: Integer specifying the handle of the Python DLL. Availability: Windows.

sys.displayhook(value)¶

Ifvalue is notNone, this function printsrepr(value) tosys.stdout, and savesvalue inbuiltins._. Ifrepr(value) isnot encodable tosys.stdout.encoding withsys.stdout.errors errorhandler (which is probably'strict'), encode it tosys.stdout.encoding with'backslashreplace' error handler.

sys.displayhook is called on the result of evaluating anexpressionentered in an interactive Python session. The display of these values can becustomized by assigning another one-argument function tosys.displayhook.

Pseudo-code:

defdisplayhook(value):ifvalueisNone:return# Set '_' to None to avoid recursionbuiltins._=Nonetext=repr(value)try:sys.stdout.write(text)exceptUnicodeEncodeError:bytes=text.encode(sys.stdout.encoding,'backslashreplace')ifhasattr(sys.stdout,'buffer'):sys.stdout.buffer.write(bytes)else:text=bytes.decode(sys.stdout.encoding,'strict')sys.stdout.write(text)sys.stdout.write("\n")builtins._=value

Changed in version 3.2:Use'backslashreplace' error handler onUnicodeEncodeError.

sys.dont_write_bytecode¶: If this is true, Python won’t try to write.pyc files on theimport of source modules. This value is initially set toTrue orFalse depending on the-B command line option and thePYTHONDONTWRITEBYTECODE environment variable, but you can set ityourself to control bytecode file generation.

sys.excepthook(type,value,traceback)¶

This function prints out a given traceback and exception tosys.stderr.

When an exception is raised and uncaught, the interpreter callssys.excepthook with three arguments, the exception class, exceptioninstance, and a traceback object. In an interactive session this happens justbefore control is returned to the prompt; in a Python program this happens justbefore the program exits. The handling of such top-level exceptions can becustomized by assigning another three-argument function tosys.excepthook.

sys.__displayhook__¶
sys.__excepthook__¶: These objects contain the original values ofdisplayhook andexcepthookat the start of the program. They are saved so thatdisplayhook andexcepthook can be restored in case they happen to get replaced with brokenobjects.

sys.exc_info()¶

This function returns a tuple of three values that give information about theexception that is currently being handled. The information returned is specificboth to the current thread and to the current stack frame. If the current stackframe is not handling an exception, the information is taken from the callingstack frame, or its caller, and so on until a stack frame is found that ishandling an exception. Here, “handling an exception” is defined as “executingan except clause.” For any stack frame, only information about the exceptionbeing currently handled is accessible.

If no exception is being handled anywhere on the stack, a tuple containingthreeNone values is returned. Otherwise, the values returned are(type,value,traceback). Their meaning is:type gets the type of theexception being handled (a subclass ofBaseException);value getsthe exception instance (an instance of the exception type);traceback getsa traceback object (see the Reference Manual) which encapsulates the callstack at the point where the exception originally occurred.

sys.exec_prefix¶: A string giving the site-specific directory prefix where the platform-dependentPython files are installed; by default, this is also'/usr/local'. This canbe set at build time with the--exec-prefix argument to theconfigure script. Specifically, all configuration files (e.g. thepyconfig.h header file) are installed in the directoryexec_prefix/lib/pythonX.Y/config, and shared library modules areinstalled inexec_prefix/lib/pythonX.Y/lib-dynload, whereX.Yis the version number of Python, for example3.2.
Note
If avirtual environment is in effect, thisvalue will be changed insite.py to point to the virtual environment.The value for the Python installation will still be available, viabase_exec_prefix.

sys.executable¶: A string giving the absolute path of the executable binary for the Pythoninterpreter, on systems where this makes sense. If Python is unable to retrievethe real path to its executable,sys.executable will be an empty stringorNone.

sys.exit([arg])¶

Exit from Python. This is implemented by raising theSystemExitexception, so cleanup actions specified by finally clauses oftrystatements are honored, and it is possible to intercept the exit attempt atan outer level.

The optional argumentarg can be an integer giving the exit status(defaulting to zero), or another type of object. If it is an integer, zerois considered “successful termination” and any nonzero value is considered“abnormal termination” by shells and the like. Most systems require it to bein the range 0–127, and produce undefined results otherwise. Some systemshave a convention for assigning specific meanings to specific exit codes, butthese are generally underdeveloped; Unix programs generally use 2 for commandline syntax errors and 1 for all other kind of errors. If another type ofobject is passed,None is equivalent to passing zero, and any otherobject is printed tostderr and results in an exit code of 1. Inparticular,sys.exit("someerrormessage") is a quick way to exit aprogram when an error occurs.

Sinceexit() ultimately “only” raises an exception, it will only exitthe process when called from the main thread, and the exception is notintercepted.

sys.flags¶

Thestruct sequenceflags exposes the status of command lineflags. The attributes are read only.

attribute	flag
`debug`	`-d`
`inspect`	`-i`
`interactive`	`-i`
`optimize`	`-O` or`-OO`
`dont_write_bytecode`	`-B`
`no_user_site`	`-s`
`no_site`	`-S`
`ignore_environment`	`-E`
`verbose`	`-v`
`bytes_warning`	`-b`
`quiet`	`-q`
`hash_randomization`	`-R`

Changed in version 3.2:Addedquiet attribute for the new-q flag.

New in version 3.2.3:Thehash_randomization attribute.

Changed in version 3.3:Removed obsoletedivision_warning attribute.

sys.float_info¶

Astruct sequence holding information about the float type. Itcontains low level information about the precision and internalrepresentation. The values correspond to the various floating-pointconstants defined in the standard header filefloat.h for the ‘C’programming language; see section 5.2.4.2.2 of the 1999 ISO/IEC C standard[C99], ‘Characteristics of floating types’, for details.

attribute	float.h macro	explanation
`epsilon`	DBL_EPSILON	difference between 1 and the least value greaterthan 1 that is representable as a float
`dig`	DBL_DIG	maximum number of decimal digits that can befaithfully represented in a float; see below
`mant_dig`	DBL_MANT_DIG	float precision: the number of base-`radix`digits in the significand of a float
`max`	DBL_MAX	maximum representable finite float
`max_exp`	DBL_MAX_EXP	maximum integer e such that`radix**(e-1)` isa representable finite float
`max_10_exp`	DBL_MAX_10_EXP	maximum integer e such that`10**e` is in therange of representable finite floats
`min`	DBL_MIN	minimum positive normalized float
`min_exp`	DBL_MIN_EXP	minimum integer e such that`radix**(e-1)` isa normalized float
`min_10_exp`	DBL_MIN_10_EXP	minimum integer e such that`10**e` is anormalized float
`radix`	FLT_RADIX	radix of exponent representation
`rounds`	FLT_ROUNDS	integer constant representing the rounding modeused for arithmetic operations. This reflectsthe value of the system FLT_ROUNDS macro atinterpreter startup time. See section 5.2.4.2.2of the C99 standard for an explanation of thepossible values and their meanings.

The attributesys.float_info.dig needs further explanation. Ifs is any string representing a decimal number with at mostsys.float_info.dig significant digits, then convertings to afloat and back again will recover a string representing the same decimalvalue:

>>>importsys>>>sys.float_info.dig15>>>s='3.14159265358979'# decimal string with 15 significant digits>>>format(float(s),'.15g')# convert to float and back -> same value'3.14159265358979'

But for strings with more thansys.float_info.dig significant digits,this isn’t always true:

>>>s='9876543211234567'# 16 significant digits is too many!>>>format(float(s),'.16g')# conversion changes value'9876543211234568'

sys.float_repr_style¶: A string indicating how therepr() function behaves forfloats. If the string has value'short' then for a finitefloatx,repr(x) aims to produce a short string with theproperty thatfloat(repr(x))==x. This is the usual behaviourin Python 3.1 and later. Otherwise,float_repr_style has value'legacy' andrepr(x) behaves in the same way as it did inversions of Python prior to 3.1.
New in version 3.1.

sys.getallocatedblocks()¶

Return the number of memory blocks currently allocated by the interpreter,regardless of their size. This function is mainly useful for trackingand debugging memory leaks. Because of the interpreter’s internalcaches, the result can vary from call to call; you may have to call_clear_type_cache() andgc.collect() to get morepredictable results.

If a Python build or implementation cannot reasonably compute thisinformation,getallocatedblocks() is allowed to return 0 instead.

New in version 3.4.

sys.getcheckinterval()¶: Return the interpreter’s “check interval”; seesetcheckinterval().
Deprecated since version 3.2:Usegetswitchinterval() instead.

sys.getdefaultencoding()¶: Return the name of the current default string encoding used by the Unicodeimplementation.

sys.getdlopenflags()¶: Return the current value of the flags that are used fordlopen() calls. Symbolic names for the flag values can befound in theos module (RTLD_xxx constants, e.g.os.RTLD_LAZY). Availability: Unix.

sys.getfilesystemencoding()¶

Return the name of the encoding used to convert Unicode filenames intosystem file names. The result value depends on the operating system:

On Mac OS X, the encoding is'utf-8'.
On Unix, the encoding is the user’s preference according to the result ofnl_langinfo(CODESET).
On Windows NT+, file names are Unicode natively, so no conversion isperformed.getfilesystemencoding() still returns'mbcs', asthis is the encoding that applications should use when they explicitlywant to convert Unicode strings to byte strings that are equivalent whenused as file names.
On Windows 9x, the encoding is'mbcs'.

Changed in version 3.2:getfilesystemencoding() result cannot beNone anymore.

sys.getrefcount(object)¶: Return the reference count of theobject. The count returned is generally onehigher than you might expect, because it includes the (temporary) reference asan argument togetrefcount().

sys.getrecursionlimit()¶: Return the current value of the recursion limit, the maximum depth of the Pythoninterpreter stack. This limit prevents infinite recursion from causing anoverflow of the C stack and crashing Python. It can be set bysetrecursionlimit().

sys.getsizeof(object[,default])¶

Return the size of an object in bytes. The object can be any type ofobject. All built-in objects will return correct results, but thisdoes not have to hold true for third-party extensions as it is implementationspecific.

Only the memory consumption directly attributed to the object isaccounted for, not the memory consumption of objects it refers to.

If given,default will be returned if the object does not provide means toretrieve the size. Otherwise aTypeError will be raised.

getsizeof() calls the object’s__sizeof__ method and adds anadditional garbage collector overhead if the object is managed by the garbagecollector.

Seerecursive sizeof recipefor an example of usinggetsizeof() recursively to find the size ofcontainers and all their contents.

sys.getswitchinterval()¶: Return the interpreter’s “thread switch interval”; seesetswitchinterval().
New in version 3.2.

sys._getframe([depth])¶: Return a frame object from the call stack. If optional integerdepth isgiven, return the frame object that many calls below the top of the stack. Ifthat is deeper than the call stack,ValueError is raised. The defaultfordepth is zero, returning the frame at the top of the call stack.
CPython implementation detail: This function should be used for internal and specialized purposes only.It is not guaranteed to exist in all implementations of Python.

sys.getprofile()¶: Get the profiler function as set bysetprofile().

sys.gettrace()¶: Get the trace function as set bysettrace().
CPython implementation detail: Thegettrace() function is intended only for implementing debuggers,profilers, coverage tools and the like. Its behavior is part of theimplementation platform, rather than part of the language definition, andthus may not be available in all Python implementations.

sys.getwindowsversion()¶

Return a named tuple describing the Windows versioncurrently running. The named elements aremajor,minor,build,platform,service_pack,service_pack_minor,service_pack_major,suite_mask, andproduct_type.service_pack contains a string while all other values areintegers. The components can also be accessed by name, sosys.getwindowsversion()[0] is equivalent tosys.getwindowsversion().major. For compatibility with priorversions, only the first 5 elements are retrievable by indexing.

platform may be one of the following values:

Constant	Platform
`0(VER_PLATFORM_WIN32s)`	Win32s on Windows 3.1
`1(VER_PLATFORM_WIN32_WINDOWS)`	Windows 95/98/ME
`2(VER_PLATFORM_WIN32_NT)`	Windows NT/2000/XP/x64
`3(VER_PLATFORM_WIN32_CE)`	Windows CE

product_type may be one of the following values:

Constant	Meaning
`1(VER_NT_WORKSTATION)`	The system is a workstation.
`2(VER_NT_DOMAIN_CONTROLLER)`	The system is a domaincontroller.
`3(VER_NT_SERVER)`	The system is a server, but nota domain controller.

This function wraps the Win32GetVersionEx() function; see theMicrosoft documentation onOSVERSIONINFOEX() for more informationabout these fields.

Availability: Windows.

Changed in version 3.2:Changed to a named tuple and addedservice_pack_minor,service_pack_major,suite_mask, andproduct_type.

sys.get_coroutine_wrapper()¶: ReturnsNone, or a wrapper set byset_coroutine_wrapper().
New in version 3.5:SeePEP 492 for more details.
Note
This function has been added on a provisional basis (seePEP 411for details.) Use it only for debugging purposes.

sys.hash_info¶

Astruct sequence giving parameters of the numeric hashimplementation. For more details about hashing of numeric types, seeHashing of numeric types.

attribute	explanation
`width`	width in bits used for hash values
`modulus`	prime modulus P used for numeric hash scheme
`inf`	hash value returned for a positive infinity
`nan`	hash value returned for a nan
`imag`	multiplier used for the imaginary part of acomplex number
`algorithm`	name of the algorithm for hashing of str, bytes,and memoryview
`hash_bits`	internal output size of the hash algorithm
`seed_bits`	size of the seed key of the hash algorithm

New in version 3.2.

Changed in version 3.4:Addedalgorithm,hash_bits andseed_bits

sys.hexversion¶

The version number encoded as a single integer. This is guaranteed to increasewith each version, including proper support for non-production releases. Forexample, to test that the Python interpreter is at least version 1.5.2, use:

ifsys.hexversion>=0x010502F0:# use some advanced feature...else:# use an alternative implementation or warn the user...

This is calledhexversion since it only really looks meaningful when viewedas the result of passing it to the built-inhex() function. Thestruct sequence sys.version_info may be used for a morehuman-friendly encoding of the same information.

More details ofhexversion can be found atAPI and ABI Versioning.

sys.implementation¶

An object containing information about the implementation of thecurrently running Python interpreter. The following attributes arerequired to exist in all Python implementations.

name is the implementation’s identifier, e.g.'cpython'. The actualstring is defined by the Python implementation, but it is guaranteed to belower case.

version is a named tuple, in the same format assys.version_info. It represents the version of the Pythonimplementation. This has a distinct meaning from the specificversion of the Pythonlanguage to which the currently runninginterpreter conforms, whichsys.version_info represents. Forexample, for PyPy 1.8sys.implementation.version might besys.version_info(1,8,0,'final',0), whereassys.version_infowould besys.version_info(2,7,2,'final',0). For CPython theyare the same value, since it is the reference implementation.

hexversion is the implementation version in hexadecimal format, likesys.hexversion.

cache_tag is the tag used by the import machinery in the filenames ofcached modules. By convention, it would be a composite of theimplementation’s name and version, like'cpython-33'. However, aPython implementation may use some other value if appropriate. Ifcache_tag is set toNone, it indicates that module caching shouldbe disabled.

sys.implementation may contain additional attributes specific tothe Python implementation. These non-standard attributes must start withan underscore, and are not described here. Regardless of its contents,sys.implementation will not change during a run of the interpreter,nor between implementation versions. (It may change between Pythonlanguage versions, however.) SeePEP 421 for more information.

New in version 3.3.

sys.int_info¶

Astruct sequence that holds information about Python’s internalrepresentation of integers. The attributes are read only.

Attribute	Explanation
`bits_per_digit`	number of bits held in each digit. Pythonintegers are stored internally in base`2**int_info.bits_per_digit`
`sizeof_digit`	size in bytes of the C type used torepresent a digit

New in version 3.1.

sys.__interactivehook__¶: When this attribute exists, its value is automatically called (with noarguments) when the interpreter is launched ininteractive mode. This is done after thePYTHONSTARTUP file isread, so that you can set this hook there. Thesite modulesets this.
New in version 3.4.

sys.intern(string)¶

Enterstring in the table of “interned” strings and return the interned string– which isstring itself or a copy. Interning strings is useful to gain alittle performance on dictionary lookup – if the keys in a dictionary areinterned, and the lookup key is interned, the key comparisons (after hashing)can be done by a pointer compare instead of a string compare. Normally, thenames used in Python programs are automatically interned, and the dictionariesused to hold module, class or instance attributes have interned keys.

Interned strings are not immortal; you must keep a reference to the returnvalue ofintern() around to benefit from it.

sys.is_finalizing()¶: ReturnTrue if the Python interpreter isshutting down,False otherwise.
New in version 3.5.

sys.last_type¶

sys.last_value¶

sys.last_traceback¶

These three variables are not always defined; they are set when an exception isnot 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 moduleand engage in post-mortem debugging without having to re-execute the commandthat caused the error. (Typical use isimportpdb;pdb.pm() to enter thepost-mortem debugger; seepdb module formore information.)

The meaning of the variables is the same as that of the return values fromexc_info() above.

sys.maxsize¶: An integer giving the maximum value a variable of typePy_ssize_t cantake. It’s usually2**31-1 on a 32-bit platform and2**63-1 on a64-bit platform.

sys.maxunicode¶: An integer giving the value of the largest Unicode code point,i.e.1114111 (0x10FFFF in hexadecimal).
Changed in version 3.3:BeforePEP 393,sys.maxunicode used to be either0xFFFFor0x10FFFF, depending on the configuration option that specifiedwhether Unicode characters were stored as UCS-2 or UCS-4.

sys.meta_path¶

A list ofmeta path finder objects that have theirfind_spec() methods called to see if oneof the objects can find the module to be imported. Thefind_spec() method is called with atleast the absolute name of the module being imported. If the module to beimported is contained in a package, then the parent package’s__path__attribute is passed in as a second argument. The method returns amodule spec, orNone if the module cannot be found.

System	`platform` value
Linux	`'linux'`
Windows	`'win32'`
Windows/Cygwin	`'cygwin'`
Mac OS X	`'darwin'`

Movatterモバイル変換

Navigation

29.1.`sys` — System-specific parameters and functions¶

Previous topic

Next topic

This Page

Navigation

Movatterモバイル変換

29.1.sys — System-specific parameters and functions¶

29.1.`sys` — System-specific parameters and functions¶