On Tue, Oct 26, 2010 at 11:18 AM, Guido van Rossum <guido@python.org> wrote:
> On Tue, Oct 26, 2010 at 8:13 AM, Alexander Belopolsky
> <alexander.belopolsky@gmail.com> wrote:
>> The one demo that I want to find a better place for is Demo/turtle.
>
> Sure, go for it. It is a special case because the turtle module is
> also in the stdlib and these are intended for a particular novice
> audience. Anything we can do to make things easier for those people to
> get start with is probably worth it. Ideally they could just double
> click some file and the demo would fire up, with a command-line
> alternative (for the geeks among them) e.g. "python -m turtledemo" .
>
> --
> --Guido van Rossum (python.org/~guido)
>
-- "Move Demo scripts under Lib"
http://mail.python.org/pipermail/python-ideas/2010-October/008397.html

Before I prepare a patch, I would like to get an agreement on the location of the demo package.  In the order of my preference:

1. turtle.demo Pro: obvious relationship to turtle.  Cons: require converting turtle.py to a package.

2. turtledemo  Pro: BDFL's suggestion; "Flat is better than nested".  Cons: relationship to turtle module is less obvious than in #1; stdlib namespace pollution. (Turtle invasion! :-)

3. demo.turtle - probably not a good idea if not as a part of a general Demo reorganization.

Note that while I listed conversion of turtle.py to a package as a cons, it may not be a bad idea on its own.  For example, toolkit abstraction naturally belongs to submodules and procedural interface belongs to package level while OOP classes may be separated into submodules.  While I am not proposing any such changes as a part of this ticket, it may not be a bad idea to take the first step and rename turtle.py to turtle/__init__.py.

IMO converting turtle.py into a package, unless that's already planned anyway, is not a good project to undertake right now.  (OTOH the demo itself already is a package, less an __init__.py file.)  Note that the turtle module already runs some demo when invoked as a script -- maybe this can be made to fire up the demo viewer instead?

On Tue, Oct 26, 2010 at 12:00 PM, Guido van Rossum
<report@bugs.python.org> wrote:
..
> IMO converting turtle.py into a package, unless that's already planned anyway, is not a good project
> to undertake right now.

What are your reasons? I don't necessarily disagree, but want to
weight pros and cons.  It does not seem like a hard thing to do:
rename turtle.py to turtle/__init__.py and add __main__.py.   As I
said, I don't intend to anything more than that in the first step.

>  (OTOH the demo itself already is a package, less an __init__.py file.)

Unfortunately it also relies on being run from directory containing
the main script, so converting it into a proper package is a bit more
involved than renaming the directory and adding an empty __init__.py
file.  Still it is not that hard.

>  Note that the turtle module already runs some demo when invoked as a script
> -- maybe this can be made to fire up the demo viewer instead?

Yes, I wanted to do that as well.  Note that in this case, it would be
natural to move turtleDemo.py code into turtle/__main__.py.   I would
also like to be able to run individual tdemo_* scripts without the
demo viewer or with an alternative viewer.  Some naming decisions have
to be made for that as well:

$ python -m turtle.tdemo_chaos
$ python -m turtle.demo.chaos
$ python -m turtledemo.tdemo_chaos
...

I would like Gregor Lingl's approval of turning turtle.py into a package.  It might make some things harder for novices, e.g. trackebacks and just browsing the source code.

Also many people don't expect to find any code in a file named __init__.py (and most of the time I agree with this).  But the alternative isn't so great either, assuming we'll want strict backwards compatibility (I wouldn't want the instructions in Gregor's or anyone's book to start failing because of this).  You can't rename turtle to turtle/turtle.py either, because then there'd be horrible confusion between turtle/ and turtle.py.

IOW, yes, flat still seems better than nested here!

On Tue, Oct 26, 2010 at 12:31 PM, Guido van Rossum
<report@bugs.python.org> wrote:
..
> I would like Gregor Lingl's approval of turning turtle.py into a package.

Me too. :-)  I added him to the "nosy list".

>  It might make some things harder for novices, e.g. trackebacks and just browsing the source code.

If better tracebacks were the goal, I would start with removing
eval-generated module level functions:

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<string>", line 1, in forward
..
TypeError: can't multiply sequence by non-int of type 'float'

Browsing source code may indeed be complicated by the package
structure.  For example, I often find it difficult to navigate
unittest code once it became a package in the recent versions.
However, simple renaming of turtle.py to turtle/__init__.py is
probably a non-event since novice-oriented environments such as IDEs
are likely to take the user directly to turtle/__init__.py when he or
she clicks on "turtle".

