Two unrelated ideas mixed in one paragraph of the tutorial (`sys.path` section)
還沒有人認領這個 Issue。
- 主要語言
- Python
- 星號
- 77.2k
- 分支
- 36k
- PR 合併指標
- PR 指標待擷取
描述
In the “The Module Search Path” section of the Python Tutorial, the following paragraph mixes two unrelated ideas in a way that makes it hard to understand:
After initialization, Python programs can modify :data:
sys.path. The
directory containing the script being run is placed at the beginning of the
search path, ahead of the standard library path. This means that scripts in that
directory will be loaded instead of modules of the same name in the library
directory. This is an error unless the replacement is intended. See section
:ref:tut-standardmodulesfor more information.
The first sentence describes the fact that Python programs can modify sys.path manually after initialization. The following sentences describe a separate and independent behavior: the directory of the executed script is automatically placed at the beginning of the module search path, which may cause shadowing of library modules with the same name.
These two behaviors are not logically connected yet are presented within a single paragraph without any transition. This may lead readers to incorrectly assume a relationship between manual modification of sys.path and the automatic placement of the script directory.
Suggested improvement
Split this paragraph into two separate paragraphs, or add an explicit transition indicating that these are independent aspects of module lookup behavior. This would improve clarity and reduce potential confusion for readers.
It may also be worth briefly noting (in a separate sentence) that manually modifying sys.path can sometimes be useful, but may also lead to import-related issues if misused.
Linked PRs
- gh-141935
貢獻指南
從這裡開始
- 先讀完整個 Issue,再讀專案的貢獻指南。
- 在 Issue 下留言說明你要接手 —— 這能避免兩個人做同樣的事。
- Fork 儲存庫,在一個分支上完成修改。
- 送出 Pull Request,並在描述裡引用這個 Issue 編號。
研究方向
從 Python Tutorial 的「The Module Search Path」章節開始,檢視關於 sys.path 的段落。先確認連結的 PR gh-141935,接著確認手動與自動路徑行為已分開或明確區分,同時確保完成後的教學文字能提升清晰度,而不引入缺乏依據的說法。
由索引模型根據 Issue 內容生成。
評估
- 技術堆疊
- python
- 領域
- documentation
- Issue 類型
- 文件
- 難度
- 1/5
- 預估耗時
- 1 小時以內
- 活躍度
- 停滯
- 描述清晰度
- 描述清楚
- 新手友好度
- 25/100