python / python/cpython

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

Offen
#141,924 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Dieses Issue hat noch niemand übernommen.

docs
Vorherrschende Sprache
Python
Sterne
77.2k
Forks
35.9k
PR-Merge-Kennzahlen
PR-Kennzahlen ausstehend

Beschreibung

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

Beitragsleitfaden

Beitragsleitfaden öffnen

Erste Schritte

  1. Lies das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreib ins Issue, dass du es übernimmst — das erspart doppelte Arbeit.
  3. Forke das Repository und arbeite in einem Branch.
  4. Öffne einen Pull Request, der die Issue-Nummer nennt.

Rechercherichtung

Beginnen Sie im Abschnitt „The Module Search Path“ des Python Tutorial und überprüfen Sie den Absatz über sys.path. Prüfen Sie zuerst den verknüpften PR gh-141935 und bestätigen Sie anschließend, dass das manuelle und das automatische Pfadverhalten getrennt oder ausdrücklich voneinander unterschieden werden, wobei der fertige Tutorialtext die Klarheit verbessert, ohne unbelegte Behauptungen einzuführen.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
python
Bereich
documentation
Issue-Typ
Dokumentation
Schwierigkeit
1/5
Geschätzter Aufwand
Unter einer Stunde
Aktivitätsstatus
Veraltet
Klarheit
Klar beschrieben
Anfängerfreundlichkeit
25/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.