Type: enhancement Stage: patch review
Components: Documentation, IDLE Versions: Python 3.7, Python 3.6
Status: open Resolution:
Dependencies: Superseder:
Assigned To: terry.reedy Nosy List: Al.Sweigart, Amit.Saha, Todd.Rovito, cheryl.sabella, docs@python, eric.araujo, ezio.melotti, roger.serwy, terry.reedy
Priority: normal Keywords: patch

Created on 2013-03-30 23:12 by Amit.Saha, last changed 2017-06-20 01:27 by terry.reedy.

File name Uploaded Description Edit
idle.patch Amit.Saha, 2013-03-31 22:16 IDLE HOWTO initial patch review
idle.patch Amit.Saha, 2013-04-02 10:21 IDLE HOWTO Patch #2 (includes screenshots) review
Messages (21)
msg185600 - (view) Author: Amit Saha (Amit.Saha) * Date: 2013-03-30 23:12
I would like to propose a new HOWTO discussing IDLE from a user's perspective. I feel that the current documentation at is not sufficient to be pointed to a newbie programmer or someone who wants to teach his/her students to IDLE. For example, being an experienced person myself, I didn't know how to start IDLE on Linux! Whether it was a separate package, or whether it was already installed (That may be my own shortcoming, but never the less).

I started a document this morning which can be seen here [1]. The source is here[2]


I am putting up my hand to write the HOWTO and maintain it for 2.7 and 3.3+. 

msg185609 - (view) Author: Todd Rovito (Todd.Rovito) * Date: 2013-03-31 03:45
I think it is a great idea.....

The Python documentation is written with restructured text.  See the Python Developer's Guide here:

Restructured text is not difficult please let me know if you need help I would be glad to assist.

What you have is a good start but it will have to be reformatted then submitted as a patch so it can be committed.  In addition you have to complete a Python Contributor Agreement.  Please spend a little time looking over the Python Developer's Guide.  Thanks.
msg185610 - (view) Author: Roger Serwy (roger.serwy) * (Python committer) Date: 2013-03-31 03:51
I agree that improving IDLE's docs would make it easier to learn and use. There is a tangentially related issue: #16893.
msg185624 - (view) Author: Amit Saha (Amit.Saha) * Date: 2013-03-31 11:38
Hi Todd, 

I just signed the Python contributor agreement electronically.

You probably missed the link to the rSt source in my original report. Here it is [1]. I would want this HOWTO to cover all aspects of IDLE from an user's perspective. 

I have some ideas about what to add, but I would like to hear from you as well.


msg185629 - (view) Author: Todd Rovito (Todd.Rovito) * Date: 2013-03-31 16:26
Yes I missed the link sorry.  Can you add the rst file to Doc/faq in the tip of the repository then do a hg diff and post the patch as an attachment to this issue?  At that point I will review and send any changes or edits with the review system.  Others can suggest changes as well.
msg185688 - (view) Author: Amit Saha (Amit.Saha) * Date: 2013-03-31 22:16
Adding the patch here. I am not sure about how to add the screenshots, so I haven't done them. 

Just attached the document as a patch (note that I have placed in doc/howto).

Thanks for the comments.
msg185693 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-03-31 23:08
I left a few comments on rietveld.
I wonder if it's better to make two separate versions, one for py2 and one for py3, and avoid repeating things (like the name of the packages) twice.

