On Nov 6, 2009, at 12:53 PM, Guido van Rossum wrote:

>  I just found this comment on my blog. People have told me this in
>  person too, so I believe it is real pain (even if the solution may be
>  elusive and the suggested solutions may not work). But I don't know
>  how to improve the world. Is the work on distutils-sig going to be
>  enough? Or do we need some other kind of work in addition? Do we need
>  more than PyPI?

In my experience, when users say this, they just mean "I tried  
easy_install and it broke".

PyPI doesn't have some deep, fundamental, architectural issue that  
prevents it from working.  The user experience of it is just buggy.   
Consider the difference between these two pages:

     http://docs.webfaction.com/software/perl.html
     http://docs.webfaction.com/software/python.html

Note that the 'python' page is more than twice as long, lists a ton of  
different installation options, and includes a gigantic  
"troubleshooting" section that apparently isn't necessary for perl.   
Note also that the Perl page is just a series of steps describing how  
to invoke the one installation mechanism, but the Python page is a  
hodgepodge of qualified instructions describing different possible  
mechanisms you can try.  It also appears that webfaction has modified  
the default environment's configuration to make their  
"troubleshooting" section *shorter* than it would have to be for more  
general Python software installation instructions.

The default behavior of most Python installation mechanisms - to my  
knowledge, 'python setup.py install', 'easy_install', and 'pip', will  
all raise exceptions by default on UNIX-y platforms, unless you're  
root.  On Windows (since a higher percentage of the user population  
walks around with admin rights all the time), the default invocations  
described by many project web pages will work if the installation is  
pure-python or if the author remembered to provide a Windows binary  
egg, but a common failure mode is "you don't have a compiler".   
Similarly, on a Mac, you have to have Xcode installed, although Python  
itself works fine if you don't, so it seems like you don't.

Many of these tools *would* work by default with a small amount of  
configuration, a couple of environment variables, and clearer error  
messages that indicate (A) *that* you need to install a C compiler and  
(B) *where* you need to go to get a C compiler.

One project that would help a lot is just a "easy python setup"  
documentation project that describes, as simply as possible, in large  
fonts, how to get a working Python setup that adheres to a few  
conventions.  Just include the 2 lines of .bashrc and explain how to  
add them; don't debate the merits of ~/bin vs. ~/.local/bin vs. ~/opt/ 
bin (although come on, ~/.local/bin/ is _clearly_ the right name for  
it), just pick one for each platform and provide clear step-by-step  
instructions for getting it to work. "put this in your ~/.bashrc:  
<really big PRE tag with shell setup in it> .  restart your shell."   
Anybody who has selected an alternate shell or done some other prior  
configuration will need to adjust their expectations, but we can worry  
about supporting unusual configurations when the community has a good  
answer for the default configuration.  (Although this is a good reason  
to do this as documentation and not attempt to write an  
autoconfigurating tool: an autoconfigurating tool needs to understand  
every possible nuance of the environment, but advanced users can  
notice which parts of the short document might not apply to them.)

I feel like I might be repeating this a bit much, but it's a really  
important point: many of the things I'm talking here are *not* about  
getting the code right as part of a Python tool, but in providing an  
easy, manageable way to integrate with _other_ tools that are outside  
of our collective control as Python package authors: the dynamic  
linker, the shell, the file manager and the C compiler (or lack  
thereof).  By providing a default user-home-directory installation  
location, Python itself is already doing almost as much as it can; if  
easy_install started installing things into that location by default  
*without* any of this bootstrapping documentation (or a very, very  
carefully written tool to do the bootstrapping for you) then importing  
pure Python packages might work great but scripts would be broken and  
any external shared libraries required by Python modules (even if they  
built correctly) would just give you an ImportError.

Once we have some kind of working consensus on this setup, the tools  
can change to support it: easy_install can default to installing  
things in the user's home directory in the case that (A) the  
environment is set up for it and (B) the user isn't an administrator.   
If the environment *isn't* set up, instead of spitting out twelve  
paragraphs explaining how really you should have read-write access to  
the location where your pth files are stored and a link into the  
middle of some dense technical reference documentation, it can just  
say "read this page" and link to something that says "HERE IS A .REG  
FILE THAT WILL FIX YOUR PYTHON.  CLICK ON IT AND DO NOT ASK QUESTIONS."

If such a document existed, it would also be good for PyPI to link to  
it prominently so that if a user comes across a package by way of a  
Google search that ends at PyPI, there is a clear set of instructions  
as to how to get it on their computer.

There's also something that everyone on this list can do today: every  
python package author should have a clean user account, OS install,  
virtual machine, or whatever; some otherwise pristine environment  
where they try to follow their own installation instructions *without*  
any of their usually available tools or tricks for setting up a python  
development environment, and without administrator access.  One thing  
that always strikes me about Python hackers is that we all have  
existing setups to support our own personal style of development, and  
so we are somewhat insulated from the new-user-experience pain.  I  
think if everyone on this list did this regularly on a package with a  
dozen or so dependencies, the situation would rapidly improve  
regardless of my other recommendations :).

_______________________________________________
Distutils-SIG maillist  -  Distutils-SIG@[...].org
http://mail.python.org/mailman/listinfo/distutils-sig