What breaks when a Python class decorator returns a wrapper function instead of the class?

**The desugaring is the whole story.** Writing ```python @deco class C: ... ``` is exactly the same as writing ```python class C: ... C = deco(C) ``` The class body executes first and a real class object is built by the metaclass; only then is the callable applied and the *name* `C` rebound to its return value. Nothing in the language checks that the return value is a class. A decorator that forgets its `return` binds `C` to `None`; one that returns a nested wrapper function binds `C` to a function; one that returns a proxy instance binds `C` to an ordinary object. The instances the class produces are untouched — their `type` is still the original class — but every use of the *name* now goes through something that is not a type. **What breaks, and why** *Type tests.* `isinstance(obj, C)` and `issubclass(D, C)` require the second argument to be a type, a tuple of types or a union. Handed a function they raise `TypeError`; they do not return `False`. This surprises people because `obj` really is an instance of the original class — the argument that is wrong is the second one. *Subclassing.* `class D(C): ...` derives the metaclass from the bases by calling `type(C)`. When `C` is a function, Python tries to call `function(...)` with the name, bases and namespace, and raises `TypeError`. A library whose classes are meant to be extended cannot be decorated this way at all. *Class-level access.* Constants, `classmethod` alternate constructors and `staticmethod` helpers reached through the name — `C.from_json(...)`, `C.DEFAULT` — raise `AttributeError`, because the function does not carry the class's namespace. Copying metadata with `functools.wraps` fixes `__name__` and `__doc__` and helps not at all: the object is still a function. *Explicit `super`.* Zero-argument `super()` inside the original methods still resolves. The compiler stores the defining class in a `__class__` closure cell created by the class body, and rebinding a module global does not touch that cell. But an explicit `super(C, self)` written anywhere reads the *name*, gets a function, and raises `TypeError`. That asymmetry is worth being able to state. *Pickling.* `pickle` serializes an instance by recording the class's `__module__` and `__qualname__`, then, at dump time, importing that path and checking that the object found there **is** the class being pickled. With the name rebound, the lookup returns the wrapper, the identity check fails, and `pickle.dumps` raises `PicklingError` before any instance state is written. This is the failure that reaches production latest, because it only appears when instances cross a process boundary — a process pool, a cache, an on-disk snapshot. Note that `copy.deepcopy` still works: it drives the same reduce protocol but never looks the class up by name. *Typing and introspection.* A static type checker follows the decorator's declared return type; a decorator annotated as returning a plain callable erases the class from the checker's view, so attribute access through the name stops being verified. Anything that walks `__mro__`, or generates documentation from a type, degrades the same way. **The safe patterns** 1. **Mutate and return the same object.** Add attributes and methods to `cls`, then `return cls`. Identity is preserved, so none of the failures above can happen. This is what the standard library's own class decorators do — `dataclasses.dataclass` hands back the very class it was given, with `slots=True` as the documented exception, where it must build a new class. 2. **Return a genuine subclass.** `type(cls.__name__, (cls,), namespace)` keeps the name bound to a class, so type tests, subclassing and class-attribute access all behave. Copy `__qualname__` and `__module__` from the original so `pickle` resolves the name to the new class, and remember that identity is still not preserved: instances built by code holding the undecorated class are not instances of the subclass, and a registry keyed by class object will see two distinct keys. 3. **Do not use a class decorator at all** when what you actually want is to intercept construction or wrap behaviour. Override `__new__` or `__init__`, wrap individual methods, or expose a separate factory function under its own name and leave the class name bound to a class. **Spotting it in review.** The tell is a class decorator whose body defines a nested `def` and returns it, or one that returns nothing because the author forgot the `return` on the last line. A single assertion at the end of the decorator — that the result is an instance of `type` — or simply annotating the decorator as taking and returning `type[T]` catches both before they ship, and costs nothing at runtime.