You should also be able to include the images in the patch by using "hg add" locally.  This should include them when you do "hg diff > idle.patch" (if it doesn't work you might have to set "git = on" (see
msg185696 - (view) Author: Amit Saha (Amit.Saha) * Date: 2013-03-31 23:50
Hi Ezio, thanks for your review comments. 

I will make the changes to the document, and also add the images in a later patch.

I do agree that repeating package names for Python 2 and Python 3 is perhaps not an ideal way. I am also trying to think of other ways to justify having two separate documents: may be the code samples? print 'Hello world' versus print('Hello World') ?

msg185701 - (view) Author: Todd Rovito (Todd.Rovito) * Date: 2013-04-01 02:21
   I left a few comments on rietveld.  This is a really nice start to a great FAQ.  Thanks for your contribution I think Python needs a nice FAQ on IDLE.  You might want to add some detail about the right click menu which allows a user to cut, copy, paste, and set breakpoints.  I think a section on the debugger would be excellent.
msg185702 - (view) Author: Amit Saha (Amit.Saha) * Date: 2013-04-01 02:23
Hi Todd, thanks for your comments. I wanted to clarify that I intend to make this a HOWTO, not a FAQ.

I hope that's fine?

msg185769 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-04-01 21:00
I added a few more comments.

To clarify, when I said two documents, I meant that there will be only a single HOWTO, but on 2.7 it will be specific to Python 2, whereas on 3.x it will be specific to Python 3.
msg185776 - (view) Author: Amit Saha (Amit.Saha) * Date: 2013-04-01 21:59
Thanks Ezio. I am almost done with incorporating the changes suggested and will submit a patch sometime in the next day or so.
msg185790 - (view) Author: Todd Rovito (Todd.Rovito) * Date: 2013-04-02 01:46
Sorry about using the wrong word, I should of used HowTo not FAQ.  I really meant to suggest replacing guide with the word HowTo.  A HowTo would be perfect!!!!  Sorry about the confusion.  Thanks again.
msg185827 - (view) Author: Amit Saha (Amit.Saha) * Date: 2013-04-02 10:21
I have tried to incorporate most of the suggestions and made some other changes as well. Hope it looks better now.

I haven't yet split it into two separate versions.
msg185874 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2013-04-03 01:27
This is a great idea, thank you.

FYI You can share text and images with a diff file: if you call “hg add path/to/images” and create the diff with the --git option, it will use an extended unified diff format which includes binary changes.  Our review system is not compatible with that format though, so you can simply attach the files here.
msg185876 - (view) Author: Amit Saha (Amit.Saha) * Date: 2013-04-03 01:35
Hello Éric Araujo, thanks. Oh I thought it did support, and hence I created the diff in exactly the way you mention.

i also went ahead and tested it by 'hg import' -ing it into a cpython clone and i was all excited to see all my images there :-)

But, yeah I can certainly attach the images separately.
msg188759 - (view) Author: Amit Saha (Amit.Saha) * Date: 2013-05-09 09:47
Hello, I just wanted to check if I should attach the image files separately and submit the text as a diff? 

msg193075 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013-07-15 05:38
(If someone else wants to take this before I get to it, feel free. But there seems to be enough support to add something eventually.)

It seems that Rietveld is able to ignore the binaries, but in the future, lets separate the text and images. If nothing else, the images should stay the same while the text gets updated patches.

Looking at, I think the title should begin with Idle or IDLE, but if the latter, not include HOWTO as one SHOUT is enough. I think it should be in its alphabetical position after Functional Programming. I have no idea why argparse and ipaddress are out of order.

I think there should be a section on using the shell before using the editor.

