python / python/cpython

Two unrelated ideas mixed in one paragraph of the tutorial (`sys.path` section)

未关闭
#141,924 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

还没有人认领这个 Issue。

docs
主要语言
Python
星标
77.2k
派生
35.9k
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-standardmodules for 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

贡献指南

打开贡献指南

从这里开始

  1. 先读完整个 Issue,再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库,在一个分支上完成修改。
  4. 提交 Pull Request,并在描述里引用这个 Issue 编号。

调研方向

从 Python Tutorial 的“The Module Search Path”部分开始,检查关于 sys.path 的段落。先查看链接的 PR gh-141935,然后确认手动和自动路径行为已分开或得到明确区分,同时确保完成后的教程文本能够提高清晰度,而不会引入缺乏依据的说法。

由索引模型根据 Issue 内容生成。

评估

技术栈
python
领域
documentation
Issue 类型
文档
难度
1/5
预计耗时
1 小时以内
活跃度
停滞
描述清晰度
描述清楚
新手友好度
25/100

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。