python / python/cpython

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

Aberta
#141,924 0 comentários 0 reações 0 responsáveis Ver no GitHub

Ninguém assumiu esta issue ainda.

docs
Linguagem predominante
Python
Estrelas
77.2k
Forks
36k
Métricas de merge de PRs
Métricas de PR pendentes

Descrição

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

Guia de contribuição

Abrir o guia de contribuição

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Direção de pesquisa

Comece na seção “The Module Search Path” do Python Tutorial e revise o parágrafo sobre sys.path. Verifique primeiro o PR vinculado gh-141935 e, em seguida, confirme que os comportamentos manual e automático dos caminhos estejam separados ou explicitamente diferenciados, com o texto final do tutorial melhorando a clareza sem introduzir afirmações sem suporte.

Escrita pelo modelo de indexação a partir do texto da issue.

Avaliação

Stack de tecnologia
python
Domínio
documentation
Tipo de issue
Documentação
Dificuldade
1/5
Tempo estimado
Menos de uma hora
Status de atividade
Estagnada
Clareza
Claramente especificada
Facilidade para iniciantes
25/100

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.