Should stubs contain default values?

[hauntsaninja]

This has come up recently, for similar reasons as #4881 and discussed a little there

From @gramster

an advantage of including default values is that tools like pyright or pylance will use stubs (if available) for the signatures they show to users when hovering over a function call, and users want to see the default values. I'd like to understand your point of view though as to why you would prefer them removed?

I'm overall fine with this, though I'd like to see the following:

• we restrict it to simple literal values (e.g. anything that can go into a Literal)
• we can still use ... at author's discretion (useful in overloads or cases where value doesn't actually matter or to avoid awful x: Literal["x"] = "x" things)
• we update e.g. stubtest to verify stuff

The case for:

• lets IDEs provide more information to users

The case against:

• most things are longer than ... and terseness may be more valuable than the additional information
• it's a thing that needs doing and maintaining
• if we allow complicated default values there are more costs

A similar thing could apply to constants.

[JelleZijlstra]

I agree, a couple of small comments:

• we restrict it to simple literal values (e.g. anything that can go into a Literal)

Other values that we could accept would include floats and types (e.g., for params like dict_factory: Callable[..., ...] = dict).

• we can still use ... at author's discretion (useful in overloads or cases where value doesn't actually matter or to avoid awful x: Literal["x"] = "x" things)
• we update e.g. stubtest to verify stuff

It should be easy for stubtest to check defaults for correctness on Python functions (it's in the signature). For C functions, it's not necessarily possible to infer the default though, and indeed there may not be a default in a useful sense.

What other tools would need updating? I think we'd have to change flake8-pyi and hopefully nothing else.

[srittau]

It would be useful - but not necessary - to update stubgen as well.

[AlexWaygood]

I like the idea of adding simple default values to stubs. I agree that it's very useful in IDEs, and I think it'll be easier to maintain than adding docstrings to stubs.

The = ... convention that we currently use is nice because it keeps stubs as concise as possible. But... it looks really weird to people who aren't used to it. I think it's nice for stubs to use the same syntax and conventions as normal Python wherever possible, and I remember finding the = ...s everywhere really strange and alien when I first started reading through typeshed's stubs as a new contributor.

What other tools would need updating? I think we'd have to change flake8-pyi and hopefully nothing else.

Pyright also has a lint that enforces only using ... as a default in stub files (ironically, since it's one of the IDEs that would benefit most from this change). We might be able to easily switch that off in our pyrightconfig file -- I'm not sure if it's bundled together with other stub-related lints or if it's a dedicated error code.

[sobolevn]

I have some concerns about it.

First of all, this will require more branching just for the sake of default values if it is different for different python versions.

Or we can show incorrect default values for this specific python version.

Secondly, default values are not a part of the signature. So, they can be changed in bugfix releases. It will make it much harder to maintain.

Next, stubs are even harder to maintain with default values.

Moreover, there are quite ugly defaults values like _sentinel = object() or others. Not sure we want this.

I think that IDEs can just use inspect to get the function and its defaults. It is much easier and it will always show correct results.

[AlexWaygood]

Moreover, there are quite ugly defaults values like _sentinel = object() or others. Not sure we want this.

I like @hauntsaninja's idea of only including "simple" defaults, e.g. "anything that's valid to go in a Literal slice". We can continue to use ... for ugly or complex defaults.

[srittau]

I'll honestly expect 95% of all default values to be None anyway.

[JelleZijlstra]

First of all, this will require more branching just for the sake of default values if it is different for different python versions.

That will happen sometimes, but my sense is that it's not common.

Secondly, default values are not a part of the signature. So, they can be changed in bugfix releases. It will make it much harder to maintain.

In theory, sure, but I'd be surprised if that happens with any frequency.

If maintainability concerns like these do come up frequently, we can revisit our decision, but I'd be surprised if it is a major issue. The stdlib doesn't change its defaults that much, and for third-party libraries we only support one version at a time.

[gramster]

I think that IDEs can just use inspect to get the function and its defaults. It is much easier and it will always show correct results. Easy in Jupyter with a running kernel; not as simple as it sounds in other IDEs that may not be written in Python, need to be responsive, and don't want to do a bunch of indexing up front.

…

On Thu, Oct 27, 2022 at 8:22 AM Jelle Zijlstra ***@***.***> wrote: First of all, this will require more branching just for the sake of default values if it is different for different python versions. That will happen sometimes, but my sense is that it's not common. Secondly, default values are not a part of the signature. So, they can be changed in bugfix releases. It will make it much harder to maintain. In theory, sure, but I'd be surprised if that happens with any frequency. If maintainability concerns like these do come up frequently, we can revisit our decision, but I'd be surprised if it is a major issue. The stdlib doesn't change its defaults that much, and for third-party libraries we only support one version at a time. — Reply to this email directly, view it on GitHub <#8988 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAVCPCAEIXNELUUVHAVZ2WLWFKM47ANCNFSM6AAAAAAROQJKTU> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[jpe]

IDEs will also probably want docstrings.

[JelleZijlstra]

Docstrings provide significantly more maintainability challenges. It's worth discussing whether it's worth changing our stance on docstrings too, but let's do that in a separate issue.

[AlexWaygood]

IDEs will also probably want docstrings.

Please don't discuss docstrings here. We have the following issue for that discussion:

• Should stubs contain docstrings? #4881

[jpe]

Docstrings are relevant here because unless docstrings are also included, I think there's little benefit in including default values for IDEs. Those that want both will continue to need to merge signatures from .pyi, .py, and other files. I suspect that some might ignore default values from .pyi files because those from the .py file are probably more up to date. It would probably be a win for C implemented modules, though.

[Avasam]

As a user of both libraries typed through Typeshed and inline-typed ones, I've noticed that's information lost in these third-party stubs, which is unfortunate. I really like when my IDE shows me default values of function parameters.

A similar thing could apply to constants.

I share the same feeling for constants. (Relates to #7258 ?)

Similarly to my comment here (#4881 (comment)) and as gramster mentionned: Is this something editors could inspect when they come across =... ? (ie: fallback to the source python code, if available).

What's a good compromise between maintainability and not hiding information that would otherwise be available?

On the idea of only doing it for simple types: stubtest could help validate and maintain accuracy. By knowing when a default is both known and considered "simple".