核心语言¶

Generated Fri 19 Jun 2026 22:08:45 UTC

类¶

用户自定义类未实现特殊方法 `del`¶

示例代码:

import gc

class Foo:
    def __del__(self):
        print("__del__")

f = Foo()
del f

gc.collect()

CPython output:	MicroPython output:
__del__

`__init_subclass__` isn't automatically called.¶

Cause: MicroPython does not currently implement PEP 487.

Workaround: Manually call __init_subclass__ after class creation if needed. e.g.:

class A(Base):
    pass
A.__init_subclass__()

示例代码:

class Base:
    @classmethod
    def __init_subclass__(cls):
        print(f"Base.__init_subclass__({cls.__name__})")


class A(Base):
    pass

CPython output:	MicroPython output:
Base.__init_subclass__(A)

`__init_subclass__` isn't an implicit classmethod.¶

Cause: MicroPython does not currently implement PEP 487. __init_subclass__ is not currently in the list of special-cased class/static methods.

Workaround: Decorate declarations of __init_subclass__ with @classmethod.

示例代码:

def regularize_spelling(text, prefix="bound_"):
    # for regularizing across the CPython "method" vs MicroPython "bound_method" spelling for the type of a bound classmethod
    if text.startswith(prefix):
        return text[len(prefix) :]
    return text


class A:
    def __init_subclass__(cls):
        pass

    @classmethod
    def manual_decorated(cls):
        pass


a = type(A.__init_subclass__).__name__
b = type(A.manual_decorated).__name__

print(regularize_spelling(a))
print(regularize_spelling(b))
if a != b:
    print("FAIL")

CPython output:	MicroPython output:
method method	function method FAIL

MicroPython doesn't support parameterized `__init_subclass__` class customization.¶

Cause: MicroPython does not currently implement PEP 487. The MicroPython syntax tree does not include a kwargs node after the class inheritance list.

Workaround: Use class variables or another mechanism to specify base-class customizations.

示例代码:

class Base:
    @classmethod
    def __init_subclass__(cls, arg=None, **kwargs):
        cls.init_subclass_was_called = True
        print(f"Base.__init_subclass__({cls.__name__}, {arg=!r}, {kwargs=!r})")


class A(Base, arg="arg"):
    pass


# Regularize across MicroPython not automatically calling __init_subclass__ either.
if not getattr(A, "init_subclass_was_called", False):
    A.__init_subclass__()

CPython output:	MicroPython output:
Base.__init_subclass__(A, arg='arg', kwargs={})	Traceback (most recent call last): File "<stdin>", line 16, in <module> TypeError: function doesn't take keyword arguments

`__init_subclass__` can't be defined a cooperatively-recursive way.¶

Cause: MicroPython does not currently implement PEP 487. The base object type does not have an __init_subclass__ implementation.

Workaround: Omit the recursive __init_subclass__ call unless it's known that the grandparent also defines it.

示例代码:

class Base:
    @classmethod
    def __init_subclass__(cls, **kwargs):
        cls.init_subclass_was_called = True
        super().__init_subclass__(**kwargs)


class A(Base):
    pass


# Regularize across MicroPython not automatically calling __init_subclass__ either.
if not getattr(A, "init_subclass_was_called", False):
    A.__init_subclass__()

CPython output:	MicroPython output:
	Traceback (most recent call last): File "<stdin>", line 22, in <module> File "<stdin>", line 13, in __init_subclass__ AttributeError: 'super' object has no attribute '__init_subclass__'

方法解析顺序（MRO）与 CPython 不兼容¶

原因： 采用深度优先的非穷举方法解析顺序。

解决方法： 避免使用包含多重继承和复杂方法覆盖的复杂类层次结构。请注意，许多编程语言根本不支持多重继承。

示例代码:

class Foo:
    def __str__(self):
        return "Foo"


class C(tuple, Foo):
    pass