> Also many people don't expect to find any code in a file named __init__.py (and most of the time I
> agree with this).

Well, logging, tkinter, and ctypes are clearly counterexamples to this rule.

>  But the alternative isn't so great either, assuming we'll want strict backwards compatibility (I
> wouldn't want the instructions in Gregor's or anyone's book to start failing because of this).

Backwards compatibility can be restored by use of relative imports as
necessary.  This is the unittest approach where backward compatibility
is paramount.

> You can't rename turtle to turtle/turtle.py either, because then there'd be horrible confusion
> between turtle/ and turtle.py.

Agree.  We have too many turtles already. :-)  On the other hand,
moving turtle object definitions into turtle/pen.py in some distant
future may not be a horrible idea.  (Note that "pen" end "turtle" are
already mostly synonymous.)

> IOW, yes, flat still seems better than nested here!

For a six year old, turtledemo is still nested - just without a dot. :-)

PS: My six year old loves the turtle!

I thought this email-to-roundup bug was fixed some time ago.  The mangled sample session was:

>>> turtle.forward('5 miles')
Traceback (most recent call last):
 File "<stdin>", line 1, in <module>
 File "<string>", line 1, in forward
..
TypeError: can't multiply sequence by non-int of type 'float'

Just an FYI: the python.org installers for Mac OS X install the demos including the turtle demo (which is probably the most useful of the bunch these days) in /Applications/Python m.n/Extras/Demo.  Depending on the default application association for ".py" files (something the user can change using the OS X Finder), double-clicking on the demo files will generally launch them in IDLE.app or with Python Launcher.app.

Various comments:

I usually expect things in stdlib to be usefully importable. Idlelib is clearly an exception.

>> Also many people don't expect to find any code in a file named
>> __init__.py (and most of the time I agree with this).

> Well, logging, tkinter, and ctypes are clearly counterexamples
> to this rule.

I think it a mistake that tkinter.__init__ is huge, about as big as the other 13 modules added together. It makes it really hard to dive into the code.

I think turtledemo would be fine, separate from turtle, if one could import and run things (one at a time) from within the interactive interpreter.

Yeah, I wish unittest hadn't been split up, and I really dislike the organization of the email package, though I think I understand how it came about historically.  So I vote for flat :)

> I think it a mistake that tkinter.__init__ is huge,
> about as big as the other 13 modules added together. 
> It makes it really hard to dive into the code

That is certainly *not* a best practice.

First of all: I'd not like to see turtle.py converted into a package. I think with the turtle module things should be as simple as possible and I don't see any need to put approx. 100kB of code into an __init__.py and be it only because there are hundreds of them and on cannot see from the name what's in there. I do not expect the avarage turtle user to look at the code, but certainly some teachers and instructors do even if they are not python specialists accustomed to the use of packages.

As far as I understood from the discussion the MAIN POINT is to make the turtleDemo accessible as easyly as possible.

So at first this needs a decision to put the demo code into the Windows-Distribution.

The next question is where to put it. In my opinion there are two possibilities.

1) The one mentioned by Alexander in msg119612: a turtledemo directory in Lib. 
2) To put a turtledemo directory into the Tools directory (in some sense the demoViewer is sort of a tool, isn't it.)

I quickly prepared a 'prototypical' collection with a modified viewer, which accounts for some of the arguments which came up in the current  discussion. It contains a turtledemo package. Please download it and have a look.

Each demo can be run by doubleclicking, as a standalone script, as well as from the turtledemo.viewer

If from the above options 1) were chosen or the package is somewhere else in the search path, on can - at the interactive prompt - do things like:

>>> from turtledemo import bytedesign
>>> bytedesign.main()

and also:

>>> from turtledemo import viewer
>>> viewer.run()

Morover one can load the examples into Idle and start them via the run-command. So one has a look at the code and moreover the possibility to make changes and try out, what happens.

I have renamed the sample scripts, omitting the tdemo_ - prefix, as 
this looks nicer (at least for me). The previous version turtleDemo recognized scripts with this suffix as belonging to the demo-suite and
added it to the examples menu. This was necessary because of a script, which cannot be demonstrated in the demo_viewer (two canvases). I changed this in my proposition in the following way: scripts that are in the demodirectory and should not appear in the DemoViewer's example-Menu, should end with _.py or some other extension.

