473,573 Members | 2,748 Online
Bytes | Software Development & Data Engineering Community
+ Post

Home Posts Topics Members FAQ

Rethinking the Python tutorial

While the official Python Tutorial has served its
purpose well, keeping it up to date is hardly anyones
top priority, and there are others who passionately
create really good Python tutorials on the web.

I think 'A Byte of Python' by Swaroop C H is a good
beginners tutorial, and 'Dive Into Python' by Mark
Pilgrim is a good tutorial for more experienced
programmers.

My radical idea is that we mirror these at
diveinto.python .org and byteof.python.o rg, and
simply remove the old tutorial from the Python
2.5 (or 2.6?) docs. Give these two good texts an
official status as the Python tutorials.

Just as we want to adopt best of breed packages
for the standard library, I think we should use
best of breed documentation, and I think there are
less backward compatibility issues with tutorials
than with libraries. :)

I think this change would give us better docs as
well as a smaller maintenance burden. If a day
comes when Mark Pilgrim or Swaroop C H don't want
to maintain these texts, I strongly suspect that
there are other tutorials we can replace them with
if noone else steps in to keep them up to date.
Feb 9 '06 #1
11 2913
On 09/02/06, Magnus Lycka <ly***@carmen.s e> wrote:
While the official Python Tutorial has served its
purpose well, keeping it up to date is hardly anyones
top priority, and there are others who passionately
create really good Python tutorials on the web.

I think 'A Byte of Python' by Swaroop C H is a good
beginners tutorial, and 'Dive Into Python' by Mark
Pilgrim is a good tutorial for more experienced
programmers.

My radical idea is that we mirror these at
diveinto.python .org and byteof.python.o rg, and
simply remove the old tutorial from the Python
2.5 (or 2.6?) docs. Give these two good texts an
official status as the Python tutorials.

Just as we want to adopt best of breed packages
for the standard library, I think we should use
best of breed documentation, and I think there are
less backward compatibility issues with tutorials
than with libraries. :)

I think this change would give us better docs as
well as a smaller maintenance burden. If a day
comes when Mark Pilgrim or Swaroop C H don't want
to maintain these texts, I strongly suspect that
there are other tutorials we can replace them with
if noone else steps in to keep them up to date.


How about putting the current tutorial into the wiki and seeing if
people start updating it? I'm not saying it would work, but it might
have interesting effects...

Ed
Feb 10 '06 #2
There are now more than 300 tutorials listed at
www.awaretek.com/tutorials.html so one could even imagine a
"mega-tutorial" using the best-of-breed tutorial for each sub-section,
a la Turbogears ;-)))

Of course it might bear an unholy resemblance to a FrankenTutorial
;-)))

Ron Stephens

Feb 10 '06 #3
I think you guys are up to something. We need some way to aggregate,
update, and extend not just tutorials but all kinds of informatory
material on Python. The Python Wiki is a good place for all that,
although it hasn't become anything resembling a Wikipedia so far.

AdSR

Feb 11 '06 #4
Ed Singleton wrote:
How about putting the current tutorial into the wiki and seeing if
people start updating it? I'm not saying it would work, but it might
have interesting effects...


There are abviously a lot of ideas in the air concerning on-line
editing of the new python web site, support for user comments in
the docs etc. I hope some of these things will be deployed soon.

Concerning the tutorial, I just felt that the two I mentioned are
the "best of breed", and it might be smarter to give them official
status. I don't see any value in maintaining Guido's tutorial for
all eternity. It's not as if we need backward compatibility in the
tutorial department... I suppose there are some gaps in A Byte Of
Python that needs to be filled. For instance, the discussion on
Unicode seems very thin. I still think it's a better starting point
for the ideal beginners tutorial than the old official tutorial.

I still feel it's a better beginner's tutorial though. Last time I
suggested the standard Python tutorial to someone, she dropped
Python almost at once, since she got the impression that it was
some kind of calculator program, and she wasn't looking for that.

