[mypyc] Add memoization support for functools.cached_property in native classes

Previously mypyc silently compiled functools.cached_property as a plain
non-caching property: the semantic analyzer marks it is_property /
is_settable_property like builtins.property, and mypyc had no handling of
its own, so the decorated body re-ran on every access -- a severe silent
performance regression.

Where the cached value is stored depends on whether the instance has a
__dict__:

- A native (compiled) class has no instance __dict__. Its cached_property is
  backed by a hidden native slot instead, so caching works without a __dict__.
- An interpreted subclass of a native class is given its own instance __dict__
  by CPython (a heap subclass of an extension type that lacks one has a
  __dict__ added automatically). A cached_property defined on the interpreted
  subclass therefore memoizes into that __dict__ with no special handling,
  while an inherited native cached_property keeps using the native slot. No
  manual __dict__ setup (e.g. assigning self.__dict__ = {}) is required.
- The only case that cannot cache is a class that suppresses its __dict__ with
  __slots__: a functools.cached_property defined on it raises at access time.
  This is ordinary CPython behaviour, unchanged by mypyc.

Author: chadrik

mypyc/codegen/emitclass.py

@@ -32,6 +32,7 @@
     MYPYC_DEFAULTS_SETUP,
     NATIVE_PREFIX,
     PREFIX,
+    PROPCACHE_PREFIX,
     REG_PREFIX,
     short_id_from_name,
 )
@@ -1268,6 +1269,34 @@ def generate_property_setter(
         )
     )
     emitter.emit_line("{")
+    # A NULL value means that the attribute is being deleted.
+    if cl.is_cached_property(attr):
+        # Deleting a functools.cached_property clears the cached value, so that
+        # it is recomputed on the next read. This matches CPython semantics,
+        # including raising AttributeError if there is no cached value.
+        slot_attr = PROPCACHE_PREFIX + attr
+        slot_expr = f"self->{emitter.attr(slot_attr)}"
+        slot_type = cl.attr_type(slot_attr)
+        emitter.emit_line("if (value == NULL) {")
+        emitter.emit_line(f"if ({slot_expr} == NULL) {{")
+        emitter.emit_line("PyErr_SetString(PyExc_AttributeError,")
+        emitter.emit_line(f'    "attribute {repr(attr)} of {repr(cl.name)} undefined");')
+        emitter.emit_line("return -1;")
+        emitter.emit_line("}")
+        emitter.emit_dec_ref(slot_expr, slot_type)
+        emitter.emit_line(f"{slot_expr} = NULL;")
+        emitter.emit_line("return 0;")
+        emitter.emit_line("}")
+    else:
+        # Properties otherwise have no deleter, so raise AttributeError
+        # (instead of calling the setter with a NULL value).
+        emitter.emit_line("if (value == NULL) {")
+        emitter.emit_line("PyErr_SetString(PyExc_AttributeError,")
+        emitter.emit_line(
+            f'    "{repr(cl.name)} object attribute {repr(attr)} cannot be deleted");'
+        )
+        emitter.emit_line("return -1;")
+        emitter.emit_line("}")
     if arg_type.is_unboxed:
         emitter.emit_unbox("value", "tmp", arg_type, error=ReturnHandler("-1"), declare_dest=True)
         emitter.emit_line(

mypyc/common.py

@@ -23,6 +23,8 @@
 TEMP_ATTR_NAME: Final = "__mypyc_temp__"
 LAMBDA_NAME: Final = "__mypyc_lambda__"
 PROPSET_PREFIX: Final = "__mypyc_setter__"
+# Prefix of hidden attributes that store values of functools.cached_property properties
+PROPCACHE_PREFIX: Final = "__mypyc_cache__"
 SELF_NAME: Final = "__mypyc_self__"
 MYPYC_DEFAULTS_SETUP: Final = "__mypyc_defaults_setup"
 GENERATOR_ATTRIBUTE_PREFIX: Final = "__mypyc_generator_attribute__"

mypyc/ir/class_ir.py

@@ -4,7 +4,7 @@
 
 from typing import NamedTuple
 
-from mypyc.common import PROPSET_PREFIX, JsonDict
+from mypyc.common import PROPCACHE_PREFIX, PROPSET_PREFIX, JsonDict
 from mypyc.ir.func_ir import FuncDecl, FuncIR, FuncSignature, RuntimeArg
 from mypyc.ir.ops import DeserMaps, Value
 from mypyc.ir.rtypes import RInstance, RType, deserialize_type, object_rprimitive
@@ -307,6 +307,10 @@ def has_attr(self, name: str) -> bool:
     def is_deletable(self, name: str) -> bool:
         return any(name in ir.deletable for ir in self.mro)
 
+    def is_cached_property(self, name: str) -> bool:
+        """Is the attribute a functools.cached_property backed by a hidden cache slot?"""
+        return any(PROPCACHE_PREFIX + name in ir.attributes for ir in self.mro)
+
     def is_always_defined(self, name: str) -> bool:
         if self.is_deletable(name):
             return False

mypyc/irbuild/function.py

@@ -29,7 +29,7 @@
     Var,
 )
 from mypy.types import CallableType, Type, UnboundType, get_proper_type
