Add a setfunc decorator for attaching functions to an existing class or object

[Natuworkguy]

The idea

A three-line decorator factory that assigns the decorated function onto an existing
object under the function's own name:

from typing import Callable

def setfunc(obj: object) -> Callable[[Callable], None]:
    def _setfunc(func: Callable) -> None:
        setattr(obj, func.__name__, func)
    return _setfunc

Usage:

class MyClass: ...

@setfunc(MyClass)
def func(self: MyClass) -> None:
    print("func called")

MyClass().func()   # func called

The appeal is that the definition reads like a normal def, with signature,
annotations, decorators and docstring all in the usual places, instead of the flatter
setattr(MyClass, "func", func) tacked on afterwards, or a MyClass.func = func
assignment that sits visually far from the body it names.

I'd like to know whether there is appetite for something like this in functools
(where decorators live) or types (where the object-model helpers live), or whether
this is firmly PyPI/recipe territory.

Motivation

Cases where the class body isn't available or isn't the right place:

• Attaching optional methods conditionally: a debug/tracing method added only when a
  flag is set, or a backend-specific implementation chosen at import time.
• Plugin systems where third-party code extends a host class.
• Splitting a very large class across modules without multiple inheritance or mixins.
• Test helpers and REPL/notebook work, where you want to grow a class incrementally.

Other languages carve out dedicated syntax for the general shape (C# extension
methods, Kotlin extension functions, Swift extension, Ruby's open classes and
refinements), so the underlying need isn't unusual. Python can already do it; the
question is only whether the spelling is worth standardising.

Prior art / what exists today

• setattr(MyClass, "func", func): already one line, already explicit.
• MyClass.func = func: same thing, fewer strings.
• functools.singledispatch(...).register is a stdlib decorator with a closely related
  shape (decorate a function, register it against a type, keep the definition readable),
  though it populates a dispatch table rather than mutating the class.
• unittest.mock.patch.object and pytest's monkeypatch.setattr cover the
  temporary/test-scoped version of this.
• Several PyPI packages ship a decorator like this one; forbiddenfruit goes further
  and patches built-in types through the C API.

This has also come up before on this forum under the heading of "extension methods",
and the def obj.method(): ... syntax that the comment in my original snippet gestures
at is a much larger proposal than the decorator itself. I'm deliberately scoping this to
the library-level helper. (If someone can link the earlier threads, I'll edit them in.)

Known problems

I'd rather list these myself than have them listed for me. Measured on CPython 3.14.7:

1. Static analysis breaks. This is the big one. Both mypy and pyright reject the
   usage example:

   error: "MyClass" has no attribute "func"  [attr-defined]        (mypy)
   error: Cannot access attribute "func" for class "MyClass"       (pyright)
   

   There is no way in the type system today to express "this decorator injects a member
   into that class." typing.dataclass_transform is a precedent for teaching checkers
   about a decorator's effects, but nothing analogous exists here. Blessing a pattern in
   the stdlib that every type checker flags seems like a hard sell, and realistically
   this idea needs a typing story before it needs a functools slot.

2. Zero-argument super() has no __class__ cell. A function compiled outside a
   class body never gets one, so out of the box:

   RuntimeError: super(): __class__ cell not found
   

   This one is fixable from the decorator, but only by rebuilding the code object:
   append __class__ to co_freevars, prepend the COPY_FREE_VARS instruction the
   prologue is missing, shift co_exceptiontable and co_linetable by one code unit
   to match, rewrite any LOAD_GLOBAL __class__ into a LOAD_DEREF, then rebuild the
   function with an extra closure cell. I have that working on 3.14 across generators,
   coroutines, pre-existing closures, try/except bodies and multi-level MROs, with
   tracebacks and co_lines() intact.

   I think this cuts in favour of the proposal rather than against it. Anyone who wants
   this pattern today either performs bytecode surgery or tells users to write
   super(MyClass, self) by hand. Inside CPython neither is necessary, since the cell
   can simply be set. A helper that can only be implemented correctly in userland by
   rewriting bytecode is a reasonable candidate for living where the bytecode is
   defined.

3. __qualname__ is wrong. It stays func, not MyClass.func, so repr(),
   tracebacks and pickle see the unattached name.

4. __set_name__ is never called, because setattr after class creation doesn't
   run it. Descriptors attached this way behave differently from ones in the class body.

5. Built-in and extension types are rejected with TypeError: cannot set '...' attribute of immutable type 'int', which rules out the use case people most often
   want extension methods for.

6. Lambdas silently attach as <lambda>, since the name comes from __name__.

7. Instances don't get a bound method. setfunc(instance) stores a plain function,
   so self is not passed and the call raises TypeError: missing 1 required positional argument. Doing it correctly needs types.MethodType.

8. Returning None rebinds the module-level name to None. That keeps the
   namespace tidy in one sense, but it means decorators can't be stacked above it, and
   linters see a name assigned to None and then never used.

If it were to go in, what should it look like?

Points 3, 6, 7 and 8 are fixable in the helper:

def setfunc(obj, name=None):
    def deco(func):
        attr = name or func.__name__
        if attr == "<lambda>":
            raise ValueError("lambda needs an explicit name")
        func.__qualname__ = f"{obj.__qualname__}.{attr}"   # when obj is a class
        setattr(obj, attr, func)
        return func                                        # stackable, no None
    return deco

That is, an explicit name= override, a __qualname__ fixup, binding via
types.MethodType when the target is an instance, and returning the function
unchanged. Point 2 is reachable only through code object surgery, as described above.
Points 1, 4 and 5 are not fixable at this level at all.

What I'm asking

1. Is the readability win over MyClass.func = func large enough to clear the stdlib
   bar for a three-line helper?
2. Is there any path to making a checker understand attribute injection, or does that
   sink it outright?
3. Does the super() argument move anyone? A stdlib implementation gets the
   __class__ cell for free, which no third-party version can say.
4. If this belongs on PyPI instead, is that the consensus, and is the answer different
   if the typing gap is closed first?

[srittau]

This is unrelated to Python typing and would better be suggested at discuss.python.org.