I think there are a lot of potential improvements for Python docs.
The Language Reference is unreadable for mortals, and that means
that there is no standard reference document describing the real
fundamentals in Python, statements and operators. we just have the
tutorial for that.

The best resource in the Python docs is that Library Reference.
As far as I understand, it's not complete, and it could contain
more examples in places, but it's very useful.

The Lanugage Reference seems more like some kind of specification.
I think a *real* Python Language Guide would be great, and it could
still be a fairly short document, even if core Python has grown a
bit in recent versions. The builtins chapter in the Library Reference
(Ch 2) belongs here, and the Std Lib Ref is just for things we
import. It's really strange to document e.g. string literals and the
string class in different manuals.

I was thinking that maybe some old paper book on Python could be
donated for this purpose, but now it seems that most of the good
ones are going to be reprinted soon, if they aren't already in the
stores. I'm really happy that they are still commercially viable,
but it would have been great if we had gotten one of these goodies
as a starting point. It's hard work to write such good books as
e.g. Martelli and Beazley did.

Of the good books, I just have Beazley's "Python Essential Reference"
1st Ed. nearby, but chapter 2-10 in that shows very well what I
think a Python Language Guide could look like.

BTW... Alex is now employed by a very rich and successful company
that really owes the Python community a lot of gratitude. It's great
that they are paying the salaries for some of the very best Python
people, and let them work some for the community, but perhaps Google
could buy the rights for "Python in a Nutshell" from Martelli/O'Reilly
and donate it do the community? :)
Feb 13 '06 #5
Magnus Lycka wrote:
Ed Singleton wrote:
How about putting the current tutorial into the wiki and seeing if
people start updating it? I'm not saying it would work, but it might
have interesting effects...

There are abviously a lot of ideas in the air concerning on-line
editing of the new python web site, support for user comments in
the docs etc. I hope some of these things will be deployed soon.

You and me both!
Concerning the tutorial, I just felt that the two I mentioned are
the "best of breed", and it might be smarter to give them official
status. I don't see any value in maintaining Guido's tutorial for
all eternity. It's not as if we need backward compatibility in the
tutorial department... I suppose there are some gaps in A Byte Of
Python that needs to be filled. For instance, the discussion on
Unicode seems very thin. I still think it's a better starting point
for the ideal beginners tutorial than the old official tutorial.
As with all such content, the first thing you will need is a band of
volunteers dedicated to keeping the content up to date, both proactively
and in response to reader comments.

This is a far from easy step.
I still feel it's a better beginner's tutorial though. Last time I
suggested the standard Python tutorial to someone, she dropped
Python almost at once, since she got the impression that it was
some kind of calculator program, and she wasn't looking for that.
Yes, I think many people would agree that the existing tutorial is a
little slanted towards people who are already familiar with programming,
and sometimes programming in the Linux/Unix environment.
I think there are a lot of potential improvements for Python docs.
The Language Reference is unreadable for mortals, and that means
that there is no standard reference document describing the real
fundamentals in Python, statements and operators. we just have the
tutorial for that.

The best resource in the Python docs is that Library Reference.
As far as I understand, it's not complete, and it could contain
more examples in places, but it's very useful.

The Lanugage Reference seems more like some kind of specification.
That's exactly what it's supposed to be: guidance for implementers.
I think a *real* Python Language Guide would be great, and it could
still be a fairly short document, even if core Python has grown a
bit in recent versions. The builtins chapter in the Library Reference
(Ch 2) belongs here, and the Std Lib Ref is just for things we
import. It's really strange to document e.g. string literals and the
string class in different manuals.
What we are talking about here is a Python Language Users' Guide.
I was thinking that maybe some old paper book on Python could be
donated for this purpose, but now it seems that most of the good
ones are going to be reprinted soon, if they aren't already in the
stores. I'm really happy that they are still commercially viable,
but it would have been great if we had gotten one of these goodies
as a starting point. It's hard work to write such good books as
e.g. Martelli and Beazley did.