t = C((1, 2, 3))
print(t)

CPython output:	MicroPython output:
Foo	(1, 2, 3)

未实现私有类成员的名称混淆¶

原因： MicroPython 编译器未实现私有类成员的名称混淆。

解决方法： 手动为私有类成员名称添加唯一前缀，以避免与全局名称冲突。

示例代码:

def __print_string(string):
    print(string)


class Foo:
    def __init__(self, string):
        self.string = string

    def do_print(self):
        __print_string(self.string)


example_string = "Example String to print."

class_item = Foo(example_string)
print(class_item.string)

class_item.do_print()

CPython output:

MicroPython output:

Example String to print.
Traceback (most recent call last):
  File "<stdin>", line 26, in <module>
  File "<stdin>", line 18, in do_print
NameError: name '_Foo__print_string' is not defined. Did you mean: '__print_string'?

Example String to print.
Example String to print.

在继承原生类型时，若在 `init(self, ...)` 中于 `super().init()` 之前调用方法，将引发 `AttributeError`（若未启用 `MICROPY_BUILTIN_METHOD_CHECK_SELF_ARG` 则可能导致段错误）。¶

原因： MicroPython 的原生类型中没有独立的 __new__ 和 __init__ 方法。

解决方法： 先调用 super().__init__()。

示例代码:

class L1(list):
    def __init__(self, a):
        self.append(a)


try:
    L1(1)
    print("OK")
except AttributeError:
    print("AttributeError")


class L2(list):
    def __init__(self, a):
        super().__init__()
        self.append(a)


try:
    L2(1)
    print("OK")
except AttributeError:
    print("AttributeError")

CPython output:	MicroPython output:
OK OK	AttributeError OK

从多个类继承时，`super()` 只调用一个类¶

原因： 请参见方法解析顺序（MRO）与 CPython 不兼容。

解决方法： 请参见方法解析顺序（MRO）与 CPython 不兼容。

示例代码:

class A:
    def __init__(self):
        print("A.__init__")


class B(A):
    def __init__(self):
        print("B.__init__")
        super().__init__()


class C(A):
    def __init__(self):
        print("C.__init__")
        super().__init__()


class D(B, C):
    def __init__(self):
        print("D.__init__")
        super().__init__()


D()

CPython output:	MicroPython output:
D.__init__ B.__init__ C.__init__ A.__init__	D.__init__ B.__init__ A.__init__

在子类中调用 `super()` 的 getter 属性将返回属性对象，而非其值¶

示例代码:

class A:
    @property
    def p(self):
        return {"a": 10}


class AA(A):
    @property
    def p(self):
        return super().p


a = AA()
print(a.p)

CPython output:	MicroPython output:
{'a': 10}	<property>

Exceptions¶

Throwing a derived exception class instance in its `init` without first calling `super().init` is a TypeError¶

Cause: In MicroPython, an object is incompletely constructed if it does not call its superclass init function or return normally from its __init__. This prevents its usage in some circumstances.

Workaround: Call the superclass __init__ method before raising the exception.

示例代码:

class C(Exception):
    def __init__(self):
        raise self


class C1(Exception):
    def __init__(self):
        super().__init__()
        raise self


try:
    C()
except Exception as e:
    print(type(e).__name__)

try:
    C1()
except Exception as e:
    print(type(e).__name__)

CPython output:	MicroPython output:
C C1	TypeError C1

函数¶

方法的错误信息可能显示意外的参数个数¶

原因： MicroPython 将 "self" 计入参数个数。

解决方法： 解读错误信息时请考虑上述情况。

示例代码:

try:
    [].append()
except Exception as e:
    print(e)

CPython output:	MicroPython output:
list.append() takes exactly one argument (0 given)	function takes 2 positional arguments but 1 were given

函数对象没有 `module` 属性¶

原因： MicroPython 针对减少代码体积和 RAM 占用进行了优化。

