[issue38333] add type signatures to library function docs

Guido van Rossum added the comment: Since this discussion went down in flames quickly, I'm closing it. Another issue can be opened once someone has a concrete design of what this should look like in the formatted docs, an example that does this for a few libraries, and a prototype of a tool

[issue38333] add type signatures to library function docs

Change by Guido van Rossum : -- resolution: -> postponed stage: -> resolved status: open -> closed ___ Python tracker ___ ___

[issue38333] add type signatures to library function docs

Vedran Čačić added the comment: https://www.python.org/dev/peps/pep-0484/#non-goals I really have nothing more to say. -- ___ Python tracker ___

[issue38333] add type signatures to library function docs

paul rubin added the comment: I don't think we're going to accomplish anything continuing the eternal static-vs-dynamic debate, which in Python's case has already been resolved by adding optional static typing. It's a done deal, and the issue here is just how to document it. Erlang (via

[issue38333] add type signatures to library function docs

Vedran Čačić added the comment: Your arguments in my view boil down to "Haskell is a nice language" and "Static typing is useful". It still doesn't change my argument that Python is genetically neither of these. And we will cripple it greatly if we try to push it in that direction. [Your

[issue38333] add type signatures to library function docs

paul rubin added the comment: At first glance, having a typeclass for each protocol (at least the widely used ones) seems fine. It's inherent in Haskell and a lot of libraries are organized around a common set of typeclasses--look up "Typeclassopedia" for descriptions of them. Certainly

[issue38333] add type signatures to library function docs

Vedran Čačić added the comment: Well, yes, if you're going to invent a special typeclass for every protocol, then you can document any signature. But what purpose does it serve? Abs to me seems like a hack, not something we really wanted to capture with the type system. Do you find (x :

[issue38333] add type signatures to library function docs

paul rubin added the comment: abs takes any value that understands the __abs__ method and returns something of the same type. In fact there is already a type protocol for it: https://mypy.readthedocs.io/en/stable/protocols.html#supportsabs-t So abs's signature would be (x : Abs[T]) -> T

[issue38333] add type signatures to library function docs

Vedran Čačić added the comment: In that case, I'm pretty sure you'd never be able to document almost _any_ function signature. Python is simply not a statically typed language, and we love it because of that. Ok, go to the list of builtins, and start alphabetically. First is abs. What type

[issue38333] add type signatures to library function docs

Guido van Rossum added the comment: @phr To be clear, I agree that there's nothing wrong with adding signatures to docs. We just need to find a way to do it. There will definitely be some cases where it's better not to have a type rather than trying to spell out the actual type in the

[issue38333] add type signatures to library function docs

paul rubin added the comment: Yes, the suggestion was just for the docs, and since those are intended for human rather than machine consumption, it's fine if there are some blurry cases where there is no signature. Ideally in those cases, the issue should be explained in the doc text. I

[issue38333] add type signatures to library function docs

Guido van Rossum added the comment: I'm sorry, but that's unacceptable. On Mon, Sep 30, 2019 at 23:42 Vedran Čačić wrote: > > Vedran Čačić added the comment: > > > Many docs are ... vague about types. > > ... and I consider that a feature. At least if you do that, make an > explicit

[issue38333] add type signatures to library function docs

Vedran Čačić added the comment: > Many docs are ... vague about types. ... and I consider that a feature. At least if you do that, make an explicit decision not to introduce TypeErrors for "disagreeing with the documented signature". For example, I'd be ok with sum being documented as

[issue38333] add type signatures to library function docs

Guido van Rossum added the comment: Even if this not desirable for the source code, it still makes sense to add the types to the docs, at least when they are simple and compact. The proposed notation from PEP 604 ('|' for unions) might help with compactness. Many docs are unnecessarily

[issue38333] add type signatures to library function docs

Change by Raymond Hettinger : -- assignee: docs@python -> gvanrossum nosy: +gvanrossum ___ Python tracker ___ ___ Python-bugs-list

[issue38333] add type signatures to library function docs

Raymond Hettinger added the comment: I believe there was an explicit decision not to do this. For the time being, optional typing is still optional. -- nosy: +rhettinger ___ Python tracker

[issue38333] add type signatures to library function docs

New submission from paul rubin : It would be nice if the library reference manual had type signatures for all the stdlib functions at some point. It might be possible to extract a lot of them automatically from typeshed and semi-automatically paste them into the doc files. It might also be