Calling help() on a dataclass shows dataclass internal names instead of type names in 3.14 or later

[DavidCEllis]

Bug report

Bug description:

If you call help on a dataclass in Python 3.14 or later it shows the internal type names used for the exec call in the signature.

Docstring included to hide the dataclasses generated __doc__ which would just confuse things.

from dataclasses import dataclass

@dataclass
class Example:
    "docstring"
    x: int

help(Example)

Before, on 3.13

Help on class Example in module __main__:

class Example(builtins.object)
 |  Example(x: int) -> None
 |
 |  docstring
 |
 |  Methods defined here:
 |
 |  __eq__(self, other)
 |      Return self==value.
 |
 |  __init__(self, x: int) -> None
 |      Initialize self.  See help(type(self)) for accurate signature.
...

Now, on 3.14 or later

Help on class Example in module __main__:

class Example(builtins.object)
 |  Example(x: __dataclass_type_x__) -> __dataclass___init___return_type__
 |
 |  docstring
 |
 |  Methods defined here:
 |
 |  __eq__(self, other)
 |      Return self==value.
 |
 |  __init__(self, x: __dataclass_type_x__) -> __dataclass___init___return_type__
 |      Initialize self.  See help(type(self)) for accurate signature.
...

This looks a bit messy and reveals inner details that users of help probably don't need to see.

It looks like this comes from inspect.signature(cls, annotation_format=Format.STRING) being used in pydoc, but I think it's a dataclasses issue.

attrs doesn't suffer the same fate as it attaches annotations as __annotations__ instead of defining them in the source code string to be evaluated.

Inspired by that, for my own dataclass-like implementation for 3.14+ I'm collecting the annotations and generating an __annotate__ function which appears to solve this issue: see here

dataclasses could potentially do something similar.

CPython versions tested on:

3.14, CPython main branch

Operating systems tested on:

No response

Linked PRs

• gh-137530: generate an __annotate__ function for dataclasses __init__ #137711
• [3.14] gh-137530: generate an __annotate__ function for dataclasses __init__ (GH-137711) #141352

[ZeroIntensity]

This is a 3.14 regression, so I've marked it as a blocker for now. This doesn't look like something that can easily be fixed, but we should come to a decision before 3.14.0.

[sobolevn]

Idea: we can at least define a table with translation. Something like:

class Example(builtins.object)
 |  Example(x: __dataclass_type_x__) -> __dataclass___init___return_type__
 |
 |  docstring
 |
 |  Internal magic names:
 |     __dataclass___init___return_type__ -> None
 |     __dataclass_type_x__ -> int
 |
 |  Methods defined here:
 |
 |  __eq__(self, other)
 |      Return self==value.
 |
 |  __init__(self, x: __dataclass_type_x__) -> __dataclass___init___return_type__
 |      Initialize self.  See help(type(self)) for accurate signature.

What do you think?

CC @JelleZijlstra

[JelleZijlstra]

That's unfortunate, thanks for noticing!

I think we should fix this but it doesn't seem critical for 3.14.0 since it's not runtime behavior; it can wait for 3.14.1.

I don't think @sobolevn's translation table is a great solution; ideally the internal names shouldn't bleed to users at all. Maybe we can attach a custom __annotate__ function that outputs nicer STRING format outputs?

[sobolevn]

Ok, I will try this out: custom __annotate__ seems like an interesting idea.

[DavidCEllis]

The issue is caused by get_annotations with Format.STRING attempting to get the text from the source code and in this case succeeding, but the output is not what you actually want users to see.

These values are specifically from the generated __init__ function.

It may be worth noting that if you have a forward reference in your dataclass annotations, this will also appear in __annotations__ (and get_annotations with format.VALUE).

from dataclasses import dataclass
from annotationlib import get_annotations, Format

@dataclass
class Example:
    x: undefined

print(get_annotations(Example.__init__, format=Format.STRING))
# {'x': '__dataclass_type_x__', 'return': '__dataclass___init___return_type__'}

print(Example.__init__.__annotations__)
# {'x': ForwardRef('undefined', is_class=True, owner=<class '__main__.Example'>), 'return': None}

Maybe we can attach a custom annotate function that outputs nicer STRING format outputs?

As linked earlier, this is what I currently have for my own implementation in ducktools-classbuilder

from annotationlib import Format, ForwardRef, type_repr

def make_annotate_function(annos):
    # Construct an annotation function from __annotations__
    def annotate_func(format):
        match format:
            case Format.VALUE | Format.FORWARDREF:
                return {
                    k: v.evaluate(format=format)
                    if isinstance(v, ForwardRef) else v
                    for k, v in annos.items()
                }
            case Format.STRING:
                string_annos = {}
                for k, v in annos.items():
                    if isinstance(v, str):
                        string_annos[k] = v
                    elif isinstance(v, ForwardRef):
                        string_annos[k] = v.evaluate(format=Format.STRING)
                    else:
                        string_annos[k] = type_repr(v)
                return string_annos
            case _:
                raise NotImplementedError(format)
    return annotate_func

Where annos would be {f.name: f.type for f in fields} with the resulting function attached to the __init__ method.

Edit: Along with "return": None included in the annotation dict
Edit 2: And possibly with some extra filtering for f.init.

[hugovk]

I think we should fix this but it doesn't seem critical for 3.14.0 since it's not runtime behavior; it can wait for 3.14.1.

Agreed, let's wait for 3.14.1 and move to deferred-blocker.