pep 681 is ambiguous in terms of dataclass_transform decorator applied to an overload

[zzzeek]

from the spec

If dataclass_transform is applied to a function, using the decorated function as a decorator is assumed to apply dataclass-like semantics. If the function has overloads, the dataclass_transform decorator can be applied to the implementation of the function or any one, but not more than one, of the overloads.

From reading the above, both myself and a co-developer were led to believe this indicated that a specific overload of a decorator function can enable dataclass_transforms, independently of other function overloads. However this does not seem to be the case at least with pyright.

pyright/pylance's behavior seems to be that the @dataclass_transform decorator must be applied to the first mention of a function and that mention only, whether it's an overload or just the function implementation. the dataclass_transform then applies to all occurrences of the function.

I'm really not sure if im doing this right or what the intent was, so the script below shows what I can see, if someone can check my work on this, thanks

from typing import Callable
from typing import overload
from typing import Type
from typing import TypeVar

from typing_extensions import dataclass_transform
from typing_extensions import Literal

_T = TypeVar("_T")



# #### case 1 #####
# dataclass transform applied to the first of two overloads.
# result: dataclass_transform takes effect for all variants of the decorator.
# we would have hoped this instead meant it takes place just for the first
# overload but spec is ambiguous

@dataclass_transform()
@overload
def create_model_first_overload(
    dataclass_semantics: Literal[True],
) -> Callable[[Type[_T]], Type[_T]]:
    ...


@overload
def create_model_first_overload(
    dataclass_semantics: Literal[False],
) -> Callable[[Type[_T]], Type[_T]]:
    ...


def create_model_first_overload(
    dataclass_semantics: bool,
) -> Callable[[Type[_T]], Type[_T]]:
    def wrap(cls):
        return cls
    return wrap


@create_model_first_overload(dataclass_semantics=True)
class FirstOverloadModelOne:
    id: int
    name: str


@create_model_first_overload(dataclass_semantics=False)
class FirstOverloadModelTwo:
    id: int
    name: str

# both pass.  The spec is ambiguous if the second should pass or not
FirstOverloadModelOne(5, "some name")


FirstOverloadModelTwo(5, "some name")



# #### case 2 #####
# dataclass transform applied to the second overload
# result: dataclass_transform takes effect for no variants of the decorator.
# this seems to contradict the spec.

@overload
def create_model_second_overload(
    dataclass_semantics: Literal[False],
) -> Callable[[Type[_T]], Type[_T]]:
    ...


@dataclass_transform()
@overload
def create_model_second_overload(
    dataclass_semantics: Literal[True],
) -> Callable[[Type[_T]], Type[_T]]:
    ...


def create_model_second_overload(
    dataclass_semantics: bool,
) -> Callable[[Type[_T]], Type[_T]]:
    def wrap(cls):
        return cls
    return wrap


@create_model_second_overload(dataclass_semantics=True)
class SecondOverloadModelOne:
    id: int
    name: str


@create_model_second_overload(dataclass_semantics=False)
class SecondOverloadModelTwo:
    id: int
    name: str

# both fail.  this contradicts the spec which says @dataclass_transform()
# can be on any overload
SecondOverloadModelOne(5, "some name")


SecondOverloadModelTwo(5, "some name")

output for pyright:

  /home/classic/dev/sqlalchemy/test3.py:102:1 - error: Expected no arguments to "SecondOverloadModelOne" constructor (reportGeneralTypeIssues)
  /home/classic/dev/sqlalchemy/test3.py:105:1 - error: Expected no arguments to "SecondOverloadModelTwo" constructor (reportGeneralTypeIssues)
2 errors, 0 warnings, 0 informations 

[erictraut]

@zzzeek, your second example should type check fine. This was a simple bug in pyright. It will be fixed in the next release.

[debonte]

PEP 681 says:

If the function has overloads, the dataclass_transform decorator can be applied to the implementation of the function or any one, but not more than one, of the overloads.

and also:

If multiple dataclass_transform decorators are found, either on a single function (including its overloads), a single class, or within a class hierarchy, the resulting behavior is undefined. Library authors should avoid these scenarios.

Is this not clear?

[zzzeek]

@debonte see my example at the top. There is only a single @dataclass_transform decorator, so this is not described by the "if multiple dataclass_transform decorators are found..." language.

in my example at the top, the intent should be clear that it wants "dataclass_transform" behaviors to apply only when the "dataclass_semantics=True" parameter is passed. It's fine that this is not part of the spec but the language mentioned in my opinion does not make this clear.

[debonte]

Ok. @JelleZijlstra, can I make a small change in PEP 681 to make this more clear?

At the end of this paragraph:

If dataclass_transform is applied to a function, using the decorated function as a decorator is assumed to apply dataclass-like semantics. If the function has overloads, the dataclass_transform decorator can be applied to the implementation of the function or any one, but not more than one, of the overloads.

I'm thinking of adding something like this:

When applied to an overload, the dataclass_transform decorator still impacts all usage of the function.

[JelleZijlstra]

Yes, that should be fine.

[debonte]

python/peps#2610

[gvanrossum]

From reading the above, both myself and a co-developer were led to believe this indicated that a specific overload of a decorator function can enable dataclass_transforms, independently of other function overloads. However this does not seem to be the case at least with pyright.

It doesn't look like what you want was intended -- surely if the intention was to allow a specific overload to be affected there wouldn't be a restriction on decorating at most one overload. So I think the proposed clarification in the PEP text is the way to go.

[zzzeek]

I can see from your comments in python/peps#2610 this is causing curiosity, so basically in non-stub Python code we normally have a non-overloaded implementation of the function at the bottom. If the decorator in fact has no intention of taking overloads into account, it is most intuitive, assuming one omits from one's memory that a non-overloaded implementation is not necessary from a typing point of view, that the decorator would be on the non-overloaded function, since "overload" is not taken into account. Hence "it can be on any overload" seems a little strange given that omission from one's memory.