People use custom Python builds setting PYTHONHOME and PYTHONPATH to these custom builds. This may be expected to break running system Python binary but it also unexpectedly breaks various applications which also embed Python:

$ echo foo >site.py; export PYTHONPATH=.
$ gdb
Traceback (most recent call last):
  File "./site.py", line 1, in <module>
    foo
NameError: name 'foo' is not defined
$ _

It is not obvious to the user who even already forgot about custom PYTHONPATH why GDB breaks.

Standard Fedora applications may link with system libpython incompatible with the PYTHONHOME/PYTHONPATH files for the other Python version. Python does not keep the scripts too compatible across Python versions.

This issues was discussed first for GDB upstream:
[RFA] ignore PYTHONHOME environment variable.
http://sourceware.org/ml/gdb-patches/2010-11/msg00328.html
http://sourceware.org/ml/gdb-patches/2010-12/msg00214.html
http://sourceware.org/ml/gdb-patches/2011-01/msg00307.html
http://sourceware.org/ml/gdb-patches/2012-05/msg00710.html
(first mail of the thread in each month)
Then also in Fedora:
https://fedorahosted.org/fesco/ticket/858
This Python issue would not be filed by the user if it gets resolved:
Issue12140

Exactly the same problem exists for many other apps, yum for all

$ echo foo >site.py; PYTHONPATH=. yum list bash
Traceback (most recent call last):
  File "./site.py", line 1, in <module>
    foo
NameError: name 'foo' is not defined
$ _

Various proposal have been, applicable possibly in some combination together:

 * Ignore PYTHONHOME/PYTHONPATH for embedded applications. (dot)
 * Ignore PYTHONHOME, use only GDB_PYTHONHOME (if set). This proposal is not applicable for all applications in general.
 * Print warning if PYTHONHOME/PYTHONPATH is set.
 * Recover from Python startup failure and suppress the environment vars.
   or Recover from Python startup failure and disable the Python support, if possible.
 * Should the special care affect PYTHONHOME? Differently for PYTHONPATH? What about PYTHONVERBOSE and other PYTHON* settings? 

How should get PYTHONHOME/PYTHONPATH inherited into child processes, if any (debuggees in the GDB case).

Another question is whether the behavior should be the same if upstream application has been linked with non-system libpython location.

An alternate idea would be to recommend more strongly in the doc that people should not shadow standard library module names (in your example, site).

This site.py is only an example how it can happen.  In reality it is due to .py files intended for incompatible version of Python.  I am not a Python programmer to have some appropriate incompatible code at hand.

> This site.py is only an example how it can happen.
site is special, as it’s one of the modules imported during Python startup.  Can you reproduce the bug with the same file named os.py?  (I expect you can.)  Can you reproduce with spam.py?  (I think you can’t.)

I think it is up to each embedding application to decide if it wants to respect the environment variables or not.  I don't think that's a decision that core can make.

Now, if we aren't providing an easy way for an embedding application to make that decision, that might be something we could fix.  But I suspect we are (I don't know the C API well enough to say for sure).

I fully agree with site.py/os.py/spam.py but I find it offtopic for this Issue.

I do not find too important if some unsetenv/setenv gets called by the app or by libpython.  But the rules should apply for every embedded app the same, the Fedora ticket is suggesting new PEP (Informational) for it.

An informational PEP sounds like exactly what I said: each application needs to decide.  The PEP would provide the information on which to base that decision, and suggestions for how to do it.

An informational PEP on best practices for embedding sounds like a great idea to me.  I hope someone will write one.

It wouldn't be a PEP, it would be an addition to the embedding docs:
http://docs.python.org/extending/embedding.html

For the more general breakage due to PYTHONHOME and PYTHONPATH, yeah, global environment variables are bad, particularly when an OS relies on tools written in (or embedding) Python.

That's the reason virtualenv (and 3.3's forthcoming venv) are a preferred alternative - they give you a space to play in that shouldn't break your system Python or apps that embed it.

> I fully agree with site.py/os.py/spam.py but I find it offtopic for this Issue.

I don’t understand this message :)  There is nothing to agree with or judge on or off-topic; I was trying to understand the root of the bug and really asking you in good faith to try two things to see if my idea was right.

While it should be documented this is not only a docs issue.  It should be solved in some way during runtime.

No it shouldn't.  As mentioned in the Fedora thread you linked, this is no different than the user setting LD_LIBRARY_PATH to something that screws up a system installed program.

If we don't expose the mechanism behind -E to embedding applications via
the C API, then a non-docs change may be needed. However, writing (or at
least trying to write) the relevant docs is a good way to check whether or
not that is the case.