解决方法： 对于非内置模块，使用 sys.modules[function.__globals__['__name__']]。

示例代码:

def f():
    pass


print(f.__module__)

CPython output:	MicroPython output:
__main__	Traceback (most recent call last): File "<stdin>", line 13, in <module> AttributeError: 'function' object has no attribute '__module__'

不支持函数的用户自定义属性¶

原因： MicroPython 针对内存使用进行了高度优化。

解决方法： 使用外部字典，例如 FUNC_X[f] = 0。

示例代码:

def f():
    pass


f.x = 0
print(f.x)

CPython output:	MicroPython output:
0	Traceback (most recent call last): File "<stdin>", line 13, in <module> AttributeError: 'function' object has no attribute 'x'

生成器¶

未运行至结束的生成器中，上下文管理器的 `exit()` 不会被调用¶

示例代码:

class foo(object):
    def __enter__(self):
        print("Enter")

    def __exit__(self, *args):
        print("Exit")


def bar(x):
    with foo():
        while True:
            x += 1
            yield x


def func():
    g = bar(0)
    for _ in range(3):
        print(next(g))


func()

CPython output:	MicroPython output:
Enter 1 2 3 Exit	Enter 1 2 3

运行时¶

局部变量不包含在 `locals()` 的结果中¶

原因： MicroPython 不维护符号化的局部环境，而是优化为槽数组，因此局部变量无法通过名称访问。

示例代码:

def test():
    val = 2
    print(locals())


test()

CPython output:	MicroPython output:
{'val': 2}	{'test': <function test at 0x7f5d74c05260>, '__name__': '__main__', '__file__': '<stdin>'}

在 `eval()` 函数中运行的代码无法访问局部变量¶

原因： MicroPython 不维护符号化的局部环境，而是优化为槽数组，因此局部变量无法通过名称访问。实际上，MicroPython 中的 eval(expr) 等价于 eval(expr, globals(), globals())。

示例代码:

val = 1


def test():
    val = 2
    print(val)
    eval("print(val)")


test()

CPython output:	MicroPython output:
2 2	2 1

f-strings¶

若相邻字面量包含花括号，f-string 不支持与其拼接¶

原因： MicroPython 针对代码空间进行了优化。

解决方法： 当两个字符串不都是 f-string 时，使用 + 运算符进行拼接。

示例代码:

x, y = 1, 2
print("aa" f"{x}")  # works
print(f"{x}" "ab")  # works
print("a{}a" f"{x}")  # fails
print(f"{x}" "a{}b")  # fails

CPython output:	MicroPython output:
aa1 1ab a{}a1 1a{}b	aa1 1ab Traceback (most recent call last): File "<stdin>", line 12, in <module> IndexError: tuple index out of range

f-string 不支持需要解析来处理不平衡嵌套花括号和方括号的表达式¶

原因： MicroPython 针对代码空间进行了优化。

解决方法： 在 f-string 内的表达式中始终使用平衡的花括号和方括号。

示例代码:

print(f"{'hello { world'}")
print(f"{'hello ] world'}")

CPython output:	MicroPython output:
hello { world hello ] world	Traceback (most recent call last): File "<stdin>", line 9 SyntaxError: invalid syntax

f-string 不支持 `!a` 转换¶

原因： MicroPython 未实现 ascii()。

解决方法： 无。

示例代码:

f"{'unicode text'!a}"

CPython output:	MicroPython output:
	Traceback (most recent call last): File "<stdin>", line 8 SyntaxError: invalid syntax

import¶

MicroPython 中包的 `path` 属性类型不同（单个字符串而非字符串列表）¶

原因： MicroPython 不支持跨文件系统拆分的命名空间包，且其导入系统针对最小内存占用进行了高度优化。

解决方法： 导入处理的细节本质上依赖于具体实现，请勿在可移植应用中依赖这些细节。

示例代码:

import modules

