This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Document PEP 557 Data Classes (dataclasses module)
Type: Stage: resolved
Components: Documentation Versions: Python 3.8, Python 3.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: eric.smith Nosy List: Chris.Barker, Mariatta, barry, docs@python, eric.smith, levkivskyi, mastrodomenico, miss-islington, ned.deily, rhettinger, vstinner
Priority: Keywords: patch

Created on 2017-12-05 02:05 by eric.smith, last changed 2022-04-11 14:58 by admin. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 6886 merged eric.smith, 2018-05-15 23:51
PR 6894 merged miss-islington, 2018-05-16 08:22
PR 6913 merged barry, 2018-05-16 16:45
PR 6918 merged miss-islington, 2018-05-16 19:51
Messages (21)
msg307614 - (view) Author: Eric V. Smith (eric.smith) * (Python committer) Date: 2017-12-05 02:05
The documentation needs to be added.
msg308608 - (view) Author: Christopher Barker (Chris.Barker) Date: 2017-12-19 02:41
It was suggested that I could contirbute to the docs of dataclasses in this issue. Which confuses me, as there doesn't appear to be any content here to comment on. But what the heck:

As I've been annoyingly persistent about on the python-dev list, I think we need to be quite careful about making type hints appear to be a requirement for using dataclasses. In order to counter this, we could:

* have the first couple example be type-less:

@dataclass
class C:
    a: ...   # field without a default
    b: ... = 0 # field with a default

or something like that.

Then purposely introduce "how to add type hints" a bit down in the docs.
msg308920 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2017-12-21 23:48
My Issue32406 has been marked as a duplicate of this one. Copy of my message:

bpo-32214 "Implement PEP 557: Data Classes" added a new dataclasses module and was closed, but the new module is not documented:
https://docs.python.org/dev/library/dataclasses.html

And it's also missing from What's New in Python 3.7:
https://docs.python.org/dev/whatsnew/3.7.html
msg311496 - (view) Author: Barry A. Warsaw (barry) * (Python committer) Date: 2018-02-02 15:14
Do you have an ETA for the documentation PR?  I would be happy to review it.
msg311498 - (view) Author: Eric V. Smith (eric.smith) * (Python committer) Date: 2018-02-02 15:24
I was hoping a volunteer would step up to write the documentation, as it's definitely not my forte.

Raymond has also volunteered to help.
msg311499 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2018-02-02 15:50
Marking this as a "deferred blocker" for exiting the beta phase.
msg311531 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2018-02-03 03:23
I'd be interested to help write the PR for this.
msg311576 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2018-02-03 23:32
> I'd be interested to help write the PR for this.

I've already started on drafting these docs.  Would you like to work together?
msg311583 - (view) Author: Christopher Barker (Chris.Barker) Date: 2018-02-04 03:25
Thanks Raymond. Can a draft be put in a gitHub repo so we can all help out?
msg311584 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2018-02-04 03:36
> I've already started on drafting these docs.  Would you like to work together?

Sure, Raymond. Let me know how I can help :)
msg314823 - (view) Author: Lino Mastrodomenico (mastrodomenico) Date: 2018-04-02 19:25
Friendly ping, there's still no documentation for this wonderful new module and there's only one planned beta left for 3.7 before the release candidates.

Needless to say, https://www.python.org/dev/peps/pep-0557/ has lots of information that could be a starting point.
msg316360 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2018-05-10 12:35
We really need to get this done prior to 370rc1 coming up on 05-21.
msg316545 - (view) Author: Eric V. Smith (eric.smith) * (Python committer) Date: 2018-05-14 18:07
Note that the documentation should make the implications of #33453 very clear.

In short, if an annotation "looks like" a ClassVar or InitVar, it will be treated as such. This is true even if it's specified as a string, or if it's a string due to "from __future__ import annotations".

