How should I document exceptions thrown by a method?

[Chris Torek]

>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
>ConfigParser instance.

>> 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,
hence "better".
-- 
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