Python 2.6 saw the introduction of per user site-packages directory for easy installation of Python packages into a guaranteed location in which the user has appropriate permissions.

http://bugs.python.org/issue1799
http://www.python.org/dev/peps/pep-0370/
http://docs.python.org/whatsnew/2.6.html#pep-370-per-user-site-packages-directory

With it came a new option available in distutils-powered setup.py scripts, "--user". It has been a year since this feature was introduced, yet no documentation has appeared in the official Python Documentation other than in the "What's New" document. Specifically, this option should appear and be documented in the "Installing Python Modules" document.

http://docs.python.org/install/

It would be very helpful if the documentation described the advantages of using this option over "--home" and "--prefix".

I am not the first user to notice this gap in the documentation, e.g.,

http://www.devx.com/opensource/Article/42353/1763

however, I couldn't find any bugs open for this issue so I have created this new one.