[issue36661] Missing dataclass decorator import in dataclasses module docs

[Brett Cannon]

Change by Brett Cannon :


--
resolution:  -> fixed
stage: patch review -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue36661] Missing dataclass decorator import in dataclasses module docs

[Brett Cannon]

Brett Cannon  added the comment:

Thanks for noticing, Karl!

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue36661] Missing dataclass decorator import in dataclasses module docs

[karl]

karl  added the comment:

This should be closed. The PR has been merged and the doc is now up to date.

--
nosy: +karlcow

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue36661] Missing dataclass decorator import in dataclasses module docs

[Cheuk Ting Ho]

Cheuk Ting Ho  added the comment:

I agree that for the more confusing ones, it would be better to write out the 
import statement explicitly.

--
nosy: +Cheukting

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue36661] Missing dataclass decorator import in dataclasses module docs

[Prateek Nayak]

Change by Prateek Nayak :


--
keywords: +patch
pull_requests: +14149
stage:  -> patch review
pull_request: https://github.com/python/cpython/pull/14329

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue36661] Missing dataclass decorator import in dataclasses module docs

[Mark turner]

Mark turner  added the comment:

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.

--
nosy: +mturner865

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue36661] Missing dataclass decorator import in dataclasses module docs

[Brett Cannon]

Brett Cannon  added the comment:

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.

--
nosy: +brett.cannon

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue36661] Missing dataclass decorator import in dataclasses module docs

[Eric V. Smith]

Eric V. Smith  added the comment:

I definitely think any missing import from typing should be added.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue36661] Missing dataclass decorator import in dataclasses module docs

[Windson Yang]

Windson Yang  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue36661] Missing dataclass decorator import in dataclasses module docs

[Eric V. Smith]

Eric V. Smith  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue36661] Missing dataclass decorator import in dataclasses module docs

[Windson Yang]

Windson Yang  added the comment:

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?

--
nosy: +Windson Yang

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue36661] Missing dataclass decorator import in dataclasses module docs

[Stéphane Wirtel]

Change by Stéphane Wirtel :


--
keywords: +easy

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue36661] Missing dataclass decorator import in dataclasses module docs

[Stéphane Wirtel]

Stéphane Wirtel  added the comment:

Ok, I suggest to add a "first issue" for the sprint days at PyCon US.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue36661] Missing dataclass decorator import in dataclasses module docs

[Eric V. Smith]

Eric V. Smith  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue36661] Missing dataclass decorator import in dataclasses module docs

[Stéphane Wirtel]

Stéphane Wirtel  added the comment:

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.

--
nosy: +matrixise

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue36661] Missing dataclass decorator import in dataclasses module docs

[Karthikeyan Singaravelan]

Karthikeyan Singaravelan  added the comment:

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.

--
nosy: +eric.smith, xtreak
title: Missing import in docs -> Missing dataclass decorator import in 
dataclasses module docs
versions: +Python 3.8

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com