How do I get info on an exception ?

[Bengt Richter]

On Tue, 22 Jul 2003 16:44:04 -0000, claird at lairds.com (Cameron Laird) wrote:

>Raymond Hettinger <python at rcn.com> wrote:
>>> >You could catch it with:
>>> >
>>> >            except socket.herror, inst:
>>> >                  print inst.args
>>> >
>>> >or more broadly with:
>>> >
>>> >             except socket.error, (errno, string_message):
>>> >                   print code, message
>>> >
>>> >
>>> >> More importantly, where is the answer documented that I should
>>> >> have looked?
>>> >
>>> >The list of possible socket exceptions is in the docs for sockets.
>>> >It also describes the (errno, string) return tuple value of inst.args.
>>> .
>>> .
>>> .
>>> True.
>>>
>>> But unsatisfying--at least to me.
>>
>>Submit a patch.
>			.
>			.
>			.
>I deserved that.
>
>There was more to my post, of course.  Part of what I was trying to
>express is that exception interfaces are almost always relegated to
>a footnote, with only a generalized description, even in the frequent
>case that a method's exceptions are more complicated than its invoca-
>tions.
>
>Rather than tilt at the collection of all such windmills, I want to
>first understand better why this is, and what response is appropriate.
>To summarize:  I don't know what patch is the right one.  I also
>thought it only fair to warn Mr. July that things are indeed more dif-
>ficult than we were explaining, even though I didn't feel up to 
>detailing the difficulties.
>
>So, Raymond, do you have general guidelines for how you think excep-
>tions should be documented?

ISTM there are (at least) two important places for doc info: Code-associated and
language/tool-usage-associated. There are docs we approach as docs like books to read,
and there are embedded docs as in doc strings and comments. And pydoc sort of
bridges the gap and makes a book from code and whatall.

I wonder where the best place is to enhance the documentation accessible to users.
I suspect it would be in the area of pydoc and the structure of "code and whatall."
The most likely place to find up-to-date info is in the latest code. (See below
for an idea of how to enhance the latest code doc info without changing known-good
code source).

Exceptions (subject topic ;-) are a special case. In principle any code documentation
could be enhanced by adopting source conventions to help pydoc present better info.
The question then becomes how best to format the doc-enhancing info, where to put it,
and how best to support its presentation.

One thing that is a deterrent to improved documentation *within* code is that people
like to minimize the number of official code versions, whether by CVS or just noting
MD5 digests etc., and/or by burning an "official" CDROM. This makes me wonder if it would
make sense to have a way to store doc info separately, yet still integratable into a pydoc
presentation.

One way would be to have a file name convention, so that the optional doc-enhancement
info for e.g., xxx.py would be found in, e.g., xxx.dpy. This could make a clutter of small
files though, so maybe one or more .dpx files could contain the mapping from multiple
small related sources to a single .dpy. And by convention .dpy info for packaged files
would be looked for in a .dpy for the overall package if not found separately.

Ok, we could hone this search mechanism. What about the structure of .dpy files themselves,
which now potentially could have info enhancing docs for both xxx.py and yyy.py?

Some kind of easy internal labeled sections to separate xxx.py from yyy.py info
would seem obvious. Then, the real question: what goes in the .dpy section for xxx.py
so as to tie into certain parts of xxx.py code, without requiring changes to that code
(which, remember, may be on a CDROM etc)?

The context-finding mechanism of diff/patch would be one option, but to use that literally
would make the .dpy files into diff files, and probably not something easy to generate
manually and readably. And you don't want to carry a whole source fork just to maintain
doc enhancement .dpy files. So we need some conventions functionally to enable human-doable
doc diff patches. Maybe with special easy syntax to refer to exception raising loci
in the code vs catching, vs functions, classes, methods, existing doc strings, etc, etc.

An advantage of pure doc-enhancement info is that a mistake can't break the actual code,
so more people could be given commit privileges for that kind of files, if maintained
separately on CVS. Even wide-open wiki methods could be considered. You could even configure
pydoc to query python.org efficiently to check if a local cache is out of date, and prompt
for optional download.

But this is a matter of arriving at some PEP consensus after discussing 1) whether it's
worth discussing, and 2) what the usability goals are for both users and creators of
doc enhancement info, and 3) who has the time to follow up on stuff like this.
Just writing this post cost something, as will your replies (if any ;-)

Regards,
Bengt Richter