Raise vs throw in docs

Terminology: are the terms “raise” and “throw” when talking about exceptions in the docs considered entirely equivalent? Obviously, one is a language keyword and the other is not. A little muddled in that generators have a throw method, but disregarding that… is this anything to care about? I have a bit of background in standards work, so I tend to expect precise terminology, more so perhaps than is always needed; meanwhile the Web is pretty imprecise about this, you see mention of throwing exceptions and throwing errors in Python all the time. We can’t control the Web, of course, so this question is only about Python’s own docs, and I do admit doubt whether this would confuse any moderately experienced programmer.

Example:
os — Miscellaneous operating system interfaces — Python 3.11.0 documentation - os.supports_dir_fd and os.supports_follow_symlinks describe “throw” while tons of other mentions are all to “raise”.

It would be nice if we used consistent, accurate and precise terminology, particularly where it is helpful to do :keyword:`raise`, which uses the appropriate semantic markup and links to more information about the keyword (isn’t always appropriate, of course, but certainly some of the time), especially in API/Reference type documentation. That said, while this would be the kind of thing I might fix when revising a section, adding new content or making other changes, and perhaps we could document and provide devguide guidance on, I’m not sure its worth making PRs just to change this (not sure that’s what is being suggested, just want to mention that).

1 Like

Consistency is important,

but

what does the except keyword do? It catches exceptions, right? So by symmetry, the raise keyword throws them.

¯\_(ツ)_/¯

Regaring the two terms’ equivalency, they are entirely equivalent. I prefer to use “raise” because that matches the keyword, and not too long ago we would always use that. I’m guessing “throw” has been popularized by other languages, but it is not Python’s term of preference.

The generator throw() method is called that because we can’t use a keyword like raise as a method name. It does lend credibility to the equivalency of the two terms.

By all means let’s not start submitting PRs that “fix” uses of “throw” where “raise” could be used. That’s just noise, and serves no purpose of clarification. (If this were a standard, I’d just state “raise and throw are equivalent” at the start so in the rest of the text we wouldn’t have to care.)

7 Likes

Certainly wasn’t going to start pushing PRs, I can’t even get around to doing the one on glob() that I raised (sorry for possible pun) a couple of months back. Maybe that mention in the devguide makes sense, affirming that “raises” is the preferred term, but the other is not incorrect - or maybe that’s so vague it doesn’t even help.

Oh, I wasn’t worried about you, just about other folks who might read this and get ideas… :slight_smile:

I honestly don’t think this is worth documenting beyond this thread. If CAM disagrees he can make the devguide PR. :slight_smile:

1 Like

Nah, we are of the same mind here (on both points) :+1:

I suppose that there was is a similar (and opposite) situation in C++. They use the “throw” keyword because “raise” was already used as a function name in Posix. Other programming laguages inherited that from C++.

As far as I remember, I did that many years ago – replaced many “throws” with “raises” if it was appropriate. The few remaining “throws” were most likely added after that, or there were reasons to keep them (if they refer to the generator throw() method or other meaning of this word).

3 Likes