Library sys

by Alex
Library sys

Like any other language, Python has a large set of additional tools called modules. You can use them to implement a task of any complexity. Some modules are installed with the interpreter from the official repository/website, others must be downloaded separately. The programmer can not only use ready-made libraries, but also write his own. Let us consider the sys library, which is part of the Python distribution.

What is the sys module

The sys module provides the programmer with a set of functions that provide information about how the Python interpreter interacts with the operating system. The sys module gives the following information:

  • What version of Python is running.
  • The path to the Python interpreter that executes the current script.
  • The command line parameters used when running the script.
  • The flags set by the interpreter.
  • Floating point value representation.
  • Lots of other things.

The sys module is often used with the os module. With sys you get the information you need about the operating system to avoid unexpected errors, and with os you interact with it (file handling, program execution, path handling, and so on).

How to connect a library

All libraries (modules) in Python 3 are connected using the “import library name” command. There are different connection options used under certain circumstances:

  • import sys – This method is used if your project can use the same variable or function names as in the library. With this connection, the call of functions or variables from the module is performed as follows: “sys.function_name”.
  • from sys import * – The method is used when the programmer is sure that there are no crossings of names. When calling methods or functions there is no need to prefix “sys.”, which reduces the amount of code. The asterisk can be replaced by the names of specific functions listed separated by commas. This allows you to import not the entire module, but only some parts of it.
  • import sys as s – With this entry, the name “sys” is replaced by “s”. The method is used to replace the long name of the module for a shorter and more convenient, it allows you to reduce the amount of code and avoid crossing names. But sys is short enough as it is.

Functions and constants of the sys module

The sys library allows the programmer to get information about the Python interpreter and the operating system, work with input and output, change module parameters, and handle errors that occur.

Information about system parameters

sys.dllhandle

An integer that defines the descriptor of the dynamically attached Python library. It works only in Windows operating system. The descriptor is a pointer to an area of memory. This address is where the Python DLL is located. Here’s an example of how to use it. Define the pointer and use it to find the path to the DLL. To do this we need another library, pywin32, which we will install with pip install pywin32. This library is installed with import win32api:

import sys
import win32api
print(sys.dllhandle)
print(win32api.GetModuleFileName(sys.dllhandle))

1407778816
C:Usersall-pythonAppDataLocalProgramsPythonPython36-32python36.dll

sys.exec_prefix

A string that shows in which directory Python is installed. (usually “/usr/local”).

If a virtual environment is used, the value of sys.exec_prefix will be changed to the virtual environment directory. In this case, you can find out the Python installation path with base_exec_prefix.
import sys
print(sys.exec_prefix)
print(sys.base_exec_prefix)

d:pythonexampleenv
C:Usersall-pythonAppDataLocalProgramsPythonPython38-32

sys.executable

A string showing the absolute path to the binary executable file of the Python interpreter. If for some reason the path to the interpreter cannot be determined, sys.executable will be an empty string or None. Here is an example of its output:

C:Usersall-pythonAppDataLocalProgramsPythonPython38-32python.exe

sys.getfilesystemencoding()

The function returns the system encoding, which is used to convert file names from Unicode to bytes. For best compatibility you should always use strings, although filenames as bytes are also supported. Different operating systems use different encodings:

  • In UTF-8 mode, the encoding on any platform is always “utf-8”.
  • Mac OS X uses “utf-8” encoding.
  • Windows uses “utf-8” or “mbcs”, it depends on your system settings.

Notes:

  • In Python 3.2 the result of getfilesystemencoding() can no longer be None.
  • As of Python 3.6, Windows is no longer guaranteed to return “mbcs” encoding.
  • In Python 3.7 in UTF-8 mode, the encoding is always “utf-8”.

sys.getwindowsversion()

This function only works with Windows. It returns a tuple describing which version of Windows is currently running. The tuple contains up to 10 items showing various information about the operating system (build version, platform version and other information). To access a particular component of the tuple, just refer to it by the index “sys.getwindowsversion()[1]” or the name “sys.getwindowsversion().platform”. To maintain compatibility with previous versions, only the first five elements can be retrieved by index. Let’s list all 10 naming options: major, minor, build, platform, service_pack, service_pack_minor, service_pack_major, suite_mask, product_type and platform_version. Some elements can output multiple values, for example, the “platform_version” element returns the major version, minor version and OS build number.

import sys
print(sys.getwindowsversion())
print(sys.getwindowsversion().platform_version)

sys.getwindowsversion(major=10, minor=0, build=17763, platform=2, 
                      service_pack='')
(10, 0, 17763)

sys.platform

A string giving information about the operating system used (platform ID). For example, “win32”.

