Update code sample when importing modules in queue doc #94244
Conversation
In the queue documentation, the code snippet shows the import to be not PEP 8 compliant. Since people typically copy-paste from such code samples, I think it's important to show best-practices here.
Mariatta
added
skip issue
skip news
docs
|
We've generally avoided this sort of change. It doesn't improve the readability of the docs because we want people to focus on the main part of the code sample. Also the rationale behind the PEP 8 guidance doesn't apply here. In production code, having imports on separate lines makes maintenance easier because diffs are simpler to read. That of course doesn't apply to doc examples. The other rationale is that if there are many imports, then having them on separate lines and in alphabetical order makes them easier to search. |
|
I think you're both right. In general, we avoid overshadowing the code example with boilerplate as much as possible. Agreed. In this case however, it takes barely a 6% SLOC difference to split the import into two and in this way to avoid the busy import statement becoming its own (bad) "code example". So I'd say it's worth the tiny churn it takes to land the three PRs. |
In the queue documentation, the code snippet shows the import to be not PEP 8 compliant. Since people typically copy-paste from such code samples, I think it's important to show best-practices here. (cherry picked from commit ad55147) Co-authored-by: Mariatta Wijaya <Mariatta@users.noreply.github.com>
|
GH-94490 is a backport of this pull request to the 3.11 branch. |
In the queue documentation, the code snippet shows the import to be not PEP 8 compliant. Since people typically copy-paste from such code samples, I think it's important to show best-practices here. (cherry picked from commit ad55147) Co-authored-by: Mariatta Wijaya <Mariatta@users.noreply.github.com>
|
GH-94491 is a backport of this pull request to the 3.10 branch. |
…-94490) In the queue documentation, the code snippet shows the import to be not PEP 8 compliant. Since people typically copy-paste from such code samples, I think it's important to show best-practices here. (cherry picked from commit ad55147) Co-authored-by: Mariatta Wijaya <Mariatta@users.noreply.github.com>
…-94491) In the queue documentation, the code snippet shows the import to be not PEP 8 compliant. Since people typically copy-paste from such code samples, I think it's important to show best-practices here. (cherry picked from commit ad55147) Co-authored-by: Mariatta Wijaya <Mariatta@users.noreply.github.com>
In the queue documentation, the code snippet shows the import to be not PEP 8 compliant.
https://docs.python.org/3/library/queue.html
Since people typically copy-paste from such code samples, I think it's important to show best-practices here.