I'm planning on specifying more details in #33453.
msg316634 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2018-05-15 10:23
Mariatta, go ahead and take the lead on this one.
msg316783 - (view) Author: Eric V. Smith (eric.smith) * (Python committer) Date: 2018-05-16 08:20
New changeset 98d50cb8f57eb227c373cb94b8680b12ec8aade5 by Eric V. Smith in branch 'master':
bpo-32216: Add documentation for dataclasses (GH-6886)
https://github.com/python/cpython/commit/98d50cb8f57eb227c373cb94b8680b12ec8aade5
msg316790 - (view) Author: miss-islington (miss-islington) Date: 2018-05-16 09:17
New changeset 04e96da5e4982afeb639d6a4d232c6c221fe3a9d by Miss Islington (bot) in branch '3.7':
bpo-32216: Add documentation for dataclasses (GH-6886)
https://github.com/python/cpython/commit/04e96da5e4982afeb639d6a4d232c6c221fe3a9d
msg316793 - (view) Author: Eric V. Smith (eric.smith) * (Python committer) Date: 2018-05-16 09:21
I've added some initial documentation. Most of it is text from the PEP, cleaned up and sphinx-ized. It no doubt needs a lot of work, but I think it's good enough to close this issue and remove the release blocker. Changes to the documentation can be done going forward, including after 3.7.0rc1 is released.
msg316839 - (view) Author: Barry A. Warsaw (barry) * (Python committer) Date: 2018-05-16 16:44
I've got a branch that cleans up and updates the dataclasses documentation, so I'm reopening this issue and piggybacking my PR on it.
msg316840 - (view) Author: Barry A. Warsaw (barry) * (Python committer) Date: 2018-05-16 16:44
...although I unfortunately cannot build it because of Issue33543
msg316854 - (view) Author: Barry A. Warsaw (barry) * (Python committer) Date: 2018-05-16 19:50
New changeset 713a9367366c88662c39ed20dd6bce22399299f1 by Barry Warsaw in branch 'master':
bpo-32216: Update dataclasses documentation (#6913)
https://github.com/python/cpython/commit/713a9367366c88662c39ed20dd6bce22399299f1
msg316862 - (view) Author: Barry A. Warsaw (barry) * (Python committer) Date: 2018-05-16 20:37
New changeset 0c62e09774e445a185fd192524454ce697ca123b by Barry Warsaw (Miss Islington (bot)) in branch '3.7':
bpo-32216: Update dataclasses documentation (GH-6913) (#6918)
https://github.com/python/cpython/commit/0c62e09774e445a185fd192524454ce697ca123b
History
Date User Action Args
2022-04-11 14:58:55adminsetgithub: 76397
2018-05-16 20:37:17barrysetmessages: + msg316862
2018-05-16 19:52:10barrysetstatus: open -> closed
stage: patch review -> resolved
2018-05-16 19:51:17miss-islingtonsetpull_requests: + pull_request6586
2018-05-16 19:50:09barrysetmessages: + msg316854
2018-05-16 16:45:48barrysetstage: resolved -> patch review
pull_requests: + pull_request6581
2018-05-16 16:44:54barrysetmessages: + msg316840
2018-05-16 16:44:27barrysetstatus: closed -> open

messages: + msg316839
2018-05-16 09:21:42eric.smithsetstatus: open -> closed
priority: release blocker ->
messages: + msg316793

assignee: docs@python -> eric.smith
resolution: fixed
stage: patch review -> resolved
2018-05-16 09:17:05miss-islingtonsetnosy: + miss-islington
messages: + msg316790
2018-05-16 08:22:09miss-islingtonsetpull_requests: + pull_request6566
2018-05-16 08:20:53eric.smithsetmessages: + msg316783
2018-05-15 23:51:12eric.smithsetkeywords: + patch
stage: needs patch -> patch review
pull_requests: + pull_request6560
2018-05-15 10:23:58rhettingersetmessages: + msg316634
2018-05-14 18:07:42eric.smithsetmessages: + msg316545
2018-05-10 12:35:34ned.deilysetpriority: deferred blocker -> release blocker

messages: + msg316360
2018-04-02 19:25:31mastrodomenicosetnosy: + mastrodomenico
messages: + msg314823
2018-02-04 03:36:58Mariattasetmessages: + msg311584
2018-02-04 03:25:34Chris.Barkersetmessages: + msg311583
2018-02-03 23:32:41rhettingersetnosy: + rhettinger
messages: + msg311576
2018-02-03 03:23:51Mariattasetnosy: + Mariatta
messages: + msg311531
2018-02-02 15:50:39ned.deilysetpriority: high -> deferred blocker
versions: + Python 3.8
nosy: + ned.deily

messages: + msg311499

stage: needs patch
2018-02-02 15:24:22eric.smithsetmessages: + msg311498
2018-02-02 15:14:26barrysetnosy: + barry
messages: + msg311496
2017-12-21 23:48:08vstinnersetnosy: + vstinner
messages: + msg308920
2017-12-21 23:44:19eric.smithsettitle: Document PEP 557 Data Classes -> Document PEP 557 Data Classes (dataclasses module)
2017-12-19 02:41:17Chris.Barkersetnosy: + Chris.Barker
messages: + msg308608
2017-12-08 18:17:21levkivskyisetnosy: + levkivskyi
2017-12-05 02:05:11eric.smithcreate