Raymond Hettinger added the comment: I think the advice should stay as-is. In my experience as a teacher, the possibility doesn't usually occur to people without it having been suggested. Also, it mirrors practices in the standard library (decimal.DecimalException and sqlite3.DatabaseError). For users, it provides a way to catch possible errors that are specific to a particular module. ---------- nosy: +rhettinger _______________________________________ Python tracker https://bugs.python.org/issue34538 _______________________________________

Brett Cannon added the comment: I think the question is how often in real code to people want to catch all exceptions produced by a package or module but not any others. Perhaps it would be better to re-word the advice that when there are many related exceptions that it is suggested you have a base class for them? ---------- nosy: +brett.cannon _______________________________________ Python tracker https://bugs.python.org/issue34538 _______________________________________

Brett Cannon added the comment: I'm not questioning if people have ever created a base exception for an entire package, I'm just asking how often it's actually used when the base exception didn't make sense outside of the rule-of-thumb Nathaniel is pointing out? For instance, it could makes sense in requests' case to have a base exception to help facilitate catching network-related errors but let through e.g. TypeError. But does that extend to most packages such that users regularly write an 'except' clause catching that package's common base exception type? That's my question and I personally don't have an answer beyond reflecting on this and not really remembering a case where I have (I _can_ remember following this pattern simply because it's habit at this point for some unknown reason :) . ---------- _______________________________________ Python tracker https://bugs.python.org/issue34538 _______________________________________

INADA Naoki added the comment: I didn't claim this pattern is not used anymore. My point is "should we suggest this pattern for tutorial readers?" * Is this pattern recommended blindly? -- I think no. * How / when this pattern is recommended? -- When there is use case people want to catch the base exception. * Should it be in tutorial? -- I doubt it. This topic requires some experience to understand. ---------- _______________________________________ Python tracker https://bugs.python.org/issue34538 _______________________________________

Nathaniel Manista added the comment: I’d like to try to steer this conversation back toward what I think is the actionable question: “does the exemplification of this practice in the Errors and Exceptions portion of The Python Tutorial bring about a net benefit or a net cost to its intended audience?”. What is the benefit? It is that when an author happens to be authoring a module *all user-defined Exception subclasses of which satisfy some more-specific-than-Exception type* the author is led to define an intermediate class between Exception and the directly-used user-defined Exception subclasses capturing that type in a usable code element. What readers of the tutorial enjoy this benefit? Pretty much only those authors (who happen to be authoring a module *all user-defined Exception subclasses of which satisfy some more-specific-than-Exception type*) who are still learning about classes and inheritance. That’s a doubly slim population, isn’t it? Maybe also those who kind of know, but aren’t so sure and could use some reinforcement from seeing in the tutorial something that they independently did on their own in their own code. I wouldn’t think that authors who already know with confidence and from experience about classes and inheritance would benefit from the example in the tutorial, so “In my experience as a teacher, the possibility doesn't usually occur to people without it having been suggested” comes as a surprise to me. But… okay, them too - but again, only when they happen to be authoring a module *all user-defined Exception subclasses of which satisfy some more-specific-than-Exception type*. What is the cost? It is that when an author happens to be authoring a module that does *not* have the property that all user-defined Exception subclasses satisfy some more-specific-than-Exception type, the common intermediate class is just bloat. It’s noise disrupting the signal. It undermines the API design advice “when in doubt, leave it out”. It unnecessarily widens the module’s API. It undermines the API design advice “classes are the most complex kind of code element in common use so they have the highest value proposition to satisfy to justify their existence”. It violates the Liskov Substitution Principle. Maybe most importantly, it obscures other relationships among the user-defined Exception subclasses in the module such as a superclass shared by some-but-not-all of the module’s user-defined Exception subclasses, if such other relationships exist. What readers of the tutorial pay this cost? Those who are still learning the language. And those who are following pattern and convention - note that the tutorial contains only one example of user-defined Exception subclasses, and… an unfortunate fact of life of tutorials is that readers are invited to generalize from single examples. And, as I think we’ve seen in this conversation, those who just picked up the practice at one point and have kept it going. The Exception subclass hierarchy of sqlite3 that was mentioned earlier in this conversation demonstrates exactly this bloat and misapplication - there’s Warning, which is a direct subclass of Exception, and there’s Error, which is also a direct subclass of Exception and has the erroneous specification “The base class of the other exceptions in this module”, and there’s DatabaseError, which is a subclass of Error, and then there are IntegrityError, ProgrammingError, OperationalError, and NotSupportedError, which inherit from DatabaseError. What’s the use of Error? There are no code elements in the module specified as raising Error. There’s example code in the module showing “except sqlite3.Error”, but why shouldn’t that be “except sqlite3.DatabaseError”? It’s a red herring is that the practice appears widely applied in existing Python code - well of course; it’s been exemplified in the tutorial for seventeen years! :-P One last thing to consider: look at the example specifically - InputError and TransitionError. There’s no elsewhere-in-the-module example code showing a function that has “Error” in its “Raises:” specification and could raise either an InputError or a TransitionError, and there’s no outside-of-the-module example code showing a user of the module calling a module function and saving duplicated lines of code because they want to respond to InputErrors and TransitionErrors in exactly the same way. We should remove the “Base class for exceptions in this module” Error class from the tutorial’s example because it just isn’t beneficial enough, in enough applicable modules, to enough authors, and it’s more than costly enough, in enough modules to which it doesn’t apply, and to enough authors, even just as noise and API bloat. I don’t know that this could have been calculated from first principles seventeen years ago; I think perhaps it took the experience of having the guidance out there, so rarely merited and so widely implemented, to see it being a net drag. ---------- _______________________________________ Python tracker https://bugs.python.org/issue34538 _______________________________________

Raymond Hettinger added the comment: Guido, the check-in message for this section indicates that Fred Drake added this wording at your behest. Do you still agree with the guidance and examples or would you like to have it removed from all active versions of the documentation as proposed? https://docs.python.org/3.8/tutorial/errors.html#user-defined-exceptions ---------- assignee: docs@python -> gvanrossum nosy: +gvanrossum _______________________________________ Python tracker https://bugs.python.org/issue34538 _______________________________________

Marc-Andre Lemburg added the comment: Just as extra data point: It is fairly common to have a common exception class which is then used a mixin class together with the standard exception classes, so that you can indeed identify the source of an exception and catch errors based on the source (e.g. say you want to catch database errors coming from MySQL specifically). The Python DB-API also requires to create a separate hierarchy for this purpose. Overall, I wouldn't call this a non-best practice. It depends on the use case, whether it's useful or not. ---------- nosy: +lemburg _______________________________________ Python tracker https://bugs.python.org/issue34538 _______________________________________