Bug? cgi.escape(int)

[Alex Martelli]

Max M wrote:

> Alex Martelli wrote:
> 
>> Therefore, I find your criticism totally unfounded.
> 
> I beg to differ Sire!
> 
> To understand the error message you need to understand the
> implementation of the module. One of the reasons for having modules and
> encapsulation is to minimize the need to know implementation details.

To understand an error message that tells you that the
argument you supplied, of type X, lacks attribute Y, you
need to infer that part of the preconditions is that your
argument MUST supply an attribute Y (there may be others,
of course -- e.g., here, Y must be callable with two
arguments, and return an object such that, etc, etc, but
that's beside the point).


> The message "Argument must be a string", while not technically correct,
> is far easier to understand and in line with the Docs where argument 's'
> is defined as a string.

The docs lie, or, to be more accurate, they use ellipsis:
most of the time they state something "must be an Y", they
mean "must mimic a Y well enough for this function's use".

When you want to mimic "well enough", you need accurate
error messages telling you what went wrong (if anything)
with your mimickry attempts.  *Otherwise* you would need
to study the library's sources, presumably just in order
to acquire exactly those implementation details that you
CLAIM you don't want to know.

>>> print cgi.escape.__doc__
Replace special characters '&', '<' and '>' by SGML entities.

Given THIS doc, and accidentally its appropriate use
of the verb 'replace', I can't agree with criticism
about "missing replace attribute" reminders in errors
when you DO supply objects on which replace can't work.


Alex