Add the typing spec #1517
Add the typing spec #1517
Conversation
Copied over from https://github.com/JelleZijlstra/typing-spec The text largely derives from the typing PEPs, though I added some material. The organization is based on an outline by @erictraut. @rchen152 and @Daverball made contributions to the text.
JelleZijlstra
added
the
Typing Council decision
|
@hauntsaninja I agree, but won't have time right now to fix that. As you say, let's leave it for later. |
|
|
||
| (Originally specified in :pep:`702`.) | ||
|
|
||
| The :py:func:`warnings.deprecated` |
There was a problem hiding this comment.
| The :py:func:`warnings.deprecated` | |
| The :class:`warnings.deprecated` |
As this is now implemented as a class?
There was a problem hiding this comment.
It's not documented as a class: https://docs.python.org/3.13/library/warnings.html#warnings.deprecated
There was a problem hiding this comment.
Ah yes makes sense, it isn't auto-generated docs
docs/spec/Makefile
Outdated
| @@ -0,0 +1,20 @@ | |||
| # Minimal makefile for Sphinx documentation | |||
There was a problem hiding this comment.
Why is this here? I went into this directory and typed make venv but it complained about a missing conf.py.
There was a problem hiding this comment.
Oops, probably a holdover from when it was in its own repo. I'll get rid of it. (You should make in the parent directory, which includes this spec and the other typing docs.)
There was a problem hiding this comment.
Yeah, I figured that out eventually. It's a bit weird how clicking on the Table of Contents header at the top of the sidebar takes you to the global ToC, not the Spec ToC, even though there is no "Next topic" linked from spec/historical.html, the last topic in Spec (so I would expect that the ToC link would go to the Spec ToC). But that's a very minor detail at this point, and probably some Sphinx oddity.
| @@ -0,0 +1,95 @@ | |||
| Type system concepts | |||
There was a problem hiding this comment.
This feels like a grab-bag section, and it's oddly placed at the start of the document (why start with unions, when nothing else has been described yet)?
There was a problem hiding this comment.
This comes from Eric's outline in https://discuss.python.org/t/proposed-initial-typing-spec/39389/4, but I omitted the sections for which we don't have any text yet. I'm open to reorganizing this, but we can do that later too.
| @@ -0,0 +1,291 @@ | |||
| .. _historical: | |||
There was a problem hiding this comment.
Maybe add from __future__ import annotations to this page? I was reminded of it in the section about forward references. I think it's within the scope of the typing spec, since it changes semantics: even if you don't use runtime introspection, enabling it changes what gets accepted.
There was a problem hiding this comment.
I'm not sure it does; shouldn't type checkers infer the same types with and without the future import? Obviously the future import affects the runtime behavior, but this spec doesn't need to describe that.
There was a problem hiding this comment.
Huh, I suppose. Does the spec not describe any runtime behavior?
There was a problem hiding this comment.
It does in a few cases, but in principle I think it shouldn't. docs.python.org describes how Python the language works; this spec should only describe the semantics of the type system.
Thanks! I think a general review is enough; this text is so big that we can't hope to get it all right, and I primarily want this in so we can start iterating on it and improving it. |
Copied over from https://github.com/JelleZijlstra/typing-spec
The text largely derives from the typing PEPs, though I added some
material. The organization is based on an outline by @erictraut.
@rchen152 and @Daverball made contributions to the text.
This was previously discussed on https://discuss.python.org/t/proposed-initial-typing-spec/39389. I'll submit an issue to the Typing Council to request its imprimatur.