diff options
Diffstat (limited to 'docs/library/sys.rst')
| -rw-r--r-- | docs/library/sys.rst | 84 |
1 files changed, 68 insertions, 16 deletions
diff --git a/docs/library/sys.rst b/docs/library/sys.rst index b3e52c40c..b5a9138c0 100644 --- a/docs/library/sys.rst +++ b/docs/library/sys.rst @@ -7,14 +7,15 @@ Functions --------- -.. function:: exit([retval]) +.. function:: exit(retval=0) - Raise a ``SystemExit`` exception. If an argument is given, it is the - value given to ``SystemExit``. + Terminate current program with a given exit code. Underlyingly, this + function raise as ``SystemExit`` exception. If an argument is given, its + value given as an argument to ``SystemExit``. -.. function:: print_exception(exc, [file]) +.. function:: print_exception(exc, file=sys.stdout) - Print exception with a traceback to a file-like object ``file`` (or + Print exception with a traceback to a file-like object `file` (or ``sys.stdout`` by default). .. admonition:: Difference to CPython @@ -27,38 +28,89 @@ Constants .. data:: argv - a mutable list of arguments this program started with + A mutable list of arguments the current program was started with. .. data:: byteorder - the byte order of the system ("little" or "big") + The byte order of the system ("little" or "big"). + +.. data:: implementation + + Object with information about the current Python implementation. For + MicroPython, it has following attributes: + + * `name` - string "micropython" + * `version` - tuple (major, minor, micro), e.g. (1, 7, 0) + + This object is the recommended way to distinguish MicroPython from other + Python implementations (note that it still may not exist in the very + minimal ports). + + .. admonition:: Difference to CPython + :class: attention + + CPython mandates more attributes for this object, but the actual useful + bare minimum is implemented in MicroPython. + +.. data:: maxsize + + Maximum value which a native integer type can hold on the current platform, + or maximum value representable by MicroPython integer type, if it's smaller + than platform max value (that is the case for MicroPython ports without + long int support). + + This attribute is useful for detecting "bitness" of a platform (32-bit vs + 64-bit, etc.). It's recommended to not compare this attribute to some + value directly, but instead count number of bits in it:: + + bits = 0 + v = sys.maxsize + while v: + bits += 1 + v >>= 1 + if bits > 32: + # 64-bit (or more) platform + ... + else: + # 32-bit (or less) platform + # Note that on 32-bit platform, value of bits may be less than 32 + # (e.g. 31) due to peculiarities described above, so use "> 16", + # "> 32", "> 64" style of comparisons. + +.. data:: modules + + Dictionary of loaded modules. On some ports, it may not include builtin + modules. .. data:: path - a mutable list of directories to search for imported modules + A mutable list of directories to search for imported modules. .. data:: platform - The platform that MicroPython is running on. This is "pyboard" on the - pyboard and provides a robust way of determining if a script is running - on the pyboard or not. + The platform that MicroPython is running on. For OS/RTOS ports, this is + usually an identifier of the OS, e.g. ``"linux"``. For baremetal ports it + is an identifier of a board, e.g. "pyboard" for the original MicroPython + reference board. It thus can be used to distinguish one board from another. + If you need to check whether your program runs on MicroPython (vs other + Python implementation), use ``sys.implementation`` instead. .. data:: stderr - standard error (connected to USB VCP, and optional UART object) + Standard error stream. .. data:: stdin - standard input (connected to USB VCP, and optional UART object) + Standard input stream. .. data:: stdout - standard output (connected to USB VCP, and optional UART object) + Standard output stream. .. data:: version - Python language version that this implementation conforms to, as a string + Python language version that this implementation conforms to, as a string. .. data:: version_info - Python language version that this implementation conforms to, as a tuple of ints + Python language version that this implementation conforms to, as a tuple of ints. |