[Numpy-discussion] f2py functions, docstrings, and epydoc

[Pearu Peterson]

On Thu, March 27, 2008 7:20 pm, Tom Loredo wrote:
>
> Pearu-
>
>> smll_offset = smll_offset
>> exec `smll_offset.__doc__`
>
> Thanks for the quick and helpful response!  I'll give it
> a try.  I don't grasp why it works, though.  I suppose I don't
> need to, but... I'm guessing the exec adds stuff to the current
> namespace that isn't there until a fortran object's attributes
> are explicitly accessed.
>
> While I have your attention... could you clear this up, also just
> for my curiousity?  It's probably related.

I got this idea from how epydoc gets documentation strings
for variables:

http://epydoc.sourceforge.net/whatsnew.html

according to the variable assignement must follow a string constant
containing documentation.

In our case,

  smll_offset = smll_offset

is variable assignment and

  exec `smll_offset.__doc__`

creates a string constant after the variable assingment.

>> f2py generated functions (that, by the way, are
>> actually instances of `fortran` type and define __call__ method).
>
> I had wondered about this when I first encountered this issue,
> and thought maybe I could figure out how to put some hook into
> epydoc so it would document anything with a __call__ method.
> But it looks like 'fortran' objects *don't* have a __call__
> (here _cbmlike is my f2py-generated module):
>
> In [1]: from inference.count._cbmlike import smllike
>
> In [2]: smllike
> Out[2]: <fortran object at 0x947a668>
>
> In [3]: dir smllike
> ------> dir(smllike)
> Out[3]: ['__doc__', '_cpointer']
>
> In [4]: smllike.__call__
> ---------------------------------------------------------------------------
> AttributeError                            Traceback (most recent call
> last)
>
> /home/inference/loredo/tex/meetings/head08/<ipython console> in <module>()
>
> AttributeError: __call__
>
> Yet despite this apparent absence of __call__, I can magically
> call smllike just fine.  Would you provide a quick explanation of
> what f2py and the fortran object are doing here?

`fortran` object is an instance of a *extension type* `fortran`.
It does not have __call__ method, the extension type has a slot
in C struct that holds a function that will be called when
something tries to call the `fortran` object.

If there are epydoc developers around in this list then here's
a feature request: epydoc support for extension types.

Regards,
Pearu