sys.winver

Contains the version number of Python used in the Windows registry. For example, “3.8-32”. It is used for informational purposes only, that is, even if you change the values of “sys.winver”, the values in the Windows registry will not change.

Information about the interpreter parameters

sys.argv

A list consisting of the command line arguments that are used in the current Python script. argv[0] is the name of the script. If the command was executed with the “-c” option, argv[0] places the string “-c”. If the script name has not been passed to the interpreter, argv[0] will be an empty string.

sys.byteorder

Shows the byte order. Different platforms can use both “big-endian”, which is direct byte numbering, and “little-endian”, which is reverse byte numbering. For example, when writing a two-byte integer to computer memory, the most significant byte goes first, followed by the least significant byte. In reverse numbering, the least significant byte goes first.

sys.builtin_module_names

A tuple that shows all modules available to the Python interpreter. sys.builtin_module_names is the only way to get this information, any other tools can only show a list of modules imported into the script.

sys.breakpointhook()

This intercept function is called by the built-in breakpoint() function. By default it puts the script into a pdb debugger, but you can set any other function to be used for debugging. In the normal implementation, the function first calls the local environment variable PYTHONBREAKPOINT. If it has a value of “0”, the function returns immediately, that is, no action will be performed. If the environment variable is not defined or is an empty string, pdb.set_trace() is called.

sys.copyright

A string giving copyright information about the Python interpreter.

sys._current_frames()

Returns a dictionary giving information about active threads. The function is only used for internal or specialized purposes. Example output:

{2788: <frame at 0x03A76418, file 'D:pythontestloader.py', 
        line 59, code run>,
7796: <frame at 0x03B02190, file 'D:{pythontestloader.py', 
        line 27, code out>}

A thread was created here, and you can use this function to track what thread is currently running. The name of the script, the line of code being executed, and the name of the function being executed are specified.

sys.flags

A tuple that defines the status of command line flags, all attributes are read-only. Here is an example output:

sys.flags(debug=0, inspect=0, interactive=0, optimize=0, 
dont_write_bytecode=0, no_user_site=0, no_site=0, ignore_environment=0, 
verbose=0, bytes_warning=0, quiet=0, hash_randomization=1, isolated=0, 
dev_mode=False, utf8_mode=0)

sys.float_info

A named tuple that contains information about the type “float”. It contains accuracy data and the internal representation of numbers of this type. The values correspond to the floating point constants defined in the float.h file for the C programming language.

Attribute Float.h macro Explanation
epsilon DBL_EPSILON The smallest possible difference between 1.0 and a value greater than 1.0, represented as “float”
dig DBL_DIG Maximum number of digits that can be accurately represented in a float number
mant_dig DBL_MANT_DIG Floating point precision
max DBL_MAX Maximum possible representation of an infinite floating point number
max_exp DBL_MAX_EXP Maximum integer e such that radix**(e-1) is a representable finite floating point number
max_10_exp DBL_MAX_10_EXP Maximum integer e such that 10**e is in the range of finite floating point numbers
min DBL_MIN Minimum positive “float” number
min_exp DBL_MIN_EXP Minimal integer e such that the “float” number is a normalized floating point number
min_10_exp DBL_MIN_10_EXP Minimum integer e such that 10**e is a normalized floating point number
radix FLT_RADIX The basis for the exponential form of representation
rounds FLT_ROUNDS Integer constant which indicates which rounding mode is used for arithmetic operations

Example output:

sys.float_info(max=1.7976931348623157e+308, max_exp=1024, max_10_exp=308, 
min=2.2250738585072014e-308, min_exp=-1021, min_10_exp=-307, dig=15, 
mant_dig=53, epsilon=2.220446049250313e-16, radix=2, rounds=1)

sys.float_repr_style

A string that shows the behavior of repr() for numbers of type “float”. If the string is “short”, then for the final number x, the repr(x) function tries to create a string such that float(repr(x)) equals x with the minimum number of decimal digits. If float_repr_style is “legacy” and repr(x) behaves the same way it did before Python 3.1 – rounding to 17 decimal digits.

sys.getdefaultencoding()

A function which returns the name of the default encoding, such as “utf-8”.

sys.getallocatedblocks()

Returns the number of memory blocks used by the interpreter, regardless of their size. This function is mostly used for tracking and debugging memory leaks. Each new output of the function can be different from the previous one, this is due to the interpreter’s internal cache. You must use _clear_type_cache() and gc.collect() to get correct results. If for some reason the interpreter can’t figure out the information about the number of memory blocks, the function will return zero.

sys.getandroidapilevel()

Only available on the Android platform. Returns the version of the Android API build.

