.. This document was generated by tools/gen-cpydiff.py
Modules
=======
Generated Fri 31 May 2024 05:52:06 UTC
.. Preamble section inserted into generated output
Positional-only Parameters
--------------------------
To save code size, many functions that accept keyword arguments in CPython only accept positional arguments in MicroPython.
MicroPython marks positional-only parameters in the same way as CPython, by inserting a ``/`` to mark the end of the positional parameters. Any function whose signature ends in ``/`` takes *only* positional arguments. For more details, see `PEP 570 <https://peps.python.org/pep-0570/>`_.
Example
~~~~~~~
For example, in CPython 3.4 this is the signature of the constructor ``socket.socket``::
socket.socket(family=AF_INET, type=SOCK_STREAM, proto=0, fileno=None)
However, the signature documented in :func:`MicroPython<socket.socket>` is::
socket(af=AF_INET, type=SOCK_STREAM, proto=IPPROTO_TCP, /)
The ``/`` at the end of the parameters indicates that they are all positional-only in MicroPython. The following code works in CPython but not in most MicroPython ports::
import socket
s = socket.socket(type=socket.SOCK_DGRAM)
MicroPython will raise an exception::
TypeError: function doesn't take keyword arguments
The following code will work in both CPython and MicroPython::
import socket
s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
array
-----
.. _cpydiff_module_array_comparison:
Comparison between different typecodes not supported
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Cause:** Code size
**Workaround:** Compare individual elements
Sample code::
import array
array.array("b", [1, 2]) == array.array("i", [1, 2])
+-------------+-------------------------------------------+
| CPy output: | uPy output: |
+-------------+-------------------------------------------+
| | :: |
| | |
| | Traceback (most recent call last): |
| | File "<stdin>", line 9, in <module> |
| | NotImplementedError: |
+-------------+-------------------------------------------+
.. _cpydiff_module_array_constructor:
Overflow checking is not implemented
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Cause:** MicroPython implements implicit truncation in order to reduce code size and execution time
**Workaround:** If CPython compatibility is needed then mask the value explicitly
Sample code::
import array
a = array.array("b", [257])
print(a)
+--------------------------------------------------------+---------------------+
| CPy output: | uPy output: |
+--------------------------------------------------------+---------------------+
| :: | :: |
| | |
| Traceback (most recent call last): | array('b', [1]) |
| File "<stdin>", line 9, in <module> | |
| OverflowError: signed char is greater than maximum | |
+--------------------------------------------------------+---------------------+
.. _cpydiff_modules_array_containment:
Looking for integer not implemented
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sample code::
import array
print(1 in array.array("B", b"12"))
+-------------+-------------------------------------------+
| CPy output: | uPy output: |
+-------------+-------------------------------------------+
| :: | :: |
| | |
| False | Traceback (most recent call last): |
| | File "<stdin>", line 9, in <module> |
| | NotImplementedError: |
+-------------+-------------------------------------------+
.. _cpydiff_modules_array_deletion:
Array deletion not implemented
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sample code::
import array
a = array.array("b", (1, 2, 3))
del a[1]
print(a)
+------------------------+-------------------------------------------------------------+
| CPy output: | uPy output: |
+------------------------+-------------------------------------------------------------+
| :: | :: |
| | |
| array('b', [1, 3]) | Traceback (most recent call last): |
| | File "<stdin>", line 10, in <module> |
| | TypeError: 'array' object doesn't support item deletion |
+------------------------+-------------------------------------------------------------+
.. _cpydiff_modules_array_subscrstep:
Subscript with step != 1 is not yet implemented
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sample code::
import array
a = array.array("b", (1, 2, 3))
print(a[3:2:2])
+----------------+---------------------------------------------------------------------------+
| CPy output: | uPy output: |
+----------------+---------------------------------------------------------------------------+
| :: | :: |
| | |
| array('b') | Traceback (most recent call last): |
| | File "<stdin>", line 10, in <module> |
| | NotImplementedError: only slices with step=1 (aka None) are supported |
+----------------+---------------------------------------------------------------------------+
builtins
--------
.. _cpydiff_builtin_next_arg2:
Second argument to next() is not implemented
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Cause:** MicroPython is optimised for code space.
**Workaround:** Instead of ``val = next(it, deflt)`` use::
try:
val = next(it)
except StopIteration:
val = deflt
Sample code::
print(next(iter(range(0)), 42))
+-------------+-----------------------------------------------------------------------+
| CPy output: | uPy output: |
+-------------+-----------------------------------------------------------------------+
| :: | :: |
| | |
| 42 | Traceback (most recent call last): |
| | File "<stdin>", line 12, in <module> |
| | TypeError: function takes 1 positional arguments but 2 were given |
+-------------+-----------------------------------------------------------------------+
deque
-----
.. _cpydiff_modules_deque:
Deque not implemented
~~~~~~~~~~~~~~~~~~~~~
**Workaround:** Use regular lists. micropython-lib has implementation of collections.deque.
Sample code::
import collections
D = collections.deque()
print(D)
+---------------+-----------------------------------------------------------------+
| CPy output: | uPy output: |
+---------------+-----------------------------------------------------------------+
| :: | :: |
| | |
| deque([]) | Traceback (most recent call last): |
| | File "<stdin>", line 9, in <module> |
| | TypeError: function missing 2 required positional arguments |
+---------------+-----------------------------------------------------------------+
json
----
.. _cpydiff_modules_json_nonserializable:
JSON module does not throw exception when object is not serialisable
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sample code::
import json
a = bytes(x for x in range(256))
try:
z = json.dumps(a)
x = json.loads(z)
print("Should not get here")
except TypeError:
print("TypeError")
+---------------+--------------------------------------------+
| CPy output: | uPy output: |
+---------------+--------------------------------------------+
| :: | :: |
| | |
| TypeError | Traceback (most recent call last): |
| | File "<stdin>", line 12, in <module> |
| | UnicodeError: |
+---------------+--------------------------------------------+
os
--
.. _cpydiff_modules_os_environ:
``environ`` attribute is not implemented
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Workaround:** Use ``getenv``, ``putenv`` and ``unsetenv``
Sample code::
import os
try:
print(os.environ.get("NEW_VARIABLE"))
os.environ["NEW_VARIABLE"] = "VALUE"
print(os.environ["NEW_VARIABLE"])
except AttributeError:
print("should not get here")
print(os.getenv("NEW_VARIABLE"))
os.putenv("NEW_VARIABLE", "VALUE")
print(os.getenv("NEW_VARIABLE"))
+-------------+-------------------------+
| CPy output: | uPy output: |
+-------------+-------------------------+
| :: | :: |
| | |
| None | should not get here |
| VALUE | None |
| | VALUE |
+-------------+-------------------------+
.. _cpydiff_modules_os_getenv:
``getenv`` returns actual value instead of cached value
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Cause:** The ``environ`` attribute is not implemented
Sample code::
import os
print(os.getenv("NEW_VARIABLE"))
os.putenv("NEW_VARIABLE", "VALUE")
print(os.getenv("NEW_VARIABLE"))
+-------------+-------------+
| CPy output: | uPy output: |
+-------------+-------------+
| :: | :: |
| | |
| None | None |
| None | VALUE |
+-------------+-------------+
random
------
.. _cpydiff_modules_random_getrandbits:
``getrandbits`` method can only return a maximum of 32 bits at a time.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Cause:** PRNG's internal state is only 32bits so it can only return a maximum of 32 bits of data at a time.
**Workaround:** If you need a number that has more than 32 bits then utilize the random module from micropython-lib.
Sample code::
import random
x = random.getrandbits(64)
print("{}".format(x))
+--------------------------+--------------------------------------------+
| CPy output: | uPy output: |
+--------------------------+--------------------------------------------+
| :: | :: |
| | |
| 12118182268712600047 | Traceback (most recent call last): |
| | File "<stdin>", line 11, in <module> |
| | ValueError: bits must be 32 or less |
+--------------------------+--------------------------------------------+
.. _cpydiff_modules_random_randint:
``randint`` method can only return an integer that is at most the native word size.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Cause:** PRNG is only able to generate 32 bits of state at a time. The result is then cast into a native sized int instead of a full int object.
**Workaround:** If you need integers larger than native wordsize use the random module from micropython-lib.
Sample code::
import random
x = random.randint(2**128 - 1, 2**128)
print("x={}".format(x))
+-----------------------------------------------+-----------------------------------------------------------------+
| CPy output: | uPy output: |
+-----------------------------------------------+-----------------------------------------------------------------+
| :: | :: |
| | |
| x=340282366920938463463374607431768211455 | Traceback (most recent call last): |
| | File "<stdin>", line 11, in <module> |
| | OverflowError: overflow converting long int to machine word |
+-----------------------------------------------+-----------------------------------------------------------------+
struct
------
.. _cpydiff_modules_struct_fewargs:
Struct pack with too few args, not checked by uPy
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sample code::
import struct
try:
print(struct.pack("bb", 1))
print("Should not get here")
except:
print("struct.error")
+------------------+-------------------------+
| CPy output: | uPy output: |
+------------------+-------------------------+
| :: | :: |
| | |
| struct.error | b'\x01\x00' |
| | Should not get here |
+------------------+-------------------------+
.. _cpydiff_modules_struct_manyargs:
Struct pack with too many args, not checked by uPy
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sample code::
import struct
try:
print(struct.pack("bb", 1, 2, 3))
print("Should not get here")
except:
print("struct.error")
+------------------+-------------------------+
| CPy output: | uPy output: |
+------------------+-------------------------+
| :: | :: |
| | |
| struct.error | b'\x01\x02' |
| | Should not get here |
+------------------+-------------------------+
.. _cpydiff_modules_struct_whitespace_in_format:
Struct pack with whitespace in format, whitespace ignored by CPython, error on uPy
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Cause:** MicroPython is optimised for code size.
**Workaround:** Don't use spaces in format strings.
Sample code::
import struct
try:
print(struct.pack("b b", 1, 2))
print("Should have worked")
except:
print("struct.error")
+------------------------+------------------+
| CPy output: | uPy output: |
+------------------------+------------------+
| :: | :: |
| | |
| b'\x01\x02' | struct.error |
| Should have worked | |
+------------------------+------------------+
sys
---
.. _cpydiff_modules_sys_stdassign:
Overriding sys.stdin, sys.stdout and sys.stderr not possible
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Cause:** They are stored in read-only memory.
Sample code::
import sys
sys.stdin = None
print(sys.stdin)
+-------------+--------------------------------------------------------------+
| CPy output: | uPy output: |
+-------------+--------------------------------------------------------------+
| :: | :: |
| | |
| None | Traceback (most recent call last): |
| | File "<stdin>", line 9, in <module> |
| | AttributeError: 'module' object has no attribute 'stdin' |
+-------------+--------------------------------------------------------------+