-from mypyc.common import FAST_PREFIX, LAMBDA_NAME, PROPSET_PREFIX, SELF_NAME
+from mypyc.common import FAST_PREFIX, LAMBDA_NAME, PROPCACHE_PREFIX, PROPSET_PREFIX, SELF_NAME
 from mypyc.ir.class_ir import ClassIR, NonExtClassInfo
 from mypyc.ir.func_ir import (
     FUNC_CLASSMETHOD,
@@ -42,10 +42,14 @@
 )
 from mypyc.ir.ops import (
     BasicBlock,
+    Box,
+    Branch,
+    Cast,
     ComparisonOp,
     GetAttr,
     Integer,
     LoadLiteral,
+    Op,
     Register,
     Return,
     SetAttr,
@@ -77,6 +81,7 @@
 )
 from mypyc.irbuild.generator import gen_generator_func, gen_generator_func_body
 from mypyc.irbuild.targets import AssignmentTarget
+from mypyc.irbuild.util import is_cached_property
 from mypyc.primitives.dict_ops import (
     dict_get_method_with_none,
     dict_new_op,
@@ -500,7 +505,19 @@ def handle_ext_method(builder: IRBuilder, cdef: ClassDef, fdef: FuncDef) -> None
             py_setattr_op, [typ, builder.load_str(name), decorated_func], fdef.line
         )
 
+    cached_property = False
     if fdef.is_property:
+        if is_cached_property_class_member(cdef, fdef.name):
+            if class_ir.is_trait:
+                builder.error(
+                    '"functools.cached_property" is unsupported in traits and protocols', fdef.line
+                )
+            else:
+                # Add caching to the getter of a functools.cached_property
+                # (the setter is synthesized below).
+                cached_property = True
+                insert_cached_property_ops(func_ir, PROPCACHE_PREFIX + fdef.name, fdef.line)
+
         # If there is a property setter, it will be processed after the getter,
         # We populate the optional setter field with none for now.
         assert name not in class_ir.properties
@@ -514,6 +531,29 @@ def handle_ext_method(builder: IRBuilder, cdef: ClassDef, fdef: FuncDef) -> None
 
     class_ir.methods[func_ir.decl.name] = func_ir
 
+    if cached_property:
+        # Synthesize the setter of a functools.cached_property. Note that this
+        # must be added to class_ir.methods immediately after the getter, since
+        # the vtable layout assumes that a property setter directly follows the
+        # getter.
+        setter_name = PROPSET_PREFIX + name
+        setter_ir = gen_cached_property_setter_ir(
+            builder, class_ir.method_decls[setter_name], fdef.line
+        )
+        builder.functions.append(setter_ir)
+        class_ir.methods[setter_name] = setter_ir
+        class_ir.properties[name] = (func_ir, setter_ir)
+
+        if class_ir.allow_interpreted_subclasses:
+            # Generate a shadow glue method for the setter so that attribute
+            # assignment dispatches properly for instances of interpreted
+            # subclasses.
+            f = gen_glue_property_setter(
+                builder, setter_ir.sig, setter_ir, class_ir, class_ir, fdef.line
+            )
+            class_ir.glue_methods[(class_ir, setter_name)] = f
+            builder.functions.append(f)
+
     # If this overrides a parent class method with a different type, we need
     # to generate a glue method to mediate between them.
     for base in class_ir.mro[1:]:
