[Python-ideas] Move Demo scripts under Lib

[Alexander Belopolsky]

On Tue, Oct 26, 2010 at 10:33 AM, Dirkjan Ochtman <dirkjan at ochtman.nl> wrote:
> On Tue, Oct 26, 2010 at 16:00, Alexander Belopolsky
> <alexander.belopolsky at gmail.com> wrote:
>> What do you think?
>
> After browsing through the Demo dir a bit, I came away thinking most
> of these should just be removed from the repository. I think there's
> enough demo material out there on the internet (for example in the
> cookbook), a lot of it of higher quality than what we have in the Demo
> dir right now. Maybe it makes sense to have a basic tkinter app to get
> you started.

The one demo that I want to find a better place for is Demo/turtle.
For a novice-oriented framework that turtle is, it is really a shame
to require

$ cd <whatever>/Demo/turtle
$ python turtleDemo.py

to run the demo.  I would much rather use

$ python demo.turtle

or

$ python turtle.demo

(the later would require converting turtle.py into a package)

> And some of the smaller functions or classes could
> possibly be used in the documentation.

And most likely not be automatically tested contributing to users'
confusion: "I copied it from the documentation and it does not work!"
 See http://bugs.python.org/issue10029 .


> But as it is, it seems silly to
> waste developer time on stuff that few people look at or make use of
> (I'm assuming this from the fact that they have previously been
> neglected).
>
It is debatable what is the cause and what is the effect here.


> Back to the original question: I don't think moving the Demo stuff to
> the Lib dir is a good idea, simply because the Lib dir should contain
> libraries, not applications or scripts.

Introduction of -m option has changed that IMO.  For example, when I
work with recent versions of python, I always run pydoc as python -m
pydoc because pydoc script on the path amy not correspond to the same
version of python that I use.  The trace, timeit, dis and probably
many other useful modules don't even have a corresponding script in
the standard distribution.

> Writing a section for the
> documentation seems a better way to solve the discoverability problem,

What exactly such a section should say?  "In order to find demo
scripts, pleas unpack the source distribution and look under the Demo
directory"?

> testing could be done even in the Demo dir (with more structure if
> need be), and quality control could just as well be exercised in the
> current location.

This is a valid option and if running Demo tests is added to make test
target, it has a fighting chance to work.  However, if Demo test are
organized differently from stdlib module tests, maintaining them will
be more difficult than it needs to be.