classification
Title: Missing dataclass decorator import in dataclasses module docs
Type: enhancement Stage: patch review
Components: Documentation Versions: Python 3.8, Python 3.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Cheukting, Windson Yang, brett.cannon, docs@python, eric.smith, matrixise, mfisherlevine, mturner865, xtreak
Priority: normal Keywords: easy, patch

Created on 2019-04-18 19:36 by mfisherlevine, last changed 2019-06-26 09:51 by Cheukting.

Pull Requests
URL Status Linked Edit
PR 14329 closed Kriyszig, 2019-06-24 05:34
Messages (12)
msg340510 - (view) Author: Merlin Fisher-Levine (mfisherlevine) Date: 2019-04-18 19:36
Dataclasses docs don't mention needing import for @dataclass decorator

https://docs.python.org/3/library/dataclasses.html
msg340524 - (view) Author: Karthikeyan Singaravelan (xtreak) * (Python triager) Date: 2019-04-19 05:26
I think the import is implied in the example since the docs page is for dataclasses module but adding an explicit import to InventoryItem at the top won't hurt too.
msg340528 - (view) Author: Stéphane Wirtel (matrixise) * (Python committer) Date: 2019-04-19 08:34
We could change the example with 

```
from dataclasses import dataclass

@dataclass
class InventoryItem:
    ...
```

Because it's not specified in the documentation (header, that we need to
import dataclass from dataclasses).

+1 for a small update.

You are free to propose a PR.

Have a nice day,

>I think the import is implied in the example since the docs page is for
>dataclasses module but adding an explicit import to InventoryItem at
>the top won't hurt too.
Yep, but explicit is better than implicit.
msg340529 - (view) Author: Eric V. Smith (eric.smith) * (Python committer) Date: 2019-04-19 08:39
I think adding "from dataclasses import dataclass" in the first example is fine.

There's a similar import in the sqlite3 documentation, just to pick one at random.
msg340531 - (view) Author: Stéphane Wirtel (matrixise) * (Python committer) Date: 2019-04-19 08:44
Ok, I suggest to add a "first issue" for the sprint days at PyCon US.
msg340559 - (view) Author: Windson Yang (Windson Yang) * Date: 2019-04-20 00:37
I can find some example in the docs that didn't `import the correct module` even in the first example. Should we add the `import` statement for all of them?
msg340568 - (view) Author: Eric V. Smith (eric.smith) * (Python committer) Date: 2019-04-20 09:18
I won't discourage anyone from making such changes, but I don't think it's a real problem. I haven't seen that people are confused about needing to import the module being discussed in the documentation. I don't think there's any expectation that the code in the documentation is actually executable as-is. They're not doctests, after all.
msg340572 - (view) Author: Windson Yang (Windson Yang) * Date: 2019-04-20 13:00
I agreed most of the documents won't need the change, but some documents like https://docs.python.org/3/library/dataclasses.html#dataclasses.field didn't mention we have to run `from typing import List` and I guess most developers not familiar with this package. I suggest we should add the import statement for the uncommon package.
msg340577 - (view) Author: Eric V. Smith (eric.smith) * (Python committer) Date: 2019-04-20 15:32
I definitely think any missing import from typing should be added.
msg340679 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2019-04-22 19:13
I also don't think it's critical to make examples within a module's docs work like a doctest. Plus I discourage importing objects directly off of modules anyway and this would actually promote that.
msg346349 - (view) Author: Mark Turner (mturner865) * Date: 2019-06-24 00:07
I tried a couple of the examples from the docs and found the setup to be a little confusing
amd inconsistent. For example, the decorator line "@decorator" requires you to use

from dataclasses import dataclass

while the example line "mylist: List[int] = field(default_factory=list)" requires you to use these

import dataclasses
import typing

and must be modified to
mylist: typing.List[int] = dataclasses.field(default_factory=list)

The decorator line could be modified to be
@dataclasses.dataclass
and the from/import line could be eliminated. But that seems awkward.

So, what is are best practices for handling the imports needed by these examples?
And should the examples be updated to be consistent with a best practice set of imports?
Or am I not understanding how this code works?

Also, the intro section states "If any of the added methods already exist on the class, a TypeError will be raised."
This statement seems incorrect and contrdicts the parameter documentation that follows.
msg346595 - (view) Author: Cheuk Ting Ho (Cheukting) Date: 2019-06-26 09:51
I agree that for the more confusing ones, it would be better to write out the import statement explicitly.
History
Date User Action Args
2019-06-26 09:51:57Cheuktingsetnosy: + Cheukting
messages: + msg346595
2019-06-24 05:34:19Kriyszigsetkeywords: + patch
stage: patch review
pull_requests: + pull_request14149
2019-06-24 00:07:25mturner865setnosy: + mturner865
messages: + msg346349
2019-04-22 19:13:57brett.cannonsetnosy: + brett.cannon
messages: + msg340679
2019-04-20 15:32:40eric.smithsetmessages: + msg340577
2019-04-20 13:00:36Windson Yangsetmessages: + msg340572
2019-04-20 09:18:43eric.smithsetmessages: + msg340568
2019-04-20 00:37:23Windson Yangsetnosy: + Windson Yang
messages: + msg340559
2019-04-19 08:45:35matrixisesetkeywords: + easy
2019-04-19 08:44:14matrixisesetmessages: + msg340531
2019-04-19 08:39:32eric.smithsetmessages: + msg340529
2019-04-19 08:34:54matrixisesetnosy: + matrixise
messages: + msg340528
2019-04-19 05:26:25xtreaksetnosy: + eric.smith, xtreak
title: Missing import in docs -> Missing dataclass decorator import in dataclasses module docs
messages: + msg340524

versions: + Python 3.8
2019-04-18 19:36:48mfisherlevinecreate