On Wed, Jul 17, 2013 at 6:12 PM, Nick Coghlan <ncoghlan@gmail.com> wrote:

On 18 Jul 2013 06:24, "Oscar Benjamin" <oscar.j.benjamin@gmail.com> wrote:
>
> On 17 July 2013 17:59, Brett Cannon <brett@python.org> wrote:
> >
> > But it also sounds like that project providing wheel distributions is too
> > early to include in the User's Guide.
>
> There are already many guides showing how to use distutils/setuptools
> to do things the old way. There are also confused bits of
> documentation/guides referring to now obsolete projects that at one
> point were touted as the future. It would be really good to have a
> guide that shows how the new working with wheels and metadata way is
> expected to work from the perspective of end users and package authors
> even if this isn't fully ready yet.
>
> I've been loosely following the packaging work long enough to see it
> change direction more than once. I still find it hard to see the
> complete picture for how pip, pypi, metadata, setuptools, setup.py,
> setup.json, wheels and sdists are expected to piece together in terms
> of what a package author is expected to do and how it affects end
> users. A guide (instead of a load of PEPs) would be a great way to
> clarify this for me and for the many others who haven't been following
> the progress of this at all.

That's exactly what the packaging guide is for. It just needs volunteers to help write it.

PEP 426 goes into a lot of detail on the various things that are supported, but a key thing to keep in mind is that metadata 2.0 is a 3.4.1 time frame idea, purely for resourcing reasons. The bundling proposed for 3.4 is about blessing setuptools & pip as the "obvious way to do it". Not the *only* way to do it (other build systems like d2to1 work, they just need a suitable setup.py shim, and other installers are possible too), just the obvious way.

As of right now the User's Guide doesn't mention using setuptools for building (beyond an empty header listing) and goes with the old distutils setup.py approach. It also words things like you don't know how to really use Python and are starting a project entirely from scratch.

I think for the rewrite to move forward someone's going to need to own each part and specify upfront what assumptions are being made about the audience (e.g. they know what a package is and how to create one, etc.) and their abilities (can you say ``curl <url to ez_setup.py> | python`` to them and thus just link to the setuptools docs for installation?).