sys.getrecursionlimit()

Returns the maximum possible recursion value and the maximum stack depth of the interpreter. This limit prevents the C stack from overflowing, which in turn causes Python to crash. You can set the recursion limit with setrecursionlimit(). An example of using recursion is one possible way of finding Fibonacci numbers.

sys.getswitchinterval()

Returns a number that determines how often the threads are switched. It is a real number. The value is in seconds. For example: “0.005”.

sys.hexversion

The version number of the Python interpreter, encoded by a single number. This number increases with each version, including all kinds of releases.

sys.hexversion is used to verify if the interpreter supports a function. If not, the function is replaced by some supported analog.

This number is called “hexversion” because it only takes on a comprehensible form if it is passed to the hex() function. An example version is 50856176.

sys.hash_info

A tuple that contains information about hash parameters.

Attribute Explanation
width How many bits are used for hash values
modulus The simple modulus used for the numeric hash scheme
inf The hash value returned for +∞
nan Hash value returned for type nan
imag The multiplier which is used to represent the imaginary part of a complex number
algorithm The name of the algorithm used for string and byte hashing and memory representation
hash_bits Internal output size of the hashing algorithm
seed_bits The size of the hashing algorithm’s seed

Example output:

sys.hash_info(width=32, modulus=2147483647, inf=314159, nan=0, 
imag=1000003, algorithm='siphash24', hash_bits=64, seed_bits=128, 
cutoff=0)

sys.implementation

An object that gives information about the currently running Python interpreter. The object must contain attributes: name, version, hexadecimal version, cache descriptor. Example:

namespace(cache_tag='cpython-38', hexversion=50856176, name='cpython', 
version=sys.version_info(major=3, minor=8, micro=0, releaselevel='final', 
serial=0))

sys.int_info

A tuple that gives information about the representation of integers in the Python interpreter. All attributes are read-only. For example:

sys.int_info(bits_per_digit=15, sizeof_digit=2)

sys.maxsize

A number that shows the maximum value a variable of type Py_ssize_t can take. This is also the maximum size of lists, dictionaries, strings and other containers. Example value: 2147483647.

sys.maxunicode

A number indicating the maximum number of bits that can be allocated per Unicode character representation. For example: 1114111.

sys.modules

A dictionary giving information about the modules loaded in the script.

It can be changed to forcibly reload or remove modules, but these manipulations may cause Python to crash.

sys.path

A list of strings that shows in which directories the modules are searched. It is initialized from the PYTHONPATH environment variable and default settings. The first item in the list (path[0]) is the directory where the script that runs the Python interpreter is located. This list can be changed by the program. Only strings and byte strings can be added to sys.path, other data types are ignored during import.

sys.dont_write_bytecode

If sys.dont_write_bytecode is set to True, Python will not write “.pyc” files when importing modules. The value is set depending on the “-B” command line parameter and the value of the PYTHONDONTWRITEBYTECODE environment variable, it can also be set independently to control the creation of bytecode files.

sys.setrecursionlimit(limit)

A function that allows you to set a recursion depth limit for the Python interpreter. The limit prevents possible errors that occur when the stack overflows in C. The maximum recursion limit depends on the platform. The user can set a large limit if it is required by the application and supported by the platform, but care must be taken or too large a limit may crash the program.

sys.setswitchinterval(interval)

Allows you to set the speed at which threads are switched (time in seconds).

sys.version

A string consisting of the Python version number as well as additional information about the build number and compiler used. For example:

3.8.0 (tags/v3.8.0:fa919fd, Oct 14 2019, 19:21:23) [MSC v.1916 32 bit 
(Intel)]

sys.api_version

Information about the C API version used by the interpreter. Used when debugging conflicts that arise when Python and auxiliary modules interact. Example value: 1013.

Functions for working with objects

sys.getrefcount(object)

Returns the number of references to the object passed as an argument. The number of references is one more than expected because it includes a temporary reference as an argument when you call getrefcount() itself. As an example, let’s store an object of the Example class in the example variable. Then create a reference to the object. Calling getrefcount() will create another reference to example. The result will be 3.

import sys
class Example:
    pass
example = Example()
temp = example
print(sys.getrefcount(example))

3

sys.getsizeof(object[, default])

Shows how many bytes are allocated to store an object of any type.

It shows the memory used by the object itself, not the memory used by all objects associated with the main object.

The function calls the __sizeof__() method on the object. The size of the data allocated to the garbage collector, if the object is under its control, is added to this value.

import sys
class Example:
    pass
example = Example()
print(example.__sizeof__())
print(sys.getsizeof(example))

16
24

sys._getframe([depth])

