circuitpython/docs/library/sys.rst

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

125 lines
3.7 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`.
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.
.. admonition:: Difference to CPython
:class: attention
On MicroPython, an entry with the value ``".frozen"`` will indicate that import
should search :term:`frozen modules <frozen module>` at that point in the search.
If no frozen module is found then search will *not* look for a directory called
``.frozen``, instead it will continue with the next entry in ``sys.path``.
.. 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.
.. admonition:: Difference to CPython
:class: attention
Only the first three version numbers (major, minor, micro) are supported and
they can be referenced only by index, not by name.