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

Created on 2019-04-18 19:36 by mfisherlevine, last changed 2019-04-22 19:13 by brett.cannon.

Messages (10)
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.
History
Date User Action Args
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