python / python/cpython

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

Đang mở
#141,924 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Chưa có ai nhận issue này.

docs
Ngôn ngữ chính
Python
Star
77.2k
Fork
35.9k
Chỉ số merge pull request
Chỉ số pull request đang chờ

Mô tả

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

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Hướng nghiên cứu

Bắt đầu trong phần “The Module Search Path” của Python Tutorial và xem lại đoạn về sys.path. Trước tiên, hãy kiểm tra PR được liên kết gh-141935, sau đó xác nhận rằng các hành vi đường dẫn thủ công và tự động được tách riêng hoặc được phân biệt rõ ràng, để phần văn bản hoàn chỉnh của tutorial cải thiện tính rõ ràng mà không đưa vào các khẳng định không có cơ sở hỗ trợ.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Đánh giá

Công nghệ
python
Lĩnh vực
documentation
Loại issue
Tài liệu
Độ khó
1/5
Thời gian dự kiến
Dưới một giờ
Mức độ hoạt động
Đình trệ
Độ rõ ràng
Đặc tả rõ ràng
Mức phù hợp với người mới
25/100

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.