classification
Title: [docs] Minor information-ordering issue in __main__ doc
Type: behavior Stage: patch review
Components: Documentation Versions: Python 3.11
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, eric.araujo, ferdnyc, jacksonbrummell1, taleinat
Priority: normal Keywords: easy, patch

Created on 2022-01-06 12:57 by ferdnyc, last changed 2022-01-13 09:18 by AlexWaygood.

Pull Requests
URL Status Linked Edit
PR 30480 open jacksonbrummell1, 2022-01-08 09:36
Messages (9)
msg409839 - (view) Author: FeRD (Frank Dana) (ferdnyc) * Date: 2022-01-06 12:57
The expanded documentation on top-level environments is quite an improvement, but there's one passage that causes some confusion. In the section '__main__.py in Python Packages', towards the end, it reads:

"""
This won’t work for __main__.py files in the root directory of a .zip file though. Hence, for consistency, minimal __main__.py like the venv one mentioned above are preferred.
"""

Problem is, that's the first mention of venv anywhere in the document. There's a 'See also:' box right BELOW the sentence in question that references venv and its minimal __main__.py, but it hasn't been introduced yet when that first mention comes along.
msg409997 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2022-01-07 18:38
Do you have a suggestion on how to fix this?
msg410085 - (view) Author: Jackson Brummell (jacksonbrummell1) * Date: 2022-01-08 09:12
It seems this is a simple miswording, where the word 'above' is used when the see below example clarifies BELOW the text.

I will create a pull request within the hour
msg410087 - (view) Author: Jackson Brummell (jacksonbrummell1) * Date: 2022-01-08 09:54
Updating issue, Have submitted fix
msg410088 - (view) Author: FeRD (Frank Dana) (ferdnyc) * Date: 2022-01-08 10:10
TBH, personally I don't think I'd just reword it with "below". That seems like the path of least resistance, but then the sentence becomes this:

"""
This won’t work for __main__.py files in the root directory of a .zip file though. Hence, for consistency, minimal __main__.py like the venv one mentioned below are preferred.
"""

Doesn't really track. How can you draw conclusions ("Hence...") from something that hasn't even been discussed yet?

It might actually be better to just drop the mention of venv from that particular sentence. The see-also text introduces *itself* as an example of what was just discussed. There's no real reason to bring it up ahead of time, because the see-also already flows naturally from the previous discussion without any setup.
msg410091 - (view) Author: Tal Einat (taleinat) * (Python committer) Date: 2022-01-08 10:21
I agree that it seems better to avoid menntioning venv in that sentence. Specifically I suggest:

This won’t work for __main__.py files in the root directory of a .zip file though. Hence, for consistency, minimal __main__.py without a __name__ check are preferred.
msg410093 - (view) Author: FeRD (Frank Dana) (ferdnyc) * Date: 2022-01-08 10:49
Maybe,

"""
This won’t work for __main__.py files in the root directory of a .zip file though. Thus, for consistency, it is usually preferred to place code in other modules. That code can then be invoked from a minimal ``__main__.py``.
"""

(And then the see-also opens, "See venv for an example of a package with a minimal __main__.py in the standard library." which is a natural extension of the discussion.)

@taleinat's suggestion works as well (crossed streams).
msg410121 - (view) Author: Jackson Brummell (jacksonbrummell1) * Date: 2022-01-08 21:43
Have updated the PR to be in line with the issues leading ideas, specifically Tal's suggestion.

Thanks
msg410461 - (view) Author: FeRD (Frank Dana) (ferdnyc) * Date: 2022-01-13 04:40
Readding Tal to the nosy list, since my previous comment was inadvertently accompanied by an eviction! (Sorry about that.)
History
Date User Action Args
2022-01-13 09:18:22AlexWaygoodsettype: behavior
2022-01-13 04:40:13ferdnycsetnosy: + taleinat
messages: + msg410461
2022-01-08 21:43:57jacksonbrummell1setmessages: + msg410121
2022-01-08 10:49:20ferdnycsetnosy: - taleinat
messages: + msg410093
2022-01-08 10:21:22taleinatsetnosy: + taleinat
messages: + msg410091
2022-01-08 10:10:24ferdnycsetmessages: + msg410088
2022-01-08 09:54:00jacksonbrummell1setmessages: + msg410087
2022-01-08 09:36:56jacksonbrummell1setkeywords: + patch
stage: patch review
pull_requests: + pull_request28683
2022-01-08 09:12:53jacksonbrummell1setnosy: + jacksonbrummell1
messages: + msg410085
2022-01-07 18:38:27eric.araujosetnosy: + eric.araujo
messages: + msg409997
2022-01-07 10:13:50iritkatrielsetkeywords: + easy
2022-01-06 12:57:08ferdnyccreate