Modules¶

Generated Thu 05 Sep 2024 00:47:45 UTC

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.

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 MicroPython 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¶

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:
	/bin/sh: 1: ../ports/unix/build-standard/micropython: not found

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): File "<stdin>", line 9, in <module> OverflowError: signed char is greater than maximum	/bin/sh: 1: ../ports/unix/build-standard/micropython: not found

Looking for integer not implemented¶

Sample code:

import array

print(1 in array.array("B", b"12"))

CPy output:	uPy output:
False	/bin/sh: 1: ../ports/unix/build-standard/micropython: not found

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])	/bin/sh: 1: ../ports/unix/build-standard/micropython: not found

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')	/bin/sh: 1: ../ports/unix/build-standard/micropython: not found

builtins¶

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	/bin/sh: 1: ../ports/unix/build-standard/micropython: not found

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([])	/bin/sh: 1: ../ports/unix/build-standard/micropython: not found

json¶

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	/bin/sh: 1: ../ports/unix/build-standard/micropython: not found

os¶

`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 VALUE	/bin/sh: 1: ../ports/unix/build-standard/micropython: not found

`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	/bin/sh: 1: ../ports/unix/build-standard/micropython: not found

random¶

`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:
13234793640459878723	/bin/sh: 1: ../ports/unix/build-standard/micropython: not found

`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	/bin/sh: 1: ../ports/unix/build-standard/micropython: not found

struct¶

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	/bin/sh: 1: ../ports/unix/build-standard/micropython: not found

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	/bin/sh: 1: ../ports/unix/build-standard/micropython: not found

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' Should have worked	/bin/sh: 1: ../ports/unix/build-standard/micropython: not found

sys¶

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	/bin/sh: 1: ../ports/unix/build-standard/micropython: not found

Modules¶

Positional-only Parameters¶

Example¶

array¶

Comparison between different typecodes not supported¶

Overflow checking is not implemented¶

Looking for integer not implemented¶

Array deletion not implemented¶

Subscript with step != 1 is not yet implemented¶

builtins¶

Second argument to next() is not implemented¶

deque¶

Deque not implemented¶

json¶

JSON module does not throw exception when object is not serialisable¶

os¶

environ attribute is not implemented¶

getenv returns actual value instead of cached value¶

random¶

getrandbits method can only return a maximum of 32 bits at a time.¶

randint method can only return an integer that is at most the native word size.¶

struct¶

Struct pack with too few args, not checked by uPy¶

Struct pack with too many args, not checked by uPy¶

Struct pack with whitespace in format, whitespace ignored by CPython, error on uPy¶

sys¶

Overriding sys.stdin, sys.stdout and sys.stderr not possible¶

`environ` attribute is not implemented¶

`getenv` returns actual value instead of cached value¶

`getrandbits` method can only return a maximum of 32 bits at a time.¶

`randint` method can only return an integer that is at most the native word size.¶