Following up http://mail.python.org/pipermail/docs/2011-April/004029.html here's a small patch (applicable on all the active branches) to "actually" :) connects the two paragraphs about modules search path.

It would be better to drop the introductory phrase entirely.

Hi Raymond, thanks for looking into it! What do you think of this patch? I tried to save what I think was nice in the first paragraph and collapse it into the second one.

I believe the patch produces the following as the first sentence

"When a module named :mod:`spam` is imported, the interpreter searches for a file named :file:`spam.py` in a list of directories given by the variable ``sys.path`` which is initialized from the directory containing the input script (or the current directory), :envvar:`PYTHONPATH` (a list of directory names, with the same syntax as the shell variable :envvar:`PATH`) and the installation-dependent default."

This is more that a 'mouthful', especially for a tutorial, and I think is should be split into two:
variable ``sys.path``.  ``Sys.path`` is initialized ...

One caveat to Terry’s suggestion: never ever change the case of a Python identifier or keyword (“Sys”).

Here's attached the patch including Terry's suggestion (gaah, sorry for this late reply).

s/``sys.path``/:data:`sys.path`/ (or whatever turns that into a link).
I also don't like the "Python programs that know what they're doing" bit.
The list of places where the modules are searched could be a bullet list.

What about the attached (v3) patch? the "This allows...experts hands." part can be remove completely if can be mis-interpreted.

Please don't make these kind of changes.  Guido has been clear that the docs need to affirmatively state what the language does.  

Except for certain security risks or segfault risks, the docs should avoid wording along the lines of "feature x is dangerous" or "experts only".  These kind of value judgements belong in blogs and wikis, not in the core documentation which should simply focus on what the language does and examples of how to use it effectively.

Sorry Raymond for the bad editing, I was confused by thinking 'tutorial' is particularly meant for new-coming people. Anyhow, sorry again: I attach a patch removing the badworded part.

Please let me know if anything else is missing or needs fixing.

Thanks for your check & time.

Raymond: I haven't read the examples in detail so I don't have an opinion on the appropriateness of the text, but I'm curious: while what you say certainly applies to the Language Reference, does it also apply to the Tutorial?

The tutorial is meant for newcomers.  The experience needs to be positive and not leave the reader with worries that something bad will happen if they make a misstep.

People commonly use the tutorial to evaluate the language as a whole.  The tutorial needs to show people what the language is capable of doing.  It should not create the impression that all its features are dangerous and should only be used by experts.

One other stylistic note.  The tone of the tutorial (and all the docs) needs to be respectful of the readers intelligence.  We don't presume that the readers are stupid.  We lay out the relevant information, show motivating use cases, provide glossary links, and do our best to connect-the-dots, but don't talk down them or waste their time.

The recent doc patch for using the in-operator instead of str.find borders on the edge of not giving readers credit for being able to make trivial inferences about the API.

Raymond, thanks for explaining the reasoning behind your replies, it really helps me understand the "spirit" behind python :)

That said, and trying to be a bit more pragmatical, what are the next steps to make this patch acceptable? It's kinda of a small patch, and I honestly didn't foresee the long ping-pong of corrections I received :)

Sandro, import is a somewhat dark corner of Python that newcomers and even experienced people ofter trip over. So getting the text both correct and clear is worth some thought.

I just noticed that the text is only true for Python-coded modules and not for built-in modules. I discovered this by setting sys.path to {} and importing itertools. It works. It appears that Python first searches for builtins -- I created itertools.py and it did not mask the builtin. If there were a Lib/itertools.py which imported _itertools, it would have been masked. So it appears that the text should begin

"When a module named :mod:`spam` is imported, the interpreter first searches for a built-in module with that name. If not found, it then searches for a file ..."

I suggest changing
"This allows Python programs to modify or replace the module search path."
to
"After initialization, Python programs can modify sys.path."

and changing the followup

" Note that because the directory containing the script being run is on the search path, it is important that the script not have the same name as a standard module, or Python will attempt to load the script as a module when that module is imported.  This will generally be an error."

to something more like

"Because the directory containing the script being run is placed at the beginning of the search path, ahead of the standard library path, the script and other scripts in that directory should not have the same name as a standard library module unless one really intends for the script to be loaded in place of the standard library module."

or perhaps

"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."

I think the change to warn about all possibly conflicting scripts in the directory is needed because a common problem people have is more like

import random
a = random.choice('abc')

raising AttributeError ("O python-list, why???") because there is a forgotten random.py in the same directory.

Raymond: yes, thanks for the clear guidance.  Perhaps it could be added to Documenting Python, perhaps in the Style Guide chapter?

I agree with both Raymond and David's suggestion.

+1 to the guidance, and to adding it to the doc style chapter.

See http://bugs.python.org/issue12047

I first would like to apologize if my comments were interpreted like I'd like to do a poor quality job, that's actually the opposite! I just get caught by surprise how a simple change in a word to better join two paragraphs grows up like this - but that's perfectly fine and understandable we want to be as detailed and precise as possible

Here's the fifth version of the patch, including Terry's suggestions - thanks!

About Terry’s suggestion to change "This allows Python programs to modify or replace the module search path" to "After initialization, Python programs can modify sys.path": IMO the old text is talking about intent (modify the module search path) and the replacement about implementation (modify sys.path).  I prefer the former; what do you think?

I disagree (else I would not have suggested change ;-). First, I dislike 'This allows' on stylistic grounds, when there is a better alternative. It is rather wishy-washy: 'this allows' -- so what? As for the rest -- why not be specific? The whole paragraph is about sys.path, so it is not an hidden detail.

> First, I dislike 'This allows' on stylistic grounds
Fully agreed, sir!

> The whole paragraph is about sys.path, so it is not an hidden detail.
It may be that I miss context; I don’t actually know whether the paragraph is only about sys.path or about module search in general.  Apologies if my comments are only noise.  This is my last proposal:

“After initialization, Python programs can modify sys.path to modify or replace the module search path (except for built-in modules)”

If it’s redundant, then +1 to your earlier suggestion.

Sandro, thank you for sticking with this. Seemingly simples issues sometimes 'explode' a bit. Having reviewed the patch, I think the it is ready to be committed.

Éric: if you were to commit this and, in the process, wanted to change sys.path back to 'this module search path' ('this' instead of 'the' to refer back to the definition of sys.path just given), I would not object.

I think I’d better leave this one to Terry or Raymond.

Sandro, I think you can apply this.

New changeset d01208ba482f by Sandro Tosi in branch '2.7':
Issue #11948: clarify modules search path
http://hg.python.org/cpython/rev/d01208ba482f

New changeset 6d663db63705 by Sandro Tosi in branch '3.2':
Issue #11948: clarify modules search path
http://hg.python.org/cpython/rev/6d663db63705

New changeset 93769b8ff40b by Sandro Tosi in branch 'default':
Issue #11948: merge with 3.2
http://hg.python.org/cpython/rev/93769b8ff40b

Thanks Terry for the ping, I've just committed it - thanks again to everyone for the help/suggestions.

FYI: unless importlib took undue liberties (unlikely), frozen modules also precede path-based modules.  See the implicit additions to sys.meta_path in Lib/importlib/_bootstrap.py.

Whether or not to include a mention of frozen modules in the tutorial...I'll leave that to you.  :)

Definitely out-of-scope for the tutorial. I consider this akin to monkey patching imported modules.