[Distutils] Q about best practices now (or near future)

[Nick Coghlan]

On 18 Jul 2013 08:18, "Brett Cannon" <brett at python.org> wrote:
>
>
>
>
> On Wed, Jul 17, 2013 at 6:12 PM, Nick Coghlan <ncoghlan at gmail.com> wrote:
>>
>>
>> On 18 Jul 2013 06:24, "Oscar Benjamin" <oscar.j.benjamin at gmail.com>
wrote:
>> >
>> > On 17 July 2013 17:59, Brett Cannon <brett at 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?).

It would make sense to have targeted sections for "I am...":

-... a new developer on Windows
-... a new developer on Mac OS X
-... a new developer on Linux
-... an experienced Python developer on Windows
-... an experienced Python developer on Mac OS X
-... an experienced Python developer on Linux
-... an experienced developer, new to Python, on Windows
-... an experienced developer, new to Python, on Mac OS X
-... an experienced developer, new to Python, on Linux

Cheers,
Nick.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/distutils-sig/attachments/20130718/726300ef/attachment.html>