Add Syntax and Distribution sections #17

srittau · 2018-10-01T09:18:34Z

Closes: #8

JelleZijlstra · 2018-10-01T15:50:22Z

pep-9999.rst

+Type stubs are syntactically valid Python files with a ``.pyi`` suffix.
+Type checkers are expected to support the syntax of the latest Python
+version. Type stubs should be parseable with the latest released Python
+version, but also support the previous version up until six months after


I think the usage of "support" here is confusing, since it refers only to syntactic validity. Probably better to just consistently say "should be syntactically valid" here.

Also, it might be good to have an explicit example of a timeline that would have applied to old features (like "December 1, 2016 - 3.6 is released; May 1, 2017 - stubs may now use variable annotations").

(I didn't look up the actual dates though.)

rchen152 · 2018-10-02T06:11:41Z

Sorry I didn't get around to reviewing this today - I'll look at it tomorrow morning. (And sorry about the closing and reopening - first time using the phone interface.)

srittau · 2018-10-02T07:27:37Z

Thank you for your reviews! I will look at them over the weekend.

rchen152 · 2018-10-02T16:23:20Z

pep-9999.rst

+version. Type stubs should be parseable with the latest released Python
+version, but also support the previous version up until six months after
+the release of the current version. Older Python versions do not need to be
+supported, even if the implementation supports older versions or the


I had to read "the implementation supports older versions" a couple times before understanding it - I think it would be clearer to say something along the lines of "the type information in the stub is targeted to an older version".

rchen152 · 2018-10-02T16:25:02Z

pep-9999.rst

+
+Type stubs are syntactically valid Python files with a ``.pyi`` suffix.
+Type checkers are expected to support the syntax of the latest Python
+version. Type stubs should be parseable with the latest released Python


Should the sentence about type checkers say something about the timeframe of expected support for the latest version (within six months of release) for symmetry with the type stub requirement?

I think it makes sense that type checkers aim to support a new Python version as soon as it comes out, so people type checking their code can use a new Python version when it becomes available. But I wonder whether it makes sense to reduce the six month to something like three?

What strikes me as odd about the current recommendation is that saying both that type checkers should immediately support the latest version and that stubs should give checkers a six month grace period means that there's no incentive for the first timeline to be followed.

I think either allowing stubs to immediately use new syntax or explicitly giving type checkers a grace period (whether that's six months or something shorter) would make sense to me.

I think I have described it backwards in the PR: Stubs can start to use new syntax immediately, but can use obsolete syntax up until 6 months after the release of a Python version. For the async example: Type checkers should have supported the async keyword in Python 3.7 code with the release of 3.7. Stubs can use async as a keyword immediately as well, but can still use async as an attribute up until 6 months after the release of 3.7. (Of course in the meantime the stubs can't be used to check 3.7 code.) Does this make more sense?

Ahhh, so the intent is that stubs have up to six months to become compatible with the newest version, rather than having to stay compatible with the previous version for that time period? In that case, yeah, I think the PR has described things the wrong way around.

rchen152 · 2018-10-02T16:27:03Z

pep-9999.rst

+Distribution
+============
+
+Type stubs can be distributed separately from the implementation, 


grammar nit: the comma should be a semicolon.

pep-9999.rst

rchen152 · 2018-10-02T16:29:41Z

pep-9999.rst

+    pkg
+        __init__.py
+        mod.py
+    stubs


I think this is supposed to be pkg-stubs, according to the naming scheme in PEP 561.

Oh, my example is confusing. I was trying to give an example for stubs for a stand-alone program, but of course this structure will not work when distributing the type hints via pypi. On the other hand, the pkg-stubs naming is for stubs-only packages. Maybe have three examples with better explanations:

Same directory (for distributing as part of the package)

pkg-stubs (for distributing as part of the package or as stand-alone package)

stubs/pkg (for stand-alone apps, where you won't distribute the stubs)

I removed this part, since it is confusing and I am not sure it added much value.

srittau · 2018-10-19T11:25:21Z

@JelleZijlstra @rchen152 Sorry for the delay, but I finally managed to address your review. I removed the directory structure part, since it was confusing and I don't think it conveys much useful information. Apart from that I reformulated the section with your feedback in mind. Not totally happy with it, yet.

emmatyping · 2018-10-19T21:06:04Z

pep-9999.rst

 References
 ==========

 .. [#pep484] PEP 484 -- Type Hints, van Rossum et al. (https://www.python.org/dev/peps/pep-0484)
 .. [#pep526] PEP 526 -- Syntax for Variable Annotations, Gonzalez et al. (https://www.python.org/dev/peps/pep-0526)
+.. [#pep561] PEP 561 -- Distributing and Packaging Type Information, Smit (https://www.python.org/dev/peps/pep-0561)


Unless you are intentionally truncating this, should be Smith :)

Whoops, sorry, fixing.

pep-9999.rst

emmatyping · 2018-10-19T21:10:30Z

pep-9999.rst

+For example, Python 3.6, introducing PEP 526 [#pep526]_variable annotations,
+was released on December 23rd, 2016. Type checkers should support
+variable annotations by that date, but type stubs should only
+started using them by June 23rd, 2017. Since that date the use


...should only start using them on June...

Solumin · 2018-10-23T22:29:42Z

The Stub Files section of PEP 484 recommend that function definitions should have ... instead of the body of the function. Does that belong in this section, or elsewhere in the PEP? (I can open an issue if there's need for a discussion on this.)

srittau · 2018-10-23T22:34:21Z

There was a bit of a discussion about this in #7. Personally, I'd put it in the "What constructs are typically supported by type checkers". On the PEP Content page we already have it that section.

Solumin · 2018-10-23T22:35:53Z

There was a bit of a discussion about this in #7. Personally, I'd put it in the "What constructs are typically supported by type checkers". On the PEP Content page we already have it that section.

Ah, great. I forgot to check the wiki. 👍 LGTM!

srittau · 2018-10-25T06:27:10Z

@rchen152 I have rewritten the syntax section again and used Python 3.7 and async as a better example. Could you check whether I got it right this time?

srittau · 2018-10-25T06:28:04Z

pep-9999.rst

+checkers should support them by that date and type stubs could start
+using `async` to mark function definitions. On the other hand, type stubs
+should stop using the new keyword as an attribute or function name before
+December 27nd, 2018.


This is actually a bit of a white lie. I think async could be used before that date (since it was introduced in Python 3.5), but I think as an example that is fine.

They're good examples because async and await became reserved keywords in 3.7, so using them as anything but reserved keywords in a stub file could be an error once the 6 month grace period ends.

I would change "On the other hand" to "Additionally" though.

rchen152

Looks great to me now!

pep-9999.rst

emmatyping

One minor comment, but otherwise looks good!

Co-Authored-By: srittau <srittau@rittau.biz>

srittau added 3 commits October 1, 2018 10:15

Add Syntax and Distribution sections

d864b23

Add an example and reference to PEP 526

0b86dd5

Reverse title to match content order

521c7ca

JelleZijlstra reviewed Oct 1, 2018

View reviewed changes

rchen152 closed this Oct 2, 2018

rchen152 reopened this Oct 2, 2018

rchen152 reviewed Oct 2, 2018

View reviewed changes

srittau added 3 commits October 5, 2018 18:31

Grammar

1fa3d09

Rework intro paragraph of syntax chapter

e52b5d9

Remove directory structure

a432aa5

emmatyping reviewed Oct 19, 2018

View reviewed changes

Fixes

66be805

Solumin approved these changes Oct 23, 2018

View reviewed changes

Fix stubs syntax validity dates

3e47da3

srittau commented Oct 25, 2018

View reviewed changes

Wording

b8b13d0

rchen152 approved these changes Oct 25, 2018

View reviewed changes

Solumin approved these changes Oct 25, 2018

View reviewed changes

emmatyping reviewed Oct 25, 2018

View reviewed changes

pep-9999.rst Outdated Show resolved Hide resolved

emmatyping approved these changes Oct 25, 2018

View reviewed changes

Clarify that type stubs can be distributed with the implementation

4d06143

Co-Authored-By: srittau <srittau@rittau.biz>

srittau merged commit 0891374 into type-stub-pep Oct 26, 2018

srittau deleted the syntax branch October 26, 2018 07:26

srittau mentioned this pull request Oct 26, 2018

To which Python version should a stub's syntax conform to? #8

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Syntax and Distribution sections #17

Add Syntax and Distribution sections #17

srittau commented Oct 1, 2018 •

edited

Loading

JelleZijlstra Oct 1, 2018

JelleZijlstra Oct 1, 2018

JelleZijlstra Oct 1, 2018

rchen152 commented Oct 2, 2018 •

edited

Loading

srittau commented Oct 2, 2018

rchen152 Oct 2, 2018

rchen152 Oct 2, 2018

srittau Oct 19, 2018

rchen152 Oct 23, 2018

srittau Oct 23, 2018

rchen152 Oct 23, 2018

rchen152 Oct 2, 2018

rchen152 Oct 2, 2018

srittau Oct 5, 2018

srittau Oct 19, 2018

srittau commented Oct 19, 2018

emmatyping Oct 19, 2018

srittau Oct 21, 2018

emmatyping Oct 19, 2018

Solumin commented Oct 23, 2018

srittau commented Oct 23, 2018

Solumin commented Oct 23, 2018

srittau commented Oct 25, 2018

srittau Oct 25, 2018

Solumin Oct 25, 2018

rchen152 left a comment

emmatyping left a comment

Add Syntax and Distribution sections #17

Add Syntax and Distribution sections #17

Conversation

srittau commented Oct 1, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rchen152 commented Oct 2, 2018 • edited Loading

srittau commented Oct 2, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

srittau commented Oct 19, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Solumin commented Oct 23, 2018

srittau commented Oct 23, 2018

Solumin commented Oct 23, 2018

srittau commented Oct 25, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rchen152 left a comment

Choose a reason for hiding this comment

emmatyping left a comment

Choose a reason for hiding this comment

srittau commented Oct 1, 2018 •

edited

Loading

rchen152 commented Oct 2, 2018 •

edited

Loading