circuitpython/docs/library/sys.rst

125 lines
3.6 KiB
ReStructuredText
Raw Normal View History

2014-10-31 18:21:37 -04:00
:mod:`sys` -- system specific functions
=======================================
.. include:: ../templates/unsupported_in_circuitpython.inc
.. module:: sys
:synopsis: system specific functions
|see_cpython_module| :mod:`cpython:sys`.
Functions
---------
.. function:: exit(retval=0)
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=sys.stdout)
2014-12-06 17:18:37 -05:00
Print exception with a traceback to a file-like object *file* (or
`sys.stdout` by default).
2014-12-06 17:18:37 -05:00
.. admonition:: Difference to CPython
:class: attention
This is simplified version of a function which appears in the
``traceback`` module in CPython. Unlike ``traceback.print_exception()``,
this function takes just exception value instead of exception type,
exception value, and traceback object; *file* argument should be
positional; further arguments are not supported.
Constants
---------
.. data:: argv
A mutable list of arguments the current program was started with.
.. data:: byteorder
The byte order of the system (``"little"`` or ``"big"``).
2016-05-01 06:59:34 -04:00
.. data:: implementation
Object with information about the current Python implementation. For
2018-05-22 19:52:01 -04:00
CircuitPython, it has following attributes:
2016-05-01 06:59:34 -04:00
2018-05-22 19:52:01 -04:00
* *name* - string "circuitpython"
* *version* - tuple (major, minor, micro), e.g. (1, 7, 0)
2016-05-01 06:59:34 -04:00
2018-05-22 19:52:01 -04:00
This object is the recommended way to distinguish CircuitPython from other
2016-05-01 06:59:34 -04:00
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
2018-05-22 19:52:01 -04:00
bare minimum is implemented in CircuitPython.
2016-05-01 06:59:34 -04:00
2016-05-01 07:31:08 -04:00
.. data:: maxsize
Maximum value which a native integer type can hold on the current platform,
2018-05-22 19:52:01 -04:00
or maximum value representable by CircuitPython integer type, if it's smaller
than platform max value (that is the case for CircuitPython ports without
2016-05-01 07:31:08 -04:00
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.
2016-05-01 06:32:15 -04:00
.. 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.
.. data:: platform
2018-05-22 19:52:01 -04:00
The platform that CircuitPython is running on. For OS/RTOS ports, this is
usually an identifier of the OS, e.g. ``"linux"``. For baremetal ports it
2018-05-22 19:52:01 -04:00
is an identifier of the chip on a board, e.g. ``"MicroChip SAMD51"``.
It thus can be used to distinguish one board from another.
If you need to check whether your program runs on CircuitPython (vs other
Python implementation), use `sys.implementation` instead.
.. data:: stderr
Standard error ``stream``.
.. data:: stdin
Standard input ``stream``.
.. data:: stdout
Standard output ``stream``.
.. data:: version
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.