classification
Title: new turtle module
Type: Stage:
Components: Tkinter Versions: Python 3.0, Python 2.6
process
Status: closed Resolution: accepted
Dependencies: Superseder:
Assigned To: loewis Nosy List: benjamin.peterson, bmiller, glingl, gregorlingl, gvanrossum, loewis
Priority: normal Keywords: patch

Created on 2006-06-28 00:50 by gregorlingl, last changed 2008-06-04 06:30 by loewis. This issue is now closed.

Files
File name Uploaded Description Edit
xturtle.py gregorlingl, 2006-06-28 00:50 code of xturtle.py
xturtle-docs.txt gregorlingl, 2006-06-29 22:09 documentation for xturtle.py
xturtle.py glingl, 2008-03-17 19:01 xturtle.py version 0.95a0
xturtle-docs.txt glingl, 2008-03-17 19:05 documentation for xturtle.py v0.95a0
xturtle.cfg glingl, 2008-03-17 19:16 configuration file for xturtle
whatsnew.txt gregorlingl, 2008-03-18 01:49 What's new in xturtle0.95 (compared to 0.91)
turtle.zip gregorlingl, 2008-06-01 17:35 turtle module including docs and demos
Messages (14)
msg50549 - (view) Author: Gregor Lingl (gregorlingl) Date: 2006-06-28 00:50
The file, at present named xturtle.py is a
reimplementation of turtle.py with additional features,
among them:

-Better animation of the turtle movements, especially
of turning the turtle. So the turtles can more easily
be used as a visual feedback instrument by the
(beginning) programmer.
-Different turtle shapes, gif-images as turtle shapes,
user defined and user controllable turtle shapes, among
them compound (multicolored) shapes.
-Fine control over turtle movement and screen updates
via delay(), and enhanced tracer() and speed(),
update()  methods.
-Aliases for the most commonly used commands, like fd
for forward etc. ...
-Some simple commands/methods for creating event driven
programs (mouse-, key-, timer-events). Especially
useful for programming simple games.
-A scrollable Canvas class. The scrollable Canvas can
be extended interactively as needed while playing
around with the turtle(s) (e. g. to follow some escaped
turtle).
-Commands for controlling background color or
background image.

detailed documentation is in the docstrings (similar to
the last version of turtle.py) which copmrise approx.
50% of the filesize.

xturtle.py is widely backward compatible to turtle.py
(i. e. except the appearance of the turtle(s) and their
animation)

I propose to replace turtle.py by xturtle.py

Separate Documentation is available as a text file
reassembled and enhanced from the docstring.
I'll supply this in a separate patch (as it seems
impossible here to attach 2 files)

Regards,
Gregor Lingl
msg50550 - (view) Author: Martin v. Löwis (loewis) * (Python committer) Date: 2006-06-29 18:16
Logged In: YES 
user_id=21627

A number of remarks:

1. would you like to see the demo applications included as
well? They could go somewhere into Demo. If so, please
prepare the patch as a single tar/zip file that unpacks on
top of a Python source tree.

2. The doc string refers to the module as xturtle, and says
it replaces turtle. If the module becomes turtle, this
remark becomes self-referential. Please update the doc
string accordingly.

3. Somebody should investigate the rationale for
re-exporting math in the current turtle.py. If that
rationale is still valid, the new module should comply.

4. The module should grow an __all__ attribute.

5. _Vec does not appear to be a general vector class, but be
restricted to 2D cartesian coordinates. It should be
renamed. Perhaps to "Point?"

6. Try to follow PEP 8, in particular, drop camelCase for
method names.

7. Avoid passive voice for doc strings; use active voice
instead (e.g. addshape: "Adds a turtle" -> "Add a turtle")

8. What happens to the n= argument of clear()?

9. What is the purpose/status of checkargs? Do you want to
keep it or drop it?