Of the good books, I just have Beazley's "Python Essential Reference"
1st Ed. nearby, but chapter 2-10 in that shows very well what I
think a Python Language Guide could look like.

BTW... Alex is now employed by a very rich and successful company
that really owes the Python community a lot of gratitude. It's great
that they are paying the salaries for some of the very best Python
people, and let them work some for the community, but perhaps Google
could buy the rights for "Python in a Nutshell" from Martelli/O'Reilly
and donate it do the community? :)


Google are very active supporters of Python already, though they don't
make a big song and dance about it. You might notice, for example, that
they are a Platinum Sponsor at PyCon this year, as well as being a
sponsor member of the PSF. The Summer of Code also benefited Python in
several ways.

There are older-established companies with more Python programmers who
have made hardly any community contribution - the "takers" of the open
source world. I wouldn't like Google to think that the Python community
isn't recognizing their support.

You might also like to ask Alex what he'd feel about losing the
"Nutshell" revenue stream!

regards
Steve
--
Steve Holden +44 150 684 7255 +1 800 494 3119
Holden Web LLC www.holdenweb.com
PyCon TX 2006 www.python.org/pycon/

Feb 13 '06 #6
On Mon, 13 Feb 2006 11:03:55 -0500,
Steve Holden <st***@holdenwe b.com> wrote:
What we are talking about here is a Python Language Users' Guide.


I actually started on such a document over the holidays, but have only
described about 3 or 4 statements at this point. However, it's
probably not going to be *much* smaller than the Reference Guide,
because pretty much every topic in the RefGuide needs to appear in the
user's guide.

--amk

Feb 13 '06 #7
Ur**********@gm ail.com wrote:
There are now more than 300 tutorials listed at
www.awaretek.com/tutorials.html so one could even imagine a
"mega-tutorial" using the best-of-breed tutorial for each sub-section,
a la Turbogears ;-)))


We certainly don't need 300 tutorials. :) Pick the best in the
most relevant categories and promote them to official status.
In a way this is obviously like Turbo Gears... Pick the best
ones and package them together. I don't think we need a lot
of categories though. I think we should be conservative in
what we officially promote, and leave the pointers to various
special interests to the wiki. Perhaps one tutorial official
is enough? In that case it should be Swaroop's. That's the
core language tutorial. Mark's is more a series of visits to
the great land of Python applications, and

That's what I'm proposing. I looked at a few of the beginners
tutorials in the list above. Some are pretty old, others are
present a really bad introduction to Python, showing poor
coding style and a poor understanding of Python.