print(modules.__path__)

CPython output:	MicroPython output:
['/home/runner/work/openmv-doc/openmv-doc/micropython/tests/cpydiff/modules']	../tests/cpydiff/modules

MicroPython 不支持跨文件系统拆分的命名空间包。¶

原因： MicroPython 的导入系统针对简洁性、最小内存占用和最小文件系统搜索开销进行了高度优化。

解决方法： 不要将属于同一命名空间包的模块安装到不同目录。对于 MicroPython，建议模块搜索路径最多包含 3 个部分：当前应用目录、用户级（可写）和系统级（只读）。

示例代码:

import sys

sys.path.append(sys.path[1] + "/modules")
sys.path.append(sys.path[1] + "/modules2")

import subpkg.foo
import subpkg.bar

print("Two modules of a split namespace package imported")

CPython output:	MicroPython output:
Two modules of a split namespace package imported	Traceback (most recent call last): File "<stdin>", line 14, in <module> ImportError: no module named 'subpkg.bar'

核心语言¶

类¶

用户自定义类未实现特殊方法 __del__¶

__init_subclass__ isn't automatically called.¶

__init_subclass__ isn't an implicit classmethod.¶

MicroPython doesn't support parameterized __init_subclass__ class customization.¶

__init_subclass__ can't be defined a cooperatively-recursive way.¶

方法解析顺序（MRO）与 CPython 不兼容¶

未实现私有类成员的名称混淆¶

在继承原生类型时，若在 __init__(self, ...) 中于 super().__init__() 之前调用方法，将引发 AttributeError（若未启用 MICROPY_BUILTIN_METHOD_CHECK_SELF_ARG 则可能导致段错误）。¶

从多个类继承时，super() 只调用一个类¶

在子类中调用 super() 的 getter 属性将返回属性对象，而非其值¶

Exceptions¶

Throwing a derived exception class instance in its __init__ without first calling super().__init__ is a TypeError¶

函数¶

方法的错误信息可能显示意外的参数个数¶

函数对象没有 __module__ 属性¶

不支持函数的用户自定义属性¶

生成器¶

未运行至结束的生成器中，上下文管理器的 __exit__() 不会被调用¶

运行时¶

局部变量不包含在 locals() 的结果中¶

在 eval() 函数中运行的代码无法访问局部变量¶

f-strings¶

若相邻字面量包含花括号，f-string 不支持与其拼接¶

f-string 不支持需要解析来处理不平衡嵌套花括号和方括号的表达式¶

f-string 不支持 !a 转换¶

import¶

MicroPython 中包的 __path__ 属性类型不同（单个字符串而非字符串列表）¶

MicroPython 不支持跨文件系统拆分的命名空间包。¶

用户自定义类未实现特殊方法 `del`¶

`__init_subclass__` isn't automatically called.¶

`__init_subclass__` isn't an implicit classmethod.¶

MicroPython doesn't support parameterized `__init_subclass__` class customization.¶

`__init_subclass__` can't be defined a cooperatively-recursive way.¶

在继承原生类型时，若在 `init(self, ...)` 中于 `super().init()` 之前调用方法，将引发 `AttributeError`（若未启用 `MICROPY_BUILTIN_METHOD_CHECK_SELF_ARG` 则可能导致段错误）。¶

从多个类继承时，`super()` 只调用一个类¶

在子类中调用 `super()` 的 getter 属性将返回属性对象，而非其值¶

Throwing a derived exception class instance in its `init` without first calling `super().init` is a TypeError¶

函数对象没有 `module` 属性¶

未运行至结束的生成器中，上下文管理器的 `exit()` 不会被调用¶

局部变量不包含在 `locals()` 的结果中¶

在 `eval()` 函数中运行的代码无法访问局部变量¶

f-string 不支持 `!a` 转换¶

MicroPython 中包的 `path` 属性类型不同（单个字符串而非字符串列表）¶