Why "class exceptions" are not deprecated?

[Gregory Petrosyan]

1) From 2.4.2 documentation:
There are two new valid (semantic) forms for the raise statement:
raise Class, instance
raise instance

2) In python:Traceback (most recent call last):
Traceback (most recent call last):
File "<stdin>", line 1, in ?
TypeError: exceptions must be classes, instances, or strings
(deprecated), not i
nt

So, if it's a bug in documentation, it should be corrected. Otherwise,
(IMHO!) raising classes should be deprecated. Does raising class make
sence? As for me, I can't find any usefull case for it.

 

[Fredrik Lundh]

1) From 2.4.2 documentation:
There are two new valid (semantic) forms for the raise statement:
raise Class, instance
raise instance

2) In python:
Traceback (most recent call last):

Traceback (most recent call last):
File "<stdin>", line 1, in ?
TypeError: exceptions must be classes, instances, or strings
(deprecated), not i
nt

So, if it's a bug in documentation, it should be corrected. Otherwise,
(IMHO!) raising classes should be deprecated.

it could be that the tutorial author expected you to read chapter 8
before you read chapter 9, and used "new" to mean forms that hadn't
already been described:

http://docs.python.org/tut/node10.html

Does raising class make sence? As for me, I can't find any usefull
case for it.

as explained in the language reference,

raise Class

is the same thing as

raise Class()

</F>

 

[Gregory Petrosyan]

Thanks for answer. But what about "Explicit is better than implicit"?

 

[Gregory Petrosyan]

"The first argument to raise names the exception to be raised. The
optional second argument specifies the exception's argument.
Alternatively, the above could be written as raise
NameError('HiThere'). Either form works fine, but there seems to be a
growing stylistic preference for the latter."

Are there any deprecation plans?

 

[Fredrik Lundh]

Thanks for answer. But what about "Explicit is better than implicit"?

"Practicality beats purity"

Changing the language just because some random guy on a newsgroup
read the tutorial backwards isn't really practical.

</F>

 

[Steven Bethard]

1) From 2.4.2 documentation:
There are two new valid (semantic) forms for the raise statement:
raise Class, instance
raise instance

Check `PEP 8`_ -- the latter form is preferred:

"""
When raising an exception, use "raise ValueError('message')" instead of
the older form "raise ValueError, 'message'".
"""

... _PEP 8: http://www.python.org/dev/peps/pep-0008/

STeVe

 

[Terry Reedy]

Are there any deprecation plans?

In Python 3, many redundant options will likely be eliminated, including
some for the raise statement.

 

[rurpy]

it could be that the tutorial author expected you to read chapter 8
before you read chapter 9, and used "new" to mean forms that hadn't
already been described:

http://docs.python.org/tut/node10.html


as explained in the language reference,

raise Class

is the same thing as

raise Class()

The OP points out an ambiguity in the docs, and as usual,
gets told he can't read, etc. How typical. Maybe if comments
like this were encouraged and acted upon, the docs would be
a little better than they are. But I guess the current practice
of intimidation has benefits too in that it allows the response,
"nobody has complained, so the docs must be really great
and we can go on writing Python instead of that grungy
English."

And maybe if there were a decent language reference manual
people wouldn't be so inclined to use the Tutorial as one, with
the resultant out-of-sequence reading.

 

[Fredrik Lundh]

The OP points out an ambiguity in the docs, and as usual,
gets told he can't read, etc. How typical.

where did anyone tell the OP that he can't read? it's pretty clear
that you have trouble reading things without mixing them up with
your own preconceptions, but we already knew that.

Maybe if comments like this were encouraged and acted upon

do you think your posts would look any different if we replaced you
with a markov generator and fed it with your old posts ?

if you want to contribute, contribute. a new tutorial would be great.
get to work!

</F>

 

[rurpy]

where did anyone tell the OP that he can't read?

"it could be that the tutorial author expected you
to read chapter 8 before you read chapter 9,..."

"...because some random guy on a newsgroup read
the tutorial backwards..."

it's pretty clear
that you have trouble reading things without mixing them up with
your own preconceptions, but we already knew that.111

do you think your posts would look any different if we replaced you
with a markov generator and fed it with your old posts ?

if you want to contribute, contribute. a new tutorial would be great.
get to work!

I don't want to, and probably couldn't, write a tutorial
as good as what is already there. But what I can do is
report problems I find when using it, and make suggestions
about how to avoid those problems. For example, the
sentence in question,

"There are two new valid (semantic) forms for the
raise statement: "

could be replaced with

"There are two other forms for the raise statement
in addition to the one described in chapter 8:"

or

"Two new forms for the raise statement were introduced
in Python verion 2.x:"

depending on what the meaning of "new" is in the
original sentence. (I'm still not sure, but your post
implies it is the former.)