10. There are some German doc strings left (e.g. _rotate).
msg63604 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2008-03-16 21:53
(This is no longer the latest version. Gregor, mind uploading a newer one?)
msg63711 - (view) Author: Gregor Lingl (glingl) (Python committer) Date: 2008-03-17 19:01
This version runs under Python 2.5 and should run under python 2.6 It
still needs some amendments and polishing concerning the code as well as
the docstrings. Here it can serve as a starting point for a discussion
about necessary and/or desirable modifications.

A version for Python-3000 is under construction

For the new features please consult xturtle-docs.

Remarks on Martin's 10 points (msg 50550):

1) Should be discussed. I think a few demos would be fine, the whole
package perhaps would be to large. (I'll prepare a selection and upload
it in due time)
2) decision about replacement or supllement has still to be done. This
update will be easy ;-)
3) Who is that somebody?
4) Still has to be done
5) I for my part don't like Point, because this name refers more to the
geometrical than to the computational aspects of the object. What about
_Vec2 or _Vec2D? In this version an alias without the leading underscore
can be created via an entry in the xturtle.cfg file.
6) camelCase methodnames are changed to lowercase (at least the public ones)
7) Docstrings has still to be checked
8) n argument of clear has been dropped.
9) checkargs has been dropped (for now). It's purpose was intended to be
to check the types of the arguments and construct appropriate error
messages useful for programming beginners. I deferred it until I
eventually be able to come up with some intelligent solution using
decorators ;-) Would be fine but is not urgent.
10) Maybe there are still a few. These will be changed.
msg63714 - (view) Author: Gregor Lingl (glingl) (Python committer) Date: 2008-03-17 19:16
If you put (this example of) xturtle.cfg either into the directory where
xturtle.py resides or into the current working directory, the
configuration will be loaded. In this case window size and turtle are
configured to look like in module turtle.
If no config-file is found a standard configuration is used. (This
standard configuration currently uses a scrolled canvas but could of
course be changed to look like that furnished by the above cfg-file.)
msg63842 - (view) Author: Gregor Lingl (gregorlingl) Date: 2008-03-18 01:52
Supplementary remark:
xturtle has proved to run without problems under Python 2.6. (Not
surprisingly) it's behaviour is exactly like under Python 2.5,
with the exception, that the tested scripts run 5 to 15% faster.
msg64388 - (view) Author: Brad Miller (bmiller) Date: 2008-03-24 01:21
I have xturtle 0.95a0 running under Python 3.0.  Mostly the 2to3 program 
just worked for everything except in three places:
1.  in __forward methods I had to change: 
fromClass.__dict__[method] = d[method]    to
setattr(fromClass,method,d[method])

2. in getmethparlist  The line:
if type(ob)==types.MethodType:  does not evaluate to true even when ob 
is a method.  In 3.0 it seems that ob always evaluates to a function.

3. in the _pointlist method  I changed
cl = self.cv.coords(item)     to 
cl = list(self.cv.coords(item))
There is probably a more elegant way to use the results from the coords 
call than converting to a list, but I'm confused.
The canvas coords function now returns an itertools.imap object.  This 
confuses me because the documentation on python.org does not mention the 
imap function in the itertools module documentation. So I'm not sure if 
imap is going away or is just missing documentation.

I would like to propose two additional features that I have added to my 
copy of xturtle and have used extensively in my classes:

1.  exitOnClick()  --- This function simply hides the call to mainloop() 
from beginners.  It makes life much easier for beginning programers to 
run xturtle from IDLE.

2.  setWorldCoordinates(llx,lly,ulx,uly)  This maps a given set of real 
world coordinates to window coordinates and allows programmers to run 
the turtle using real world coordinates.  Again for beginning 
programmers this makes it easy for them to use the turtle to graph 
functions, make bar charts, etc. without needing to scale everything 
themselves.
msg67241 - (view) Author: Martin v. Löwis (loewis) * (Python committer) Date: 2008-05-23 14:20
Can you please file a contributor agreement? This would be a
prerequisite for including the module.