From a command line (at least on Windows, when not in the directory containing 'python -m idlelib' is the easiest way to start. Within a Python program, 'import idlelib.idle' starts it. I plan to add a new section to the docs for this, but it might be worth repeating.

I will look more closely at the text another time.
msg296382 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2017-06-19 22:15
Cheryl, what do you think of the revised patch?  I imagine it needs some updating for *nix, but does it seem useful to a beginner?
msg296394 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2017-06-19 23:59
I think it's a good start, but may need some tweaking.  For example, the
Menu options should probably somehow stand out from the rest of the text.

I think it would be useful for a beginner, depending on how much of a
beginner they are and how they got to this page.  For example, if I wanted
to learn Python and had no prior programming experience, most likely I
would google 'learn python' (or maybe even just 'learn to program') and
check out those links.  Some results, like the Tutorial in the
docs, focus on getting Python installed and using the interactive
interpreter.  There doesn't seem to be anything in the docs
(except for the FAQ) that suggest using IDLE.  Although, the FAQ might be
one of the first places a beginner would look, so maybe a link from there
to the HOWTO would be helpful.  I think showing how to install IDLE and use
it is important, and that alone would make this page useful.  The current
IDLE doc page has the command line usage in the middle of the page, but
doesn't really just answer how do I install it and how do I run it?

So, assuming a beginner is following some tutorial, they get to a point
where they need an editor.  Following the instructions for installing any
program can be tricky.  Heck, even installing Python might have been
tricky, so good for them if they got this far.  But, without any
instructions for getting IDLE to run, they are left to googling for it.  It
would be great for the python docs can have a step by step installation
instruction and even troubleshooting.  Then, as this HOWTO does, explain
what opens up and how to use the editor, etc.  As I've recently experienced
with git, I find it frustrating to spend half a day trying to get something
to work when it should be easy.  This page could be a one page
introduction/reference so that someone doesn't have to cobble together
answers from all over the internet to questions they didn't even know to
msg296395 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2017-06-20 01:27
Thanks.  This is helpful and got me started thinking.

I don't want to duplicate the reference doc too much, but a reference is just that, a reference.  The menu items are discussed in the order they appear, not the order a beginner might use the most common ones.

Judging from Stackoverflow questions, covering platform specifics is needed.  People seem to miss the following: Python runs IDLE; IDLE hands user code to Python to execute.  Output and error messages come from Python, not IDLE.  If you want python to import 3rd party modules, one must install the module for the Python used to run IDLE.  (I have answered at least 3 variations of this question.) Anyway, I realize that I have a source of frequent beginner questions and problems.  If we have answers in a How-To, I can quote and suggest that people read it.

Amit, do you wish to continue with this?
Date User Action Args
2017-06-20 01:27:52terry.reedysetmessages: + msg296395
2017-06-19 23:59:27cheryl.sabellasetmessages: + msg296394
2017-06-19 22:15:41terry.reedysetnosy: + cheryl.sabella

messages: + msg296382
versions: + Python 3.6, Python 3.7, - Python 2.7, Python 3.3, Python 3.4
2015-01-04 02:17:21Al.Sweigartsetnosy: + Al.Sweigart
2013-07-15 05:38:44terry.reedysetassignee: docs@python -> terry.reedy

messages: + msg193075
nosy: + terry.reedy
2013-05-09 09:47:18Amit.Sahasetmessages: + msg188759
2013-04-03 01:35:52Amit.Sahasetmessages: + msg185876
2013-04-03 01:27:35eric.araujosetnosy: + eric.araujo
messages: + msg185874
2013-04-02 10:23:50Amit.Sahasetfiles: + idle.patch

messages: + msg185827
2013-04-02 01:46:13Todd.Rovitosetmessages: + msg185790
2013-04-01 21:59:36Amit.Sahasetmessages: + msg185776
2013-04-01 21:00:42ezio.melottisetmessages: + msg185769
2013-04-01 02:23:46Amit.Sahasetmessages: + msg185702
2013-04-01 02:21:56Todd.Rovitosetmessages: + msg185701
2013-03-31 23:50:45Amit.Sahasetmessages: + msg185696
2013-03-31 23:08:10ezio.melottisetnosy: + ezio.melotti

messages: + msg185693
stage: patch review
2013-03-31 23:04:19ezio.melottisethgrepos: - hgrepo180
2013-03-31 22:16:07Amit.Sahasetfiles: + idle.patch
hgrepos: + hgrepo180
messages: + msg185688

keywords: + patch
2013-03-31 16:26:46Todd.Rovitosetmessages: + msg185629
2013-03-31 11:38:47Amit.Sahasetmessages: + msg185624
2013-03-31 03:51:41roger.serwysetversions: + Python 2.7, Python 3.4
nosy: + docs@python, roger.serwy

messages: + msg185610

assignee: docs@python
components: + Documentation
2013-03-31 03:45:12Todd.Rovitosetnosy: + Todd.Rovito
messages: + msg185609
2013-03-30 23:12:36Amit.Sahacreate