But the perception I get here, from responses like yours,
is that such suggestions are unwelcome, and unlikely
to be acted upon. I gather corrections of factual
errors are welcome, but stylistic, or organizational
ones are not. And the latter kind of changes, applied
extensively to all the docs, are what will make a big
improvement. Difficult at best, but absolutely impossible
if you and the other powers-that-be are happy with
the status-quo.

 

[Terry Reedy]

"it could be that the tutorial author expected you
to read chapter 8 before you read chapter 9,..."

This actually acknowledges an ability to read ;-)
-- that just was not exercised sufficiently (in his opinion) ...

as good as what is already there. But what I can do is
report problems I find when using it, and make suggestions
about how to avoid those problems. For example, the
sentence in question,

"There are two new valid (semantic) forms for the
raise statement: "

could be replaced with

"There are two other forms for the raise statement
in addition to the one described in chapter 8:"

That said, and without looking at the context in the doc, this looks like
an improvement.

or

"Two new forms for the raise statement were introduced
in Python verion 2.x:"

This is incorrect, I believe.

depending on what the meaning of "new" is in the
original sentence. (I'm still not sure, but your post
implies it is the former.)

I agree that the current text seems ambiguous.

But the perception I get here, from responses like yours,
is that such suggestions are unwelcome, and unlikely
to be acted upon.

FL is not the main doc maintainer. Even if you were to be correct about
his views, premature generalization is the source of much error.

I gather corrections of factual
errors are welcome, but stylistic, or organizational
ones are not. And the latter kind of changes, applied
extensively to all the docs, are what will make a big
improvement. Difficult at best, but absolutely impossible
if you and the other powers-that-be are happy with
the status-quo.

If you wish to become a volunteer Python improver, let me know either here
or privately and I will respond with a suggestion and an offer.

Terry Jan Reedy

 

[Fredrik Lundh]

(e-mail address removed) wrote

"it could be that the tutorial author expected you
to read chapter 8 before you read chapter 9,..."

What makes you so sure that wasn't a statement about the tutorial ?

"...because some random guy on a newsgroup read
the tutorial backwards..."

Does the word "context" mean anything to you? or the word "de-
precation", that was used multiple times by the OP ? Or the phrase
"changing the language", that you cut out from that quote.

I don't want to, and probably couldn't

That's pretty obvious.

write a tutorial as good as what is already there. But what I can
do is report problems I find when using it, and make suggestions
about how to avoid those problems.

There's no shortage of ideas -- nor people who can write a tutorial
that's better than the current one (which is far from optimal, mostly
thanks to a zillion peephole edits over the years). There's a shortage
of volunteer time, though. That's why the "I'm just the idea guy,
someone else will have to provide the hundreds of hours required
to implement my idea" arguments are so offensively meaningless.

Come up with an idea that *reduces* the overall work needed to write
and maintain a good manual, and people might start listening to what
you have to say.

Or come up with some money. If you can fund a technical writer for
one year, there are lots of things that could be done.

But the perception I get here, from responses like yours,
is that such suggestions are unwelcome, and unlikely
to be acted upon. I gather corrections of factual
errors are welcome, but stylistic, or organizational
ones are not. And the latter kind of changes, applied
extensively to all the docs, are what will make a big
improvement. Difficult at best, but absolutely impossible
if you and the other powers-that-be are happy with
the status-quo.

The problem with people like you is that you are completely ignoring
all the hard work done by the people who build the free stuff that
anonymous cowards like you like to complain about.

Luckily, most people are not like you. If they were, nothing would
ever happen.

</F>

 

[Ed Singleton]

(e-mail address removed) wrote

There's no shortage of ideas -- nor people who can write a tutorial
that's better than the current one (which is far from optimal, mostly
thanks to a zillion peephole edits over the years). There's a shortage
of volunteer time, though. That's why the "I'm just the idea guy,
someone else will have to provide the hundreds of hours required
to implement my idea" arguments are so offensively meaningless.

I'm not entirely sure there is a shortage of people who want to
volunteer, just that a lot don't know that they can volunteer, and
those that do can't make a huge time commitment or don't have the
confidence.

I think there's quite a lot of people who would be happy to help out
as and when they could (particularly with small edits like the one
mentioned), if they were sure someone else was going to double check
that they hadn't accidentally written garbage.

This would be a perfect situation for a wiki. I think it would be a
good experiment to have a wiki containing the documentation (separate
from the main documentation and clearly marked experimental for the
moment), and to see if it did self-organise as wikis often do.
Beginners like rurpy could add comments when they don't understand a
paragraph, more confident people could attempt to correct the
paragraph, and every now and then an advanced person could scan
through it and make sure it was truly accurate.

It would greatly reduce the work need by the people currently
responsible for documentation (they just have to read through and make
sure things are correct) and if a page has been significantly improved
by the community and double checked by an expert, it could be promoted
to the official version of the documentation.

If the whole thing descends into chaos, the wiki (pages) could just be
deleted and we continue with the current system.

