[issue11948] Tutorial/Modules - small fix to better clarify the modules search path

[Terry J. Reedy]

Terry J. Reedy  added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11948] Tutorial/Modules - small fix to better clarify the modules search path

[Eric Snow]

Eric Snow  added the comment:

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.  :)

--
nosy: +eric.snow

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11948] Tutorial/Modules - small fix to better clarify the modules search path

[Sandro Tosi]

Sandro Tosi  added the comment:

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

--
resolution:  -> fixed
stage: commit review -> committed/rejected
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11948] Tutorial/Modules - small fix to better clarify the modules search path

[Roundup Robot]

Roundup Robot  added the comment:

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

--
nosy: +python-dev

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11948] Tutorial/Modules - small fix to better clarify the modules search path

[Terry J. Reedy]

Terry J. Reedy  added the comment:

Sandro, I think you can apply this.

--
versions:  -Python 3.1

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11948] Tutorial/Modules - small fix to better clarify the modules search path

[Éric Araujo]

Éric Araujo  added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11948] Tutorial/Modules - small fix to better clarify the modules search path

[Terry J. Reedy]

Changes by Terry J. Reedy :


--
stage: patch review -> commit review

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11948] Tutorial/Modules - small fix to better clarify the modules search path

[Terry J. Reedy]

Terry J. Reedy  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11948] Tutorial/Modules - small fix to better clarify the modules search path

[Éric Araujo]

Éric Araujo  added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11948] Tutorial/Modules - small fix to better clarify the modules search path

[Terry J. Reedy]

Terry J. Reedy  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11948] Tutorial/Modules - small fix to better clarify the modules search path

[Éric Araujo]

Éric Araujo  added the comment:

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?

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11948] Tutorial/Modules - small fix to better clarify the modules search path

[Sandro Tosi]

Sandro Tosi  added the comment:

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!

--
Added file: http://bugs.python.org/file21972/issue11948-v5.patch

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11948] Tutorial/Modules - small fix to better clarify the modules search path

[Raymond Hettinger]

Raymond Hettinger  added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11948] Tutorial/Modules - small fix to better clarify the modules search path

[Georg Brandl]

Georg Brandl  added the comment:

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

--
nosy: +georg.brandl

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11948] Tutorial/Modules - small fix to better clarify the modules search path

[Terry J. Reedy]

Terry J. Reedy  added the comment:

I agree with both Raymond and David's suggestion.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11948] Tutorial/Modules - small fix to better clarify the modules search path

[R. David Murray]

R. David Murray  added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11948] Tutorial/Modules - small fix to better clarify the modules search path

[Terry J. Reedy]

Terry J. Reedy  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11948] Tutorial/Modules - small fix to better clarify the modules search path

[Sandro Tosi]

Sandro Tosi  added the comment:

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 :)

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11948] Tutorial/Modules - small fix to better clarify the modules search path

[Raymond Hettinger]

Raymond Hettinger  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11948] Tutorial/Modules - small fix to better clarify the modules search path

[Raymond Hettinger]

Raymond Hettinger  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11948] Tutorial/Modules - small fix to better clarify the modules search path

[R. David Murray]

R. David Murray  added the comment:

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?

--
nosy: +r.david.murray

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11948] Tutorial/Modules - small fix to better clarify the modules search path

[Sandro Tosi]

Sandro Tosi  added the comment:

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.

--
Added file: http://bugs.python.org/file21946/issue11948-v4.patch

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11948] Tutorial/Modules - small fix to better clarify the modules search path

[Raymond Hettinger]

Raymond Hettinger  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11948] Tutorial/Modules - small fix to better clarify the modules search path

[Sandro Tosi]

Sandro Tosi  added the comment:

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

--
Added file: http://bugs.python.org/file21944/issue11948-v3.patch

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11948] Tutorial/Modules - small fix to better clarify the modules search path

[Ezio Melotti]

Ezio Melotti  added the comment:

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.

--
nosy: +ezio.melotti

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11948] Tutorial/Modules - small fix to better clarify the modules search path

[Sandro Tosi]

Sandro Tosi  added the comment:

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

--
Added file: http://bugs.python.org/file21913/issue11948-v2.patch

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11948] Tutorial/Modules - small fix to better clarify the modules search path

[Éric Araujo]

Éric Araujo  added the comment:

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

--
nosy: +eric.araujo

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11948] Tutorial/Modules - small fix to better clarify the modules search path

[Terry J. Reedy]

Terry J. Reedy  added the comment:

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

--
nosy: +terry.reedy

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11948] Tutorial/Modules - small fix to better clarify the modules search path

[Sandro Tosi]

Changes by Sandro Tosi :


Added file: http://bugs.python.org/file21836/issue11948.patch

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11948] Tutorial/Modules - small fix to better clarify the modules search path

[Sandro Tosi]

Sandro Tosi  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11948] Tutorial/Modules - small fix to better clarify the modules search path

[Raymond Hettinger]

Raymond Hettinger  added the comment:

It would be better to drop the introductory phrase entirely.

--
nosy: +rhettinger
priority: normal -> low

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11948] Tutorial/Modules - small fix to better clarify the modules search path

[Sandro Tosi]

New submission from Sandro Tosi :

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.

--
assignee: docs@python
components: Documentation
files: tutorial_modules_actually.patch
keywords: patch
messages: 134704
nosy: docs@python, sandro.tosi
priority: normal
severity: normal
stage: patch review
status: open
title: Tutorial/Modules - small fix to better clarify the modules search path
versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3
Added file: http://bugs.python.org/file21826/tutorial_modules_actually.patch

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com