@@ -576,7 +616,13 @@ def handle_non_ext_method(
 
     # TODO: Support property setters in non-extension classes
     if fdef.is_property:
-        prop = builder.load_module_attr_by_fullname("builtins.property", fdef.line)
+        if is_cached_property_class_member(cdef, fdef.name):
+            # Non-extension classes have an instance __dict__, so we can use
+            # functools.cached_property directly and get the full interpreted
+            # semantics, including caching.
+            prop = builder.get_module_attr("functools", "cached_property", fdef.line)
+        else:
+            prop = builder.load_module_attr_by_fullname("builtins.property", fdef.line)
         func_reg = builder.py_call(prop, [func_reg], fdef.line)
 
     elif builder.mapper.func_to_decl[fdef].kind == FUNC_CLASSMETHOD:
@@ -1220,3 +1266,87 @@ def gen_property_setter_ir(
     builder.add(Return(builder.none(), line))
     args, _, blocks, ret_type, fn_info = builder.leave()
     return FuncIR(func_decl, args, blocks, line)
+
+
+def is_cached_property_class_member(cdef: ClassDef, name: str) -> bool:
+    """Is the class member with the given name a functools.cached_property?"""
+    sym = cdef.info.names.get(name)
+    return sym is not None and isinstance(sym.node, Decorator) and is_cached_property(sym.node)
+
+
+def insert_cached_property_ops(func_ir: FuncIR, slot: str, line: int) -> None:
+    """Add caching ops to the getter of a functools.cached_property.
+
+    The cached value is stored in a hidden attribute (the cache slot named
+    'slot', declared in the prepare phase). The transformed getter is
+    equivalent to this:
+
+        if is_defined(self.<slot>):
+            return self.<slot>
+        ... original body, with each "return r" replaced by ...
+        self.<slot> = r
+        return r
+
+    Boxed property types are stored in the slot as-is, with NULL marking an
+    undefined (not yet cached) value. Unboxed types (such as int) are stored
+    in a boxed form, since they may not have a dedicated error value.
+    """
+    self_reg = func_ir.arg_regs[0]
+    ret_type = func_ir.decl.sig.ret_type
+
+    # Store the computed value in the cache slot before each return.
+    for block in func_ir.blocks:
+        new_ops: list[Op] = []
+        for op in block.ops:
+            if isinstance(op, Return):
+                value = op.value
+                boxed: Value = value
+                if value.type.is_unboxed:
+                    box = Box(value, op.line)
+                    new_ops.append(box)
+                    boxed = box
+                new_ops.append(SetAttr(self_reg, slot, boxed, op.line))
+            new_ops.append(op)
+        block.ops = new_ops
+
+    # Create a new entry block that returns the value of the cache slot if it
+    # is defined, and otherwise runs the original getter body (which now also
+    # stores the computed value in the cache slot).
+    entry, cache_hit = BasicBlock(), BasicBlock()
+    compute = func_ir.blocks[0]
+    cached = GetAttr(self_reg, slot, line, allow_error_value=True)
+    entry.ops.append(cached)
+    entry.ops.append(Branch(cached, compute, cache_hit, Branch.IS_ERROR))
+    result: Value = cached
+    if ret_type.is_unboxed:
+        result = Unbox(cached, ret_type, line)
+        cache_hit.ops.append(result)
+    elif not is_same_type(ret_type, cached.type):
+        # The property in a subclass may have a narrower type than the
+        # cache slot defined in a base class.
+        result = Cast(cached, ret_type, line)
+        cache_hit.ops.append(result)
+    cache_hit.ops.append(Return(result, line))
+    func_ir.blocks = [entry, cache_hit, *func_ir.blocks]
+
+
+def gen_cached_property_setter_ir(builder: IRBuilder, func_decl: FuncDecl, line: int) -> FuncIR:
+    """Generate the setter of a functools.cached_property.
+
+    Assigning to a cached property stores the value in the cache slot,
+    similar to functools.cached_property in CPython (where an assignment
+    overrides the cached value through the instance __dict__).
+    """
+    name = func_decl.name
+    builder.enter(name)
+    self_type = func_decl.sig.args[0].type
+    self_reg = builder.add_argument("self", self_type)
+    value_reg = builder.add_argument("value", func_decl.sig.args[1].type)
+    assert name.startswith(PROPSET_PREFIX)
+    slot = PROPCACHE_PREFIX + name[len(PROPSET_PREFIX) :]
+    assert isinstance(self_type, RInstance), self_type
+    slot_type = self_type.class_ir.attr_type(slot)
+    builder.add(SetAttr(self_reg, slot, builder.coerce(value_reg, slot_type, line), line))
+    builder.add(Return(builder.none(), line))
+    args, _, blocks, ret_type, fn_info = builder.leave()
+    return FuncIR(func_decl, args, blocks, line)

mypyc/irbuild/prepare.py

@@ -43,6 +43,7 @@
 from mypyc.common import (
     FAST_PREFIX,
     MYPYC_DEFAULTS_SETUP,
+    PROPCACHE_PREFIX,
     PROPSET_PREFIX,
     SELF_NAME,
     get_id_from_name,
@@ -75,6 +76,7 @@
     default_attr_name,
     get_func_def,
     get_mypyc_attrs,
+    is_cached_property,
     is_dataclass,
     is_extension_class,
     is_trait,
@@ -326,6 +328,57 @@ def prepare_method_def(
             assert node.func.type, f"Expected return type annotation for property '{node.name}'"
             decl.is_prop_getter = True
             ir.property_types[node.name] = decl.sig.ret_type
+            if ir.is_ext_class and not ir.is_trait and is_cached_property(node):
+                prepare_cached_property(ir, module_name, cdef, mapper, node, decl)
+
+
+def prepare_cached_property(
+    ir: ClassIR,
+    module_name: str,
+    cdef: ClassDef,
+    mapper: Mapper,
+    node: Decorator,
+    getter_decl: FuncDecl,
+) -> None:
+    """Set up declarations for a functools.cached_property in a native class.
+
+    The cached value is stored in a hidden attribute (the "cache slot").
+    The property getter returns the value of the slot if it is defined, and
+    otherwise runs the decorated function and stores the result in the slot
+    (see handle_ext_method). Assigning to the property stores the assigned
+    value directly in the slot via a synthesized setter (the setter IR is
+    generated in transform_class_def).
+    """
+    name = node.name
+    ret_type = getter_decl.sig.ret_type
+    # If a base class already defines this cached property, reuse its cache
+    # slot. Both properties then share the cached value, similar to how
+    # functools.cached_property instances share an instance __dict__ entry.
+    if not is_inherited_cached_property(cdef, name, mapper):
+        # For unboxed property types use a boxed slot, so that an undefined
+        # cache slot is always represented by NULL.
+        slot_type = object_rprimitive if ret_type.is_unboxed else ret_type
+        ir.attributes[PROPCACHE_PREFIX + name] = slot_type
+    sig = FuncSignature(
+        (getter_decl.sig.args[0], RuntimeArg("value", ret_type, pos_only=True)), none_rprimitive
+    )
+    setter_decl = FuncDecl(PROPSET_PREFIX + name, cdef.name, module_name, sig, is_prop_setter=True)
+    ir.method_decls[PROPSET_PREFIX + name] = setter_decl
+
+
+def is_inherited_cached_property(cdef: ClassDef, name: str, mapper: Mapper) -> bool:
+    """Does a native base class already define a cached property with this name?"""
+    for base in cdef.info.mro[1:]:
+        base_ir = mapper.type_to_ir.get(base)
+        if base_ir is not None and base_ir.is_ext_class:
+            sym = base.names.get(name)
+            if (
+                sym is not None
+                and isinstance(sym.node, Decorator)
+                and is_cached_property(sym.node)
+            ):
+                return True
+    return False
 
 
 def prepare_fast_path(

mypyc/irbuild/statement.py

@@ -1227,7 +1227,15 @@ def transform_del_item(builder: IRBuilder, target: AssignmentTarget, line: int)
     elif isinstance(target, AssignmentTargetAttr):
         if isinstance(target.obj_type, RInstance):
             cl = target.obj_type.class_ir
-            if not cl.is_deletable(target.attr):
+            # Deleting a functools.cached_property is supported: it clears the
+            # cached value (the property descriptor handles the deletion).
+            # Attributes of non-extension classes can always be deleted, since
+            # instances have an ordinary __dict__.
+            if (
+                cl.is_ext_class
+                and not cl.is_deletable(target.attr)
+                and not cl.is_cached_property(target.attr)
+            ):
                 builder.error(f'"{target.attr}" cannot be deleted', line)
                 builder.note(
                     'Using "__deletable__ = '

mypyc/irbuild/targets.py

@@ -45,7 +45,11 @@ def __init__(self, obj: Value, attr: str, can_borrow: bool = False) -> None:
         self.obj = obj
         self.attr = attr
         self.can_borrow = can_borrow
-        if isinstance(obj.type, RInstance) and obj.type.class_ir.has_attr(attr):
+        if (
+            isinstance(obj.type, RInstance)
+            and obj.type.class_ir.is_ext_class
+            and obj.type.class_ir.has_attr(attr)
+        ):
             # Native attribute reference
             self.obj_type: RType = obj.type
             self.type = obj.type.attr_type(attr)

mypyc/irbuild/util.py

@@ -65,6 +65,23 @@ def is_trait_decorator(d: Expression) -> bool:
     return isinstance(d, RefExpr) and d.fullname == "mypy_extensions.trait"
 
 
+def is_cached_property(node: Decorator) -> bool:
+    """Is the decorated function a functools.cached_property?
+
+    The semantic analyzer removes the cached_property decorator from
+    Decorator.decorators (it only marks the function as a settable
+    property), so we need to look at the original decorators. Ignore
+    properties that have additional decorators.
+    """
+    return (
+        node.func.is_property
+        and not node.decorators
+        and any(
+            refers_to_fullname(d, "functools.cached_property") for d in node.original_decorators
+        )
+    )
+
+
 def is_trait(cdef: ClassDef) -> bool:
     return any(is_trait_decorator(d) for d in cdef.decorators) or cdef.info.is_protocol