Comments requested: brief summary of Python

[Adam Barr]

For a book I am working on, I have written a brief (9 page) summary
of Python. The intent of this is that an experienced programmer who
did
not know Python would be able to get enough information to read and
understand Python programs. It is not meant to be a 100% complete
summary of the language, but everything in there should be correct.

If anyone is interested, please feel free to read it and send me
comments. Note that the material is copyrighted, this document is
provided for review only, and the ideas contained in any comments may
be used in the book, in whole or in part, with no rights granted to
the person who provided the comments. I will however acknowledge by
name (if desired) anyone who sends comments.

The information is in PDF form per my publisher's request, but if this
is a problem for anyone, email me and I can send it to you in plain
text.

The file is at

http://www.proudlyserving.com/language/python.pdf

I have written similar summaries for other languages and will
hopefully post them (with a virtually identical message) in the
appropriate newsgroups in the next few days.

Thank you.

- Adam Barr
(e-mail address removed)

 

[Moosebumps]

It seems like you could demonstrate the same thing a little more clearly and
concisely with a short program with annotations. It reads like a bunch of
facts, which is not very easy for most people to remember. If you wrap it
in some context they will be more likely to remember it.

Some standard programs from textbooks, like parsing a list of names and
addresses and doing some queries on them maybe, and formatting the text
output nicely. some program where you would have cause to use string
operations like slicing, dictionaries, tuples, lists, etc.

It will also "sell" python more if you can write a nice elegant program that
is clear and easy to understand, while demonstrating many language features.

 

[Josiah Carlson]

I'll send some real comments later (tomorrow or later this week).

I have the sense that your summary of Python, and the handful of other
languages I checked your descriptions of, are too elementary for an
experienced programmer to bother reading through. I got around two
paragraphs in, then started reading a paragraph per page until I was
done with the Python version, with the same read-through of C and Perl.

I also notice that your liberal use of semicolons (such as comments in C
in the last paragraph) are confusing:
"Comments are denoted by //; everything after that on a line is..."


- Josiah

 

[Adam Barr]

I'll send some real comments later (tomorrow or later this week).

I have the sense that your summary of Python, and the handful of other
languages I checked your descriptions of, are too elementary for an
experienced programmer to bother reading through. I got around two
paragraphs in, then started reading a paragraph per page until I was
done with the Python version, with the same read-through of C and Perl.

I also notice that your liberal use of semicolons (such as comments in C
in the last paragraph) are confusing:
"Comments are denoted by //; everything after that on a line is..."


- Josiah

Thanks for the comments.

The target audience here is an experience programmer that doesn't know
Python at all. So I didn't want to assume they knew about indenting,
or how lists work, etc.

I agree that semi-colon in confusing! I'll check for that.

- adam

 

[Josiah Carlson]

The target audience here is an experience programmer that doesn't know

Python at all. So I didn't want to assume they knew about indenting,
or how lists work, etc.

In general, not just the Python description, but the three language
descriptions I read (Python, Perl, C), all sounded like they were going
to be given to a CEO who knew how to use formulas in Excel, not to
anyone with real programming experience.

Each version felt very much like you were holding someone's hand.
Moosebumps made a good suggestion to offer a short program, and describe
it as you go along. In languages where you can insert a comment
virtually anywhere, you could document the code, describing the syntax
and features of the languages as you go along. For those additional
language features (like lists, tuples, dicts, etc. in Python, and other
in other languages), having a section at the end describing the basic
(and advanced) data structures available to the language, seems to make
sense to me.

- Josiah

 

[Cameron Laird]

In general, not just the Python description, but the three language
descriptions I read (Python, Perl, C), all sounded like they were going
to be given to a CEO who knew how to use formulas in Excel, not to
anyone with real programming experience.

Each version felt very much like you were holding someone's hand.
Moosebumps made a good suggestion to offer a short program, and describe
it as you go along. In languages where you can insert a comment
virtually anywhere, you could document the code, describing the syntax
and features of the languages as you go along. For those additional
language features (like lists, tuples, dicts, etc. in Python, and other
in other languages), having a section at the end describing the basic
(and advanced) data structures available to the language, seems to make
sense to me.

- Josiah

Me, too. Josiah hits it just right.

 

[Peter Hansen]

Me, too. Josiah hits it just right.

This reminds me of something I just saw, in a little different context.
It's a coding standard, not a language description, but there's enough
similarity to the idea above that I thought it worth mentioning. It's
Will Wake's "Java Coding Standard on a Page":

http://www.xp123.com/xplor/xp0002f/index.shtml

Would be interesting to see the same idea applied to language descriptions,
distilled right down to the essence.

-Peter

 

[Adam Barr]