Returns a frame object from the call stack. If the optional “depth” argument is passed, the function returns the frame object that is lower by the given amount of stack vertices. If the value of “depth” is greater than the call stack, a ValueError exception is thrown. The default value for “depth” is zero, which means that the function will return the topmost frame of the stack. To make it easier to understand, here is an example. We will call the example() function, which in turn will call the test() function. All these calls will be written alternately on the stack. Use _getframe() to get the frame objects from the stack:

import sys
def test():
    print(sys._getframe(0))
    print(sys._getframe(1))
    print(sys._getframe(2))
    print(sys._getframe(3))
def example():
    test()
example()

This is what will be generated as a result of execution:

sys._getframe([depth])Functions that perform actions and conversions

sys.call_tracing(function, arguments)

Calls a function, with tracing enabled, the tracing state is saved and restored after the function is executed. This is used when you want to debug some code from some checkpoint.

sys._clear_type_cache()

Clears the internal type cache, which is used to quickly find attributes and methods. The function is only used during debugging to remove unnecessary references.

sys.exit([arg])

Exit Python. Throws a SystemExit exception, which can be caught. You can optionally pass an argument to the function, which can be an integer (usually 0 to 127). If zero is passed, completion is normal; any other value results in “unsuccessful completion”. If the argument is not in the correct numeric range, the function may return undefined results. Some programmers follow certain rules when specifying an argument value, e.g., “2” may indicate exit due to a syntax error, and “3” may indicate exit due to a stack overflow. sys.exit is a quick way to exit a program if an error occurs.

sys.stdin

A standard input stream that is used for interactive input, including input() calls. A file-like object, you can read data using its read method.

sys.stdout

A standard output stream that is used to output print(), expressions, and input() requests. A file-like object, data can be written to it using its write method.

sys._enablelegacywindowsfsencoding()

Changes the file system encoding to “mbsc” and the error mode to “replace”. Acts the same as defining the PYTHONLEGACYWINDOWSFSENCODING environment variable before starting Python.

Functions for handling errors and exceptions

sys.exc_info()

A function that returns a tuple consisting of three elements that show information about the exception currently being handled. If no exceptions are being handled, the tuple consists of three elements with the value None. Otherwise it has values: type, values, trace. For example:

(<class 'ZeroDivisionError'>, ZeroDivisionError('division by zero'), 

<traceback object at 0x02D93EE8>)

sys.last_type, sys.last_value, sys.last_traceback

These three variables output exception information like the previous function exc_info(). They are also used when debugging a program or displaying error messages.

sys.getfilesystemencodeerrors()

Shows which mode of handling unsupported encoded characters when converting filenames from Unicode to byte representation. On Windows the default is “surrogatepass” or “replace”. On other operating systems “surrogateescape”.

sys.stderr

The standard error output stream to which all interpreter errors are sent. A file-like object, data can be read using its read method.

sys.settrace(trace function)

Sets the system trace function, which allows debugging of Python source code. The function is single-thread oriented; for the debugger to support multiple threads, you need to register a trace function with settrace() for each thread. Trace functions must have three arguments: frame, event, and arg. Frame is the current stack frame, event is an event: “call”, “line”, “return”, “exception” or “opcode”, and arg is an event type dependent argument. If a function causes an error, it is reset, like when calling settrace(None). The events have the following values:

  • “call”. The function is called. Global trace function is also called; arg has value None; return value refers to local trace function.
  • “line”. The interpreter prepares to execute a new line of code or repeat a loop condition. Local trace function is called; arg takes value None; return value refers to new local trace function.
  • “return”. The function prepares to return a value. The local trace function is called; arg takes the return value, or None if an exception is raised. The return value of the trace function is ignored.
  • “Exception. An exception was raised; a local trace function is called; arg is a tuple of three elements (type, value, trace); the return value refers to the new local trace function.
  • “opcode”. The interpreter prepares to execute the new operation code. A local trace function is called; arg takes the value None; the return value refers to the new local trace function.

Here’s an example: let’s create a tarse function. It will simply output the arguments it receives to the console. Let’s set it to trace. After that, we will write some code: we will call a function that calculates the sum of two numbers. We will output the result to the console.

import sys
def trace_func(frame, event, arg):
    print('FRAME: ' + str(frame))
    print('EVENT: ' + str(event))
    print('ARG: ' + str(arg))
sys.settrace(trace_func)
def sum(a, b):
    return a + b
a = sum(4, 7)
print(a)

The result of running the program is as follows:

sys.settrace(trace function)Here we see that as soon as the sum function is called, our trace function with the “call” event is immediately triggered.

Related Posts

LEAVE A COMMENT