To make the demo_viewer importable creates a special problem: the demos are imported by the demoViewer via the __import__ function, so everyone can add his own demos to the demo-directory and they will show up in the viewer. The original version (and even this one) can do this also for demos in subdirectories when started directly. (I've included as an example the geometry directory). This does't work yet for importing the viewer, I only provided a very clumsy quick and dirty solution and I hope that someone has a better, more bright idea to do this more elegantly and correctly.

Now for something completely different: how to make it easily accessible.

1) Put remarks (and links) into the documentation, near the head of the turtle module's docs. (Referring to 24.5.7)
2) Put a hint into the commentary/docstring of the file turtle.py itself.
3) I do not consider it a good idea to put the viewer.py into the 
if __name__ == "__main__" - part of turtle.py thus replacing the current demo. I think this part should demonstrate the possibilities of the module without recurring to extra use of Tkinter (as the demo viewer does). (I must also confess, that the quality of the code of the viewer, which I programmed back in 2006, does not reach the standards I tried to achieve for turtle.py)
4) BUT I'd find it useful to change this final demo code of turtle.py, so it - in the end - displays a message where to find more demos (i. e. turtledemo) or even to put there a question like ("Do you want to see more demos?") and two "turtle-generated" "buttons": "YES" and "NO". If one chooses "Yes", the turtledemo.viewer would pop up in a separate process.

Please consider this to be a proposal or a contribution. I'm very interested in discussing it further and bringing it to a quick and easy solution for Python 3.2. Unfortunately I'm currently involved in a project (also python-related) with very severe time constraints for the next four to five month. So ideas for enhancing the demoviewer and probably turtle.py have to wait until then and possibly will be an issue for Python 3.3

Best regards,
Gregor

Attached patch, issue10199.diff is mostly a copy of Gregor's turtledemo32.zip, with the main difference being that viewer code is in turtledemo/__main__.py so it can be run with just

$ python -m turtledemo

I would like to commit this before any further improvements.  Just as Gregor, I have many ideas on how to improve the demo, but implementing them would be a subject of a new ticket.

Here is a quick list:

1. Add test_turtledemo to unittests.
2. Add means to run all examples in order without user input.
3. Prune the examples: do we need both "tree" and "forest"?
5. Turn the left panel to the expanded list of tests and add a "show source" button to display source in a separate window.
6. Improve names of examples.   "I_dont_like_tiltdemo" is not really a good name. :-)

Imho it is very important to clarify the name convention for demoscripts to be added to the demo before committing (or at least before the apperance of beta1). It decides about adding scripts to the Examples Menu of the viewer.

We all know, that things once they have found their way into Lib cannot be changed easily afterwards. Guidos argument on backwards compatibility applies. So now is the only point in time to decide about this.

Should we 
- stick with the tdemo_ prefix or 
- change to another pre- or postfix (like eg. bytedesign_demo)
- or should we allow for arbitrary *.py filenames with some exception (e.g. filenames that contain an underscore) to mark files that are not meant as demos for the viewer?

Please note that there are other constraints also for demo_files anyway, like the size of the graphics window and the presence of a main()-function to be called by the viewer. 

I'd like this to be decided actively. 

What do you think?
Best regards,
Gregor

On Wed, Oct 27, 2010 at 2:37 PM, Gregor Lingl <report@bugs.python.org> wrote:
..
> Imho it is very important to clarify the name convention for demoscripts to be added to the demo before committing
> (or at least before the apperance of beta1). It decides about adding scripts to the Examples Menu of the viewer.
>

I would rather separate move under Lib and any other changes.  However
since files are moved anyways, we can use this opportunity for name
changes.

> We all know, that things once they have found their way into Lib cannot be changed easily afterwards. Guido's
> argument on backwards compatibility applies. So now is the only point in time to decide about this.
>

I don't really expect people to import turtledemo.xyz modules in their
programs.  These are designed as stand-alone scripts and I am not
proposing to change that.  We can further warn users about that in the
documentation, but I think it is obvious that demo scripts are not
supposed to be used as production components.

> Should we
> - stick with the tdemo_ prefix or
> - change to another pre- or postfix (like eg. bytedesign_demo)
> - or should we allow for arbitrary *.py filenames with some exception (e.g. filenames that contain an underscore)
>  to mark files that are not meant as demos for the viewer?
>

In the long run, I would like to add a separate template that will
determine the choice of modules for the viewer and allow menu choices
to be different from module names and the order to be different from
alphabetical.  For not, however, I am going to allow any name except
those starting with an underscore or "two_canvases".

Committed in revision 86095.  I included only those demo scripts that are described in the current manual.  I am open to making further improvements prior to bata 1, and will open separate issues to track those.