Also, is there any progress on the open issues? I really would like to
see a single zip file that unpacks on top of the Python tree, replaces
the turtle module, and works just fine in all respects out of the box.
msg67371 - (view) Author: Gregor Lingl (gregorlingl) Date: 2008-05-26 16:14
Certainly I'd like to file a contributor agreement. But I don't know
what is required exactly. Is there any template or example?  (There is
already a compyright-preamble in the submitted version - but I think you
mean something else?)

There is progress on most of the open issues and I have now a version
which works well with Python 2.6 and is fairly well documented via
docstrings. I could upload this within (at most) two days. It has also
those 2 features requested by Brad miller (msg64388) implemented.

But I have a few questions to which I need answers in order to continue
my work  optimally:

1) The turtle module is contained in one large file. But there will be
two versions, one for Python2.6 the other one for Python3.0. Right?

2) As far as I understand, xturtle.py  will replace turtle.py in Python
3.0. Will xturtle.py replace turtle.py already in Python2.6 or are the
plans that it will only be added to Python2.6? 

3) I understand, that compatibility issues are of primary importance for
Python 2.6. Is this also the case for Python 3.0? (If not some cleanup
could be done. I.e. some code, which is only there for compatibility
reasons could be dropped.)

4) How to proceed with documentation? Is it extracted automatically from
the docstrings? Or should I compose a single text file mainly from the
docstrings with some additional structure and  explanations? I also
would be happy to create sources for Sphinx, but that would take some
time (approx. a week) as I'm not familiar neither with Sphinx nor  with
reStructuredText. There are quite a few people around who would like to
help with the documentation, especially to amend my not very brillant
and clear English. This brings me to two very important questions:

5) How will the development of xturtle/turtle continue? There are more
than 3 month until the final release and it will be reasonable to use
this time to amend the docs (as mentioned above) and to fix those bugs,
which inevitably will occur during the beta testing period. 
- Should I prepare bugfix-releases of the module on my own and then
submit them every 1 or 2 weeks, or
- should the bugs and amendments be submitted to the bugtracker one at a
time and then be incorporated by some reviewer?

6) Who will be the reviewer? Martin? Or has the reviewer still to be
determined? I would very much appreciate some regular communication
about the open issues.

7) Where is the right place for this communication? Here at the
bugtracker? At Python-dev?

8) Another open issue is, if there should be added some sample scripts
to the standard-distro? What is your opinion?

More questions will certainly arise, but for now I'd be happy to get
answers to these ones.

Thanks in advance

Gregor Lingl
msg67374 - (view) Author: Benjamin Peterson (benjamin.peterson) * (Python committer) Date: 2008-05-26 16:35
You can get a contributor agreement at http://www.python.org/psf/contrib/.

1. We will add it to the 2.6, and tree and it will be ported to 3.0.

2. As long as it's compatible, it will replace the old turtle in 2.6.

3. We're trying not to change the APIs too much, but this is a
possibility if you deprecate them in 2.6.

4. reST is what we are using. If you could give the doc team a plain
text, we'd be happy to work with you and convert it to reST.

5. We can probably give you commit access to maintain your module. In
that case you can just do your fixes in Subversion.

6. I don't know. :)

7. Yes.

8. I think we could use some examples in the Demo directory.

Thanks for contributing!
msg67596 - (view) Author: Gregor Lingl (gregorlingl) Date: 2008-06-01 17:35
Hi,
here is my contribution. 
The zip-file contains

- the module turtle.py
- a doc-file turtle-docs.txt
- a subdirectory with a series of sample scripts and a demoviewer.
  (one of the demoscripts is a standalone script)

Clearly the docs have to be transformed to reST. I would do it or
participate but that certainly would only be ready within 2 or 3 weeks.
The end of the school year is near and I have a huge amount of work
in my school until approx. 20th of June. After this I have plenty of
time also for correcting etc. 

Of course I'll also do bugfixes etc. Anyway I'm interested in feedback
of any sort. 

I worked hard to do my best and I hope the result will be appreciated.
Best regards,
Gregor
msg67640 - (view) Author: Gregor Lingl (gregorlingl) Date: 2008-06-02 21:50
I'd like to propose a few modifications of turtle.py for the transition
from Python 2.6 to Python 3.0, which would result in a cleaner interface
but also in some - i think marginal - incompatibiliy: 