As Python has such an excellent community, it would be a shame not to
give them more responsibility in this area, and this system seems to
be working quite well for many python projects (many just use the wiki
in Trac).

Ed

(I'm actually tempted to just copy and paste each page from the
tutorial into the current wiki but I'd hate for it all to be deleted
after doing that).

 

[Fredrik Lundh]

This would be a perfect situation for a wiki. I think it would be a
good experiment to have a wiki containing the documentation (separate
from the main documentation and clearly marked experimental for the
moment), and to see if it did self-organise as wikis often do.
agreed.

It would greatly reduce the work need by the people currently
responsible for documentation (they just have to read through and make
sure things are correct) and if a page has been significantly improved
by the community and double checked by an expert, it could be promoted
to the official version of the documentation.

absolutely.

(and promoting could simply be done by tagging a given wiki revision as
the official source, using something like http://effbot.org/django-pageview
or a static version thereof, as the front-end renderer)

If the whole thing descends into chaos, the wiki (pages) could just be
deleted and we continue with the current system.

As Python has such an excellent community, it would be a shame not to
give them more responsibility in this area

the entire python.org site (and Python) would benefit for improved support
for micro-contributions, but I doubt that will ever happen under the current
regime.

(I'm actually tempted to just copy and paste each page from the
tutorial into the current wiki but I'd hate for it all to be deleted
after doing that).

just do it!

</F>

 

[Fredrik Lundh]

(I'm actually tempted to just copy and paste each page from the

just do it!

btw, one alternative could be to use an infogame site for this purpose:

http://infogami.com

this gives you revision history, a permissions system (limiting editing to
registered users might be a good idea), comments, an associated blog,
voting, feeds, change logs, etc.

to convert the current tutorial to infogami-compatible markup, use this:

http://www.aaronsw.com/2002/html2text/

</F>

 

[Fredrik Lundh]

btw, one alternative could be to use an infogame site for this purpose:

http://infogami.com

this gives you revision history, a permissions system (limiting editing to
registered users might be a good idea), comments, an associated blog,
voting, feeds, change logs, etc.

alright, I got bored and uploaded a copy of the current Python tutorial to

http://pytut.infogami.com

</F>

 

[Ed Singleton]

alright, I got bored and uploaded a copy of the current Python tutorial to

http://pytut.infogami.com

Damn. You beat me to it by an hour.

http://singletoned.infogami.com/_special/index

I had a nightmare with character encodings (mainly because I'm
terrible with them). I have a script written that does it all for me,
but it keeps choking on characters. I just tried randomly converting
things to Unicode at various points for over an hour until it worked.

Ed

 

[Ed Singleton]

Damn. You beat me to it by an hour.

http://singletoned.infogami.com/_special/index

I had a nightmare with character encodings (mainly because I'm
terrible with them). I have a script written that does it all for me,
but it keeps choking on characters. I just tried randomly converting
things to Unicode at various points for over an hour until it worked.

Ed

Also, your looks better than mine. Did you write a script to do the
table of contents too?

Ed

 

[Fredrik Lundh]

Damn. You beat me to it by an hour.

http://singletoned.infogami.com/_special/index

oops. sorry for that.

sounds weird. iirc, there were only one page that contained non-ascii
characters, and the latest html2text.py script had no problems dealing
with that one.

Also, your looks better than mine.

did you look at it before or after I added the new stylesheet? ;-)

Did you write a script to do the table of contents too?

nope; I did that all by hand. I plan to write some scripts to get contents
*out* of infogami, though, but that'll have to wait for some other day.

anyway, do you want to keep your version, or should we "standardize" on
the pytut version ? and are there any willing community contributors out
there?

</F>

 

[Ed Singleton]

oops. sorry for that.

Not at all. I'm quite proud that it was only an hour.

sounds weird. iirc, there were only one page that contained non-ascii
characters, and the latest html2text.py script had no problems dealing
with that one.

node4 and node5 caused problems for me. I'm still struggling a bit
with character encodings so that probably caused most of my problems.

did you look at it before or after I added the new stylesheet? ;-)

Before. Now it looks gorgeous.

nope; I did that all by hand. I plan to write some scripts to get contents
*out* of infogami, though, but that'll have to wait for some other day.

anyway, do you want to keep your version, or should we "standardize" on
the pytut version ? and are there any willing community contributors out
there?

Standardise on yours obviously, though I might keep mine around to
keep playing with the script. It's a bit clumsy at the moment, but I
can see there's some potential there for having a general script to
rip content out of sites and put it in a wiki (if only for the rest of
the python docs, should this project succeed). I'd also be interested
in seeing how you did it as it would be the first time I could
directly compare what I did to how an expert does it.

I'd suggest adding some sort of guidance page so that people know
roughly what's expected. IE can they just add questions and comments
into the text, hoping that someone more knowledgeable will sort it out
(or delete it).

Ed