It seems like you could demonstrate the same thing a little more clearly and
concisely with a short program with annotations. It reads like a bunch of
facts, which is not very easy for most people to remember. If you wrap it
in some context they will be more likely to remember it.

Some standard programs from textbooks, like parsing a list of names and
addresses and doing some queries on them maybe, and formatting the text
output nicely. some program where you would have cause to use string
operations like slicing, dictionaries, tuples, lists, etc.

It will also "sell" python more if you can write a nice elegant program that
is clear and easy to understand, while demonstrating many language features.

Good point. The book will have programs later on, this section is
meant as a reference.

However, as such I should probably split it into sections so it is not
just one big lump: "basic", "loops", "conditionals", etc.

- adam

 

[Paddy McCarthy]

For a book I am working on, I have written a brief (9 page) summary
of Python. The intent of this is that an experienced programmer who
did
not know Python would be able to get enough information to read and
understand Python programs. It is not meant to be a 100% complete
summary of the language, but everything in there should be correct.

The file is at

http://www.proudlyserving.com/language/python.pdf

I have written similar summaries for other languages and will
hopefully post them (with a virtually identical message) in the
appropriate newsgroups in the next few days.

Thank you.

- Adam Barr
(e-mail address removed)

Hi Adam.
First off, Congratulations, I read the Perl and Python PDFs and saw
nothing that I thought you had purposefully written to start a
language war.

I'll confine my comments to the Python PDF (so I don't re-kindle any
wars .


I made a few notes whilst reading through your file that I will add at
the end but I can't help but think that your description of Python is
for using it in an un-Pythonic manner (as others have stated). Whilst
you may explain enough Python for someone to follow any examples you
have in your book, I fear that the algorithms and language structures
that you may use would not be those favoured by Python programmers.
I'll touch on some of these areas later.

The notes are on points roughly in the order given in your document.

1) You mention variable for i and then state that variables cantchange
their type once set. In Python we like to call the 'i' in your example
a name and say it points to an object and that the *object* has a type
and the type of that, individual object will not change. The name can
be made to point to another object that could have a different type
but the type of the first object is not changed.

2) When you introduced slices, slices can have a step as well as a
start and stop.

3) When introducing lists and tuples you want to also explain
im/mutability, i.e. a list type object is said to be mutable
(changeable in some ways), because the individual elements of a list
may be changed on the same list object. A tuple objects elements
cannot be changed (although you may generate a new tuple object based
on an the elements of the first tuple).

3b) You could add that lists and tuples are *ordered* sets of
elements.

4) When you introduce len you might want to add that it returns the
'length' of most collection type objects e.g lists,tuples, and
dictionarys

5) If you define im/mutability you can then say that dictinary keys
can be any immutable object such as integers, strings, tuples but not
lists

6) You didn't mention document strings! When you download Python for
a lot of environments it will come with editors and debuggers that can
use document strings to aid in your coding. The pydoc utility can be
used, with document strings to document (HTML txt) and present
(inbuilt web server and search capability), the documentation for your
program.

7) In your mention of modules you should note that there is an
extensive, well documented, high quality library of modules that comes
as part of the Python installation ready to be included. (Whoops I
started selling Python there


Hey, all that, and not one unkind word about Perl. I'll have to pinch
myself

Paddy.

 

[Adam Barr]

For a book I am working on, I have written a brief (9 page) summary
of Python. The intent of this is that an experienced programmer who
did
not know Python would be able to get enough information to read and
understand Python programs. It is not meant to be a 100% complete
summary of the language, but everything in there should be correct.

The file is at

http://www.proudlyserving.com/language/python.pdf

I have written similar summaries for other languages and will
hopefully post them (with a virtually identical message) in the
appropriate newsgroups in the next few days.

Thank you.

- Adam Barr
(e-mail address removed)

Hi Adam.
First off, Congratulations, I read the Perl and Python PDFs and saw
nothing that I thought you had purposefully written to start a
language war.

I'll confine my comments to the Python PDF (so I don't re-kindle any
wars .


I made a few notes whilst reading through your file that I will add at
the end but I can't help but think that your description of Python is
for using it in an un-Pythonic manner (as others have stated). Whilst
you may explain enough Python for someone to follow any examples you
have in your book, I fear that the algorithms and language structures
that you may use would not be those favoured by Python programmers.
I'll touch on some of these areas later.

The notes are on points roughly in the order given in your document.

1) You mention variable for i and then state that variables cantchange
their type once set. In Python we like to call the 'i' in your example
a name and say it points to an object and that the *object* has a type
and the type of that, individual object will not change. The name can
be made to point to another object that could have a different type
but the type of the first object is not changed.

[other stuff deleted]

Excellent comments, thanks. Especially the comment above about names
vs. objects, that is very clear and I will change it to speak about
them that way.

- adam