sebastien / sdoc Goto Github PK

== SDoc
== Cool Python Documentation Generators
-- Author: Sebastien Pierre
-- Date: 08-Apr-2006

There are many Python API documenters, ...

Implementation notes
====================

Although Python is a very versatile language, and features amazing introspection
capabilities, implementing SDoc clearly shed some lights on some darker parts of
the language.

Accessing methods in classes:

    I learned that when you reference a class, say `o = optparser.OptionParser`,
    and that you want to get the `id` of a class particular method, you will get
    the following results:

    >   >>> id(o.set_default)
    >   -1210410132
    >   >>> id(o.set_default)
    >   -1210530556
    >   >>> id(o.set_default)
    >   -1210530556
    >   >>> id(o.has_option)
    >   -1210530556

    The conclusion is that methods, which are actually _unbound methods_ are
    instantiation at each access (I guess when the object is constructed), so you
    don't get the same object between two access to a method in a class.

    Moreover, in the above example, we have similar ids for two different
    methods, probably due to Python pooling and recycling unreferenced objects.

Some classes have no `ClassType` class:

    It seems like C-implemented Python classes do not have the `ClassType` type.
    For instance, I found that most classes of [Redland](http://www.librdf.org)
    Python package (`import RDF`) have no type:

    >   >>> type(RDF.Storage)
    >   <type 'type'>
    >   >>> type(RDF.Statement)
    >   <type 'type'>
    >   >>> repr(RDF.Storage)
    >   "<class 'RDF.Storage'>"
    >   >>> repr(RDF.Statement)
    >   "<class 'RDF.Statement'>"
    >   >>> type(optparse.OptionParser)
    >   <type 'classobj'>

    So I had to base the type detection on the `repr` of the class.

# vim: sw=4 ts=4 et