The current official tutorial isn't ideal for beginners without
previous programming experience, and providing a big bunch of
links for beginners to wade through (as in
http://wiki.python.org/moin/BeginnersGuide ) is far from ideal.
There are more than 40 links on that page for the beginners to
ponder over, and if they decide to follow the
BeginnersGuide/NonProgrammers link, they find another 20+ links.

These 60+ links are more or less equally prominent. There is
no "Go *HERE* first. If you have special interests, you might
want to look at something in this list of other resources as
well".

I'm pretty sure it hadn't looked like this if the official
tutorial had been good enough.

Somehow, the state of Python tutorials remind me of Python
web application toolkits...

I think that one good indication that a tutorial is good,
is that it's been translated to other languages. The ones
I know have been translated are Swaroop's, Mark Pilgrims,
Alan Gaulds, and Danny Yoo's Idle tutorial. Out of these,
Swaroop's and Pilgrim's are the "proper" Python Tutorials.
Danny's is an intro to Idle (which is a good thing) and
Alan's is really more focussed on programing in general
than on Python, although Python is the main vehicle.
(Just like How to Think Like a Computer Scientist.)
Feb 13 '06 #8
Steve Holden wrote:
Magnus Lycka wrote:
As with all such content, the first thing you will need is a band of
volunteers dedicated to keeping the content up to date, both proactively
and in response to reader comments.
That's why I suggested these already written tutorials. Both
authors have shown that they can make an effort, and there are
other people who have helped with contributions such as
translations. Hopefully, giving these texts a more official
status will stimulate them further and make more people
interested, but I guess it could also go the other way, if it
isn't handled well.
What we are talking about here is a Python Language Users' Guide.
Agreed.
Google are very active supporters of Python already, though they don't
make a big song and dance about it. You might notice, for example, that
they are a Platinum Sponsor at PyCon this year, as well as being a
sponsor member of the PSF. The Summer of Code also benefited Python in
several ways.
I didn't notice the PyCon sponsorship. Maybe that's something for
the EuroPython arrangers to think about... After all, EuroPython 2006
will be at CERN, and that's where the whole web thingie started... :)
There are older-established companies with more Python programmers who
have made hardly any community contribution - the "takers" of the open
source world. I wouldn't like Google to think that the Python community
isn't recognizing their support.
It has improved lately, and I agree that others could chip in as well.
You might also like to ask Alex what he'd feel about losing the
"Nutshell" revenue stream!


Well, I suggested they'd pay him for it. Perhaps a decent sized sack
of money now is as good as that long term stream... It was just a wild
idea though. You know, they don't usually come true, but who knows?
Suggesting it might increase the chances. It would certainly be a
boost for Python to have such excellent documentation on the web. It
would probably make it easier for Google (and you other big corps!)
to find good Python programmers in the future.
Feb 13 '06 #9
A.M. Kuchling wrote:
On Mon, 13 Feb 2006 11:03:55 -0500,
Steve Holden <st***@holdenwe b.com> wrote:
What we are talking about here is a Python Language Users' Guide.


I actually started on such a document over the holidays, but have only
described about 3 or 4 statements at this point.


Great! I hope you'll find the time to make this into something useful.
I don't know how easy it is to make such a thing into a collaborative
effort. Either way, I think some kind of champion is needed... I hope
we'll see some kind of tools for on-line collaboration for python.org
soon, whether it's something wiki-like or some other way to add comments
to the web pages.
Feb 14 '06 #10

This thread has been closed and replies have been disabled. Please start a new discussion.

Similar topics

3
9704
by: Stephen Ferg | last post by:
I need a little help here. I'm developing some introductory material on Python for non-programmers. The first draft includes this statement. Is this correct? ----------------------------------------------------------------- When loading modules, Python looks for modules in the following places in the following order:
4
2417
by: Mark | last post by:
Hello. I am new to programming and Python and was wondering if someone could help get me started. I picked Python to start learning to prgram because of some things I have read about it (easy to learn, object oriented, clear syntax, etc...). Can anyone assist in getting me started with learning to program and Python? Recommended reading...
0
1850
by: Kurt B. Kaiser | last post by:
Patch / Bug Summary ___________________ Patches : 259 open ( -5) / 2573 closed (+17) / 2832 total (+12) Bugs : 745 open ( +0) / 4405 closed (+21) / 5150 total (+21) RFE : 150 open ( +1) / 130 closed ( +0) / 280 total ( +1) New / Reopened Patches ______________________
24
2204
by: Christopher J. Bottaro | last post by:
This post is just the culmination of my thoughts and discussions with my coworkers on Python. If you are not interested, please skip over it. At my work, we are developing a product from scratch. It is completely modular and the modules communicate via SOAP. Because of that, we can implement individual modules in any language of our...
0
1449
by: Cameron Laird | last post by:
QOTW: "You can tell everything is well in the world of dynamic languages when someone posts a question with nuclear flame war potential like 'python vs. ruby' and after a while people go off singing hymns about the beauty of Scheme..." - vdrab "ctypes completely rocks." - Grant Edwards Michael Lange endows Tkinter with a Tree widget:...
2
2908
by: mr_gees100_peas | last post by:
Hi, I've been trying for days to make either boost.python or swig to work for me. The one I have gotten the closest to is boost. Note that this is for windows XP. I'm not much of an unix person besides doing simple ls and copy paste. What I have done is to download the boost library: C:\boost_1_34_0 I downloaded the bjam library: ...
0
1969
by: Kurt B. Kaiser | last post by:
Patch / Bug Summary ___________________ Patches : 385 open (+21) / 3790 closed (+21) / 4175 total (+42) Bugs : 1029 open (+43) / 6744 closed (+43) / 7773 total (+86) RFE : 262 open ( +4) / 291 closed ( +4) / 553 total ( +8) New / Reopened Patches ______________________
24
2491
by: Steven D'Aprano | last post by:
Sometimes it seems that barely a day goes by without some newbie, or not- so-newbie, getting confused by the behaviour of functions with mutable default arguments. No sooner does one thread finally, and painfully, fade away than another one starts up. I suggest that Python should raise warnings.RuntimeWarning (or similar?) when a function...
0
1332
by: Basha J P M | last post by:
I am beginner in python. I am working through the tutorial examples from http://www.swig.org/ and have run into some problems. I took the following command instructions from the tutorial on swig.org: http://www.swig.org/tutorial.html I have written example.c and example.i as described in the above tutorial. My first attempt at compiling...
0
7746
marktang
by: marktang | last post by:
ONU (Optical Network Unit) is one of the key components for providing high-speed Internet services. Its primary function is to act as an endpoint device located at the user's premises. However, people are often confused as to whether an ONU can Work As a Router. In this blog post, we’ll explore What is ONU, What Is Router, ONU & Router’s main...
0
7668
by: Hystou | last post by:
Most computers default to English, but sometimes we require a different language, especially when relocating. Forgot to request a specific language before your computer shipped? No problem! You can effortlessly switch the default language on Windows 10 without reinstalling. I'll walk you through it. First, let's disable language...
0
7986
Oralloy
by: Oralloy | last post by:
Hello folks, I am unable to find appropriate documentation on the type promotion of bit-fields when using the generalised comparison operator "<=>". The problem is that using the GNU compilers, it seems that the internal comparison operator "<=>" tries to promote arguments from unsigned to signed. This is as boiled down as I can make it. ...
0
8036
tracyyun
by: tracyyun | last post by:
Dear forum friends, With the development of smart home technology, a variety of wireless communication protocols have appeared on the market, such as Zigbee, Z-Wave, Wi-Fi, Bluetooth, etc. Each protocol has its own unique characteristics and advantages, but as a user who is planning to build a smart home system, I am a bit confused by the...
0
6358
agi2029
by: agi2029 | last post by:
Let's talk about the concept of autonomous AI software engineers and no-code agents. These AIs are designed to manage the entire lifecycle of a software development project—planning, coding, testing, and deployment—without human intervention. Imagine an AI that can take a project description, break it down, write the code, debug it, and then...
0
5258
by: conductexam | last post by:
I have .net C# application in which I am extracting data from word file and save it in database particularly. To store word all data as it is I am converting the whole word file firstly in HTML and then checking html paragraph one by one. At the time of converting from word file to html my equations which are in the word document file was convert...
0
3701
by: TSSRALBI | last post by:
Hello I'm a network technician in training and I need your help. I am currently learning how to create and manage the different types of VPNs and I have a question about LAN-to-LAN VPNs. The last exercise I practiced was to create a LAN-to-LAN VPN between two Pfsense firewalls, by using IPSEC protocols. I succeeded, with both firewalls in...
1
2167
by: 6302768590 | last post by:
Hai team i want code for transfer the data from one system to another through IP address by using C# our system has to for every 5mins then we have to update the data what the data is updated we have to send another system
0
999
bsmnconsultancy
by: bsmnconsultancy | last post by:
In today's digital era, a well-designed website is crucial for businesses looking to succeed. Whether you're a small business owner or a large corporation in Toronto, having a strong online presence can significantly impact your brand's success. BSMN Consultancy, a leader in Website Development in Toronto offers valuable insights into creating...

By using Bytes.com and it's services, you agree to our Privacy Policy and Terms of Use.

To disable or enable advertisements and analytics tracking please visit the manage ads & tracking page.