classification
Title: PEP 484 docs
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.6, Python 3.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Daniel.Andrade.Groppe, Mark.Shannon, berker.peksag, docs@python, gvanrossum, larry, levkivskyi, python-dev
Priority: high Keywords: patch

Created on 2015-05-23 21:09 by gvanrossum, last changed 2015-09-10 17:56 by gvanrossum. This issue is now closed.

Files
File name Uploaded Description Edit
typing_doc.patch Daniel.Andrade.Groppe, 2015-05-24 18:30 typing documentation review
typing_doc_v2.patch Daniel.Andrade.Groppe, 2015-05-25 03:47 removed classes not included in __all__ review
typing_doc_v3.patch levkivskyi, 2015-08-02 20:59 latest comments by Guido are taken into account (original patch by Daniel) review
typedoc_new.patch levkivskyi, 2015-08-07 14:40 new patch for documenting first half of remaining classes review
typying_documentation_part2.patch Daniel.Andrade.Groppe, 2015-08-11 03:19 patch for second* half of remaining classes review
Messages (28)
msg243945 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2015-05-23 21:09
Would be nice if there were more docs for the typing module (PEP 484). Looking for volunteers. (There's stuff in the PEP that can serve as a starting point.)

Note: support for isinstance() and issubclass() will be withdrawn in beta 2.
msg243996 - (view) Author: Daniel Andrade Groppe (Daniel.Andrade.Groppe) * Date: 2015-05-24 18:30
A first iteration of the documentation based on the PEP and the module source.

This still needs a lot of work.
msg244010 - (view) Author: Daniel Andrade Groppe (Daniel.Andrade.Groppe) * Date: 2015-05-25 03:47
Addressing comments from the review. Here is an updated patch.
msg247873 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2015-08-02 14:17
This should probably be committed before RC1 -- it's better than nothing!
msg247875 - (view) Author: Ivan Levkivskyi (levkivskyi) * (Python committer) Date: 2015-08-02 14:37
Is anyone working on this right now? If not, I could implement the comments by Guido to the latest patch by Daniel.
msg247876 - (view) Author: Daniel Andrade Groppe (Daniel.Andrade.Groppe) * Date: 2015-08-02 15:00
I dropped the ball here. The last message from the review system was misclassified by Gmail as spam... Sorry about that.

I can take a look at this tonight but if anyone can address the comments earlier, go for it.
msg247894 - (view) Author: Ivan Levkivskyi (levkivskyi) * (Python committer) Date: 2015-08-02 20:59
New version of the patch by Daniel, latest comments by Guido are taken into account.
msg247952 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2015-08-03 20:31
Thank you Ivan! I am going to commit this, it's much better than the two lines we had before. :-) There's still a lot of work left to do -- towards the end there are many classes without description. Maybe you and Daniel can divide up the work for those? We can always iterate (even during the release candidates and even after the 3.5.0 release).
msg248001 - (view) Author: Ivan Levkivskyi (levkivskyi) * (Python committer) Date: 2015-08-04 20:36
I could add the docs for the first half of the remaining classes by the end of this week.
msg248026 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2015-08-05 10:27
New changeset a8dcbd2711d6 by Guido van Rossum in branch '3.5':
Issue #24272: Initial docs for typing.py (PEP 484).
https://hg.python.org/cpython/rev/a8dcbd2711d6

New changeset 0c74fd4219aa by Guido van Rossum in branch 'default':
Issue #24272: Initial docs for typing.py (PEP 484). (Merge from 3.5.)
https://hg.python.org/cpython/rev/0c74fd4219aa
msg248028 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2015-08-05 10:28
I've landed this now (for real). Next time please strip all trailing whitespace from typing.rst, else the hg push fails!
msg248046 - (view) Author: Daniel Andrade Groppe (Daniel.Andrade.Groppe) * Date: 2015-08-05 15:00
@Ivan, I'll work on the remaining half.
msg248196 - (view) Author: Ivan Levkivskyi (levkivskyi) * (Python committer) Date: 2015-08-07 14:40
Here is a new patch for the first part of classes at the end of docs.
I also did some minor changes (in particular added more info on generics and removed the section about ellipsis for default arguments, we could return it if we decide to write something about stub files here).
msg248304 - (view) Author: Larry Hastings (larry) * (Python committer) Date: 2015-08-08 21:57
I assume what we've got is good enough for rc1?

Can we mark this closed / reduce the priority from "release blocker"?

Note that there are few (if any) restrictions on fixing docs during the release candidates.  (Though after today we'll be switching to the Bitbucket "pull request" workflow, so that will complicate matters slightly.)
msg248312 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2015-08-09 07:08
Yeah, there's another diff but I didn't get to it.
msg248385 - (view) Author: Daniel Andrade Groppe (Daniel.Andrade.Groppe) * Date: 2015-08-11 03:18
Here's a patch for the second half of remaining classes (this file is a complement of Ivan Levkivskyi's patch).
msg248386 - (view) Author: Daniel Andrade Groppe (Daniel.Andrade.Groppe) * Date: 2015-08-11 03:19
Missing Generator.
msg249349 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2015-08-30 03:41
New changeset 192c654a7c93 by Zachary Ware in branch '3.5':
Issue #24272: Remove usage of default reST role from typing docs
https://hg.python.org/cpython/rev/192c654a7c93

New changeset 10a63ded324c by Zachary Ware in branch 'default':
Issue #24272: Merge with 3.5
https://hg.python.org/cpython/rev/10a63ded324c
msg250086 - (view) Author: Ivan Levkivskyi (levkivskyi) * (Python committer) Date: 2015-09-07 08:36
Guido, are you going to commit our patches before 3.5.final? Is there a merge conflict now? Should I rebase my diff?

If necessary I could make a clean patch combining two patches (my and Daniel's) on top of what Zachary did.
msg250118 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2015-09-07 16:58
I apologize, I've been distracted. I will try to get to this before 3.5.0 final goes out! I don't know if the fixes will end up in the tar ball but they will certainly be on docs.python.org.
msg250128 - (view) Author: Larry Hastings (larry) * (Python committer) Date: 2015-09-07 20:22
Doc fixes are always welcome.  Barring mishaps I should tag 3.5.0 final on Saturday; it'd be sweet if you could get me your diff no later than Friday night.
msg250329 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2015-09-09 20:10
Pull Request: https://bitbucket.org/larry/cpython350/pull-requests/24/docs-update-for-typing-module/diff
msg250331 - (view) Author: Ivan Levkivskyi (levkivskyi) * (Python committer) Date: 2015-09-09 20:33
Thank you, Guido!

I have noticed single quotes in line 38: 

type hinted using `Callable[[Arg1Type, Arg2Type], ReturnType]`

I think it would be logical to replace it with double quotes: 

``Callable[[Arg1Type, Arg2Type], ReturnType]`` 

as Zachary did in the rest of the text.

By the way, you have marked my patch as Daniels and vice versa in the commit descriptions, but that probably does not matter :)
msg250332 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2015-09-09 20:38
I apologize for the mix-up! The code review tool didn't help.

Regarding the single quotes, there seem to be a bunch more of these, and as cutting a PR is a fair bit of labor I'd rather not fix that. We can fix this once 3.5.0 it out of the door (hopefully this weekend).
msg250346 - (view) Author: Larry Hastings (larry) * (Python committer) Date: 2015-09-10 02:16
Pull request accepted!  Please forward-merge, thanks!
msg250348 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2015-09-10 02:39
Merged and pushed. Let's please use a new issue for any further patches.
msg250396 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2015-09-10 17:20
By the way, for some reason the changes in revision e361130782d4 are not in Doc/library/typing.rst.

For example,

io documentation on current default branch: https://hg.python.org/cpython/file/default/Doc/library/typing.rst#l376
io documentation on current 3.5 branch: https://hg.python.org/cpython/file/3.5/Doc/library/typing.rst#l376
Updates to the io documntation in revision e361130782d4: https://hg.python.org/cpython/rev/e361130782d4#l1.67

Also, my clone is up-to-date:

changeset:   97855:d433d74e0377
tag:         tip
user:        Victor Stinner <victor.stinner@gmail.com>
date:        Thu Sep 10 16:00:06 2015 +0200
files:       Python/pytime.c
description:
pytime: oops, fix typos on Windows
msg250398 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2015-09-10 17:56
I suck at merge. :-( No idea what happened. To fix it, I have now just
copied the file again from the larry branch and committed that in 3.5, then
merged up to 3.6 (default).

changeset:   97856:8a7814a3613b
branch:      3.5
parent:      97847:6c8e2c6e3a99
user:        Guido van Rossum <guido@python.org>
date:        Thu Sep 10 10:52:11 2015 -0700
summary:     Restore doc updates to typing.rst by Ivan Levkivskyi and
Daniel Andrade Groppe.

changeset:   97857:7fc4306d537b
tag:         tip
parent:      97855:d433d74e0377
parent:      97856:8a7814a3613b
user:        Guido van Rossum <guido@dropbox.com>
date:        Thu Sep 10 10:54:10 2015 -0700
summary:     Restore doc updates to typing.rst by Ivan Levkivskyi and
Daniel Andrade Groppe.
History
Date User Action Args
2015-09-10 17:56:18gvanrossumsetmessages: + msg250398
2015-09-10 17:20:03berker.peksagsetmessages: + msg250396
2015-09-10 13:36:08berker.peksagsetresolution: fixed
stage: patch review -> resolved
2015-09-10 02:39:10gvanrossumsetstatus: open -> closed

messages: + msg250348
2015-09-10 02:16:20larrysetmessages: + msg250346
2015-09-09 20:38:09gvanrossumsetmessages: + msg250332
2015-09-09 20:33:01levkivskyisetmessages: + msg250331
2015-09-09 20:10:11gvanrossumsetmessages: + msg250329
2015-09-07 20:22:28larrysetmessages: + msg250128
2015-09-07 16:58:24gvanrossumsetmessages: + msg250118
2015-09-07 08:36:45levkivskyisetmessages: + msg250086
2015-08-30 03:41:06python-devsetmessages: + msg249349
2015-08-11 03:19:36Daniel.Andrade.Groppesetfiles: + typying_documentation_part2.patch

messages: + msg248386
2015-08-11 03:18:06Daniel.Andrade.Groppesetmessages: + msg248385
2015-08-09 10:12:36larrysetpriority: release blocker -> high
2015-08-09 07:08:16gvanrossumsetmessages: + msg248312
2015-08-08 21:57:02larrysetnosy: + larry
messages: + msg248304
2015-08-07 14:40:20levkivskyisetfiles: + typedoc_new.patch

messages: + msg248196
2015-08-05 15:00:37Daniel.Andrade.Groppesetmessages: + msg248046
2015-08-05 10:28:40gvanrossumsetmessages: + msg248028
2015-08-05 10:27:42python-devsetnosy: + python-dev
messages: + msg248026
2015-08-04 20:36:43levkivskyisetmessages: + msg248001
2015-08-03 20:31:26gvanrossumsetmessages: + msg247952
2015-08-03 09:44:49Mark.Shannonsetnosy: + Mark.Shannon
2015-08-02 20:59:04levkivskyisetfiles: + typing_doc_v3.patch

messages: + msg247894
2015-08-02 15:00:37Daniel.Andrade.Groppesetmessages: + msg247876
2015-08-02 14:37:53levkivskyisetmessages: + msg247875
2015-08-02 14:17:55gvanrossumsetpriority: normal -> release blocker

messages: + msg247873
2015-07-26 08:42:30berker.peksagsetnosy: + berker.peksag
stage: needs patch -> patch review

versions: + Python 3.6
2015-07-26 08:41:42berker.peksaglinkissue24723 superseder
2015-06-29 12:22:27levkivskyisetnosy: + levkivskyi
2015-05-25 03:47:04Daniel.Andrade.Groppesetfiles: + typing_doc_v2.patch

messages: + msg244010
2015-05-24 18:30:48Daniel.Andrade.Groppesetfiles: + typing_doc.patch

nosy: + Daniel.Andrade.Groppe
messages: + msg243996

keywords: + patch
2015-05-23 21:10:00gvanrossumsettype: enhancement
stage: needs patch
2015-05-23 21:09:28gvanrossumcreate