1) drop from math import *

2) delete the methods Turtle.window_width() and Turtle.indow_height()
(They are mereley transferred from Screen to Turtle and are imho generic
Screen.methods. So they will still be present as Screen methods and as
functions. In fact this proposition has a didactic background - on
should teach to differentiate between Screen- and Turtle-methods as
belonging to two completely different types of objects, and the only
realistic reply to the student's question "Why do Turtle objects have a
window_width() method would be: "for historical reasons!" When, if not
now, is time to make changes like this?)

3) The same is valid for Turtle.tracer() as tracer controls in fact
Screen-updates and not Turtle updates. (The only difference is, that
Turtle.tracer cannot be deleted, because it's (currently) used in
turtle.circle(), so I'd propose to rename it to Turtle._tracer() and so
delete it from the public interface.  Of course tracer() will also
remain present als Screen-method and as function.

Pros and cons?

I have prepared a file with these changes which could be used for
porting it to Python3.0. So if everybody agrees, I could upload it.
Regards,
Gregor
msg67644 - (view) Author: Gregor Lingl (gregorlingl) Date: 2008-06-02 22:54
In my last posting i forgot a fourth proposition.

Currently one has the Turtle.methods fill(), begin_fill() and end_fill()
As is stated in the old turtle docs the specification of fill is "rather
complex". begin_fill() and end_fill(), are identical to fill(True) and
fill(False) (or fill(1) and fill(0)). That means, that begin_fill()
sometimes may do somthing unexpected, namely complete som filling
underway. In the new turtle module fill() without arguments returns the
filling state, i. e. True/False respectively.

I'd prefer the following:

begin_fill() should only start a new filling process and cancel some
underway, if necessary (that means: a filling without end_fill will
not take place) 

end_fill() should only complete the current filling process

a new method filling() should be used to ask if same filling is
currently taking place

and fill() could be dropped. (deprecated in 2.6)

I think Vern Ceders intention with introducing begin_fill and end_fill
was to have a clear and easily understandable meaning, which is only
partially accomplished with the current solution.

What is your opinion?
Gregor
msg67683 - (view) Author: Martin v. Löwis (loewis) * (Python committer) Date: 2008-06-04 06:30
Thanks for the patch, committed as r63929. Please move any further
discussion or other necessary changes into a new issue.
History
Date User Action Args
2008-06-04 06:30:52loewissetstatus: open -> closed
resolution: accepted
messages: + msg67683
2008-06-02 22:55:09gregorlinglsetmessages: + msg67644
2008-06-02 21:51:04gregorlinglsetmessages: + msg67640
2008-06-01 17:35:16gregorlinglsetfiles: + turtle.zip
messages: + msg67596
2008-05-26 16:35:28benjamin.petersonsetnosy: + benjamin.peterson
messages: + msg67374
2008-05-26 16:14:23gregorlinglsetmessages: + msg67371
2008-05-23 14:20:33loewissetmessages: + msg67241
2008-03-24 01:21:03bmillersetmessages: + msg64388
2008-03-23 22:01:07bmillersetnosy: + bmiller
2008-03-18 01:52:01gregorlinglsetmessages: + msg63842
2008-03-18 01:49:23gregorlinglsetfiles: + whatsnew.txt
2008-03-17 19:24:27georg.brandlsetversions: + Python 3.0
2008-03-17 19:24:23georg.brandllinkissue2309 superseder
2008-03-17 19:16:16glinglsetfiles: + xturtle.cfg
messages: + msg63714
2008-03-17 19:05:15glinglsetfiles: + xturtle-docs.txt
2008-03-17 19:01:40glinglsetfiles: + xturtle.py
nosy: + glingl
messages: + msg63711
versions: + Python 2.6, - Python 2.4
2008-03-16 21:53:13gvanrossumsetnosy: + gvanrossum
messages: + msg63604
2006-06-28 00:50:47gregorlinglcreate