functools.wraps Not Preserving Docstrings in Decorated Functions

[Harteg]

When using functools.wraps to decorate functions, Pylance does not show the docstring and related metadata for the wrapped function. However, typing func.doc does return the correct docstring, suggesting that the docstring is preserved internally but not displayed in Pylance.

Code Example to Reproduce:

from functools import wraps
from typing import Any

def foo(a):
    """This is the docstring"""
    return a + 1

@wraps(foo)
def func(*args, **kwargs):
    return foo(*args, **kwargs)

func(1) # does not display docstring with auto-suggestion

# However, typing `func.__doc__` works:
print(func.__doc__)  # Outputs: "This is the docstring"

Expected Behavior
Pylance should show the docstring "This is the docstring" for func when hovering over it or using IntelliSense, as it is internally preserved and accessible via func.doc.

Actual Behavior
The docstring from foo is not displayed for func in Pylance.

Specifying explicit types as suggested in #4140 does not help:

Copy code
from functools import wraps
from typing import Any

def foo(a: int) -> int:
    """This is the docstring"""
    return a + 1

@wraps(foo)
def func(*args: Any, **kwargs: Any) -> int:
    return foo(*args, **kwargs)

func(1)  # Docstring not shown

Environment
Pylance Version: v2024.11.1
Python plugin version: v2024.18.0
Python Version: 3.12.6
VS Code Version: 1.95.1
Operating System: MacOS 15.1

[StellaHuang95]

Thanks for reaching out. This is because Pylance focuses on static analysis rather than runtime evaluation. Although functools.wraps sets __doc__ and other attributes dynamically, Pylance doesn’t fully interpret this during static analysis. This was covered in the discussion at #2716. Feel free to upvote if you'd like to see it being supported.

We might be able to special case this situation and use the docstring from the wrapped function instead if the decorator is functools.wrapper. Tagging @erictraut to get his thoughts on this as well.