Metaclasses & docstrings in 2.2

[Alex Martelli]

James Kew wrote:

> "Alex Martelli" <aleax at aleax.it> wrote in message
> news:JCv%8.110249$Jj7.2629802 at news1.tin.it...
>>
>> When your __init__ (or any other method) *just*
>> delegates to the superclass, and nothing else,
>> simply remove that method's definition from
>> your class -- inherit it rather than going to
>> the trouble of overriding just to delegate,
>> which buys you nothing.
> 
> I was wondering about this recently: I can see that leaving it out is more
> efficient, but leaving it in does make the class slightly easier to use:

Clutter, boilerplate, and duplicated code don't make programs
any easier to use, IMHO.  It's not mostly an issue of the extra
time of an extra function call -- it's about clarity, spareness,
elegance, and usefulness.  Oh, and ease of maintenance, too:-).


> a) clients of the class don't have to wander up the class hierarchy to
> discover what the __init__ parameters are, and

Of course not, print Theclass.__init__.__doc__ will suffice -- but
it works just as well when __init__ is inherited, of course.

> b) writers of subclasses of the class which add their own __init__ don't
> have to wander up the class hierarchy to discover which superclass to call
> __init__ on and what parameters to pass.

You don't need to know what superclass exposes __init__: you can
always call it on your immediate superclass, directly or via the
super built-in.  For parameters, see above.


> I suspect the proper Pythonic answer to both is "document, don't code"?

I'd say both document AND code.  But not DUPLICATE code -- code whose
only purpose in life is complicating everybody's life by duplicating
exactly some feature of some OTHER code, such as a given __init__'s
signature -- clutter source files with such boilerplate, and ensure
problems when something is updated and its must-be-exact copy isn't.

Say my client code uses some class A from library X.  There's another
helpful library Y which wraps X and in particular supplies a class B
that inherits from A and adds a few bells (no whistles yet, but they're
working on it).

Now, a new release of X comes out, the only change I care about being
that A's __init__ has grown a new optional keyword parameter named
encoding with a default value of 'iso-8859-1'.  Cool, I can use that,
as I need the Euro symbol and thus encoding='iso-8859-15' instead.

Oops!  B's __init__ doesn't yet known about the new encoding
parameter, thus I have to curse and hack around the limitation
(having to edit library source is SUCH a deuced, wrecked thing).

Bad enough if that __init__ had a REASON for existing.  When I
find out it's there for *NO* bloody reason whatsoever, *JUST* to
make my life miserable by failing to recognize 'encoding', THAT
is when I'll truly *SCREAM*.

Don't do that.  PLEASE.

In fact: when you wrap a library class, please CONSIDER accepting
arbitrary keyword parameters and passing them up to the superclass's
method that you're overriding-and-delegating-to.  Just in case this
sort of thing happens tomorrow.  Pretty please.

So much for the overriding method serving as "documentation" for
the signature of the superclass method, of course.  I won't miss that.



ALex