This is the documentation for the latest development branch of MicroPython and may refer to features that are not available in released versions.

If you are looking for the documentation for a specific release, use the drop-down menu on the left and select the desired version.

Modules

Generated Fri 20 Dec 2024 19:11:08 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:
	Traceback (most recent call last): File "<stdin>", line 9, in <module> NotImplementedError:

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	array('b', [1])

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:

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

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

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

json

JSON module does not throw exception when object is not serialisable

Sample code:

import json

try:
    print(json.dumps(b"shouldn't be able to serialise bytes"))
except TypeError:
    print("TypeError")

CPy output:	uPy output:
TypeError	"shouldn't be able to serialise bytes"

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	should not get here None VALUE

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

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:
2620957806073053289	Traceback (most recent call last): File "<stdin>", line 11, in <module> ValueError: bits must be 32 or less

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=340282366920938463463374607431768211456	Traceback (most recent call last): File "<stdin>", line 11, in <module> OverflowError: overflow converting long int to machine word

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	b'\x01\x00' Should not get here

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

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	struct.error

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	Traceback (most recent call last): File "<stdin>", line 9, in <module> AttributeError: 'module' object has no attribute 'stdin'