How to reset document string

[Carl Banks]

On Aug 7, 2:54 am, Anand K Rayudu <an... at esi-india.com> wrote:
> Dear All,
>
> We have extended and embedded python into my our application.
> We exposed few APIs to python using
>
>  Py_InitModule("myModuleName", myMethods);
> where my methods are
>
> static PyMethodDef VistaDbMethods[] = {
>    { (char *)"myAPI",_myAPICFunctionPtr ,METH_VARARGS,"usage: MyHelp)" }
>
> Now problem is ml_doc (Document string). Most of the time the strings
> given by development team is not descriptive enough, so support team
> want to enhance these docstring on need basis and supply to customer
> The idea is we will provide get latest help option from application,
> which will contact our webserver or allow user to pick new help
> document,  which will re apply the help on fly.
>  From then on our script editors will show the new enhanced help.
> How do I achieve this.

Sounds very cool.  I have a few ideas.

1. Since you say you are embedding Python in your application, the
most direct way might be to modify the Python interpreter to allow the
__doc__ attribute to be changed.  You'd have to modify the PyCFunction
type (defined in methodobject.h and methodobject.c) to allow
overriding the compiled-in doc field.

2. Instead of replacing the __doc__ attribute of the function, just
replace the whole function with a wrapper.  So, for instance, if your
application decides to update the docstring for myModuleName.myAPI(),
instead of running code like this:

    myModuleName.myAPI.__doc__ = 'new docstring'

run code like this:

    def create_wrapper(func,docstring):
        def wrapper(*args):
            return func(*args)
        wrapper.__doc__ = doc
        return wrapper
    myModuleName.myAPI = create_wrapper(
                 myModuleName.myAPI,'new docstring')

So now myApi is a Python function with the new docstring that calls
the old function.  (Note: if you are concerned with efficiency, it's
possible to write a wrapper in C that has very little overhead.)

This approach has minor disadvantages (such as if any code write from
myModuleName import myAPI--it won't see the new version) but it may be
the easiest approach.

3. Instead of customizing the __doc__ attribute, store any custom
docstrings in a dictionary keyed by the function.

    custom_doc[myModuleName.myApi] = 'new docstring'

Your script editor, when looking for documentation, will first search
in this custom area to see if the docstring has been overridden; if
so, use that; if not, use the docstring.  Something like this:

    def documentation_to_use_in_script_editor(func):
        try:
            return custom_doc[func]
        except KeyError:
            return func.__doc__

That has the negative of the special docstring not being visible at an
interactive prompt.


I have given you some fairly vague answers, hopefully that'll give you
some idea.  It sounds like you have an ambitious project, suggesting
that you are probably good enough to implement the suggestions.


Carl Banks