How should I document exceptions thrown by a method?
nospam at torek.net
Thu Jul 28 03:47:18 CEST 2011
>Arcadio <arcadiosincero at gmail.com> writes:
>> I have a Settings class that is used to hold application settings. A
>> Settings object initializes itself from a ConfigParser that gets
>> passed in as an argument to the constructor.
In article <87oc0fpg9o.fsf at benfinney.id.au>
Ben Finney <ben+python at benfinney.id.au> wrote:
>So the caller is aware of, and takes responsibility for, the
>> If a setting isn't found in whatever the ConfigParser is reading
>> settings from, the ConfigParser's get() method will raise an
>> exception. Should I just say that clients of my Settings class should
>> be prepared to catch exceptions thrown by ConfigParser? Do I even have
>> to mention that as it might be just implied?
>In this case IMO it is implied that one might get exceptions from the
>object one passes as an argument to a callable.
Yes. But on the other hand:
>>> import this
The Zen of Python, by Tim Peters
Beautiful is better than ugly.
Explicit is better than implicit.
I would suggest that in this case, too, "explicit is better than
implicit": the documentation should say "will invoke x.get() and
therefore propagate any exception that x.get() might raise".
>> Or should Setting's constructor catch any exceptions raised by the
>> ConfigParser and "convert it" to a Settings- specific exception class
>> that I then document?
>Please, no. Since the ConfigParser object was created and passed in by
>the calling code, the calling code needs to know about the exceptions
>from that object.
In *some* cases (probably not applicable here), one finds a good
reason to transform one exception to another. In this case I agree
with Ben Finney though, and so does "import this":
Simple is better than complex.
Letting exceptions flow upward unchanged is (usually) simpler,
In-Real-Life: Chris Torek, Wind River Systems
Intel require I note that my opinions are not those of WRS or Intel
Salt Lake City, UT, USA (40°39.22'N, 111°50.29'W) +1 801 277 2603
email: gmail (figure it out) http://web.torek.net/torek/index.html
More information about the Python-list