How to reset document string

[Anand K Rayudu]

Dear Carl,

Your ideas are extremely good, and I liked idea 2 especially, based on 
that I am considering following approach.
Eg: let us say I have module named myModule and exposing myModule.myAPI
So I will now rename myModule as _myModule and write a python layer with 
myModule

So my python layer will look like this

file name myModule.py

import _myModule

def myAPI(arg1, arg2):
    """
   @param  arg1 help string
   @param  arg2 help string
   """"
       _myModule.myAPI(arg1,arg2) # actual API

So I will provide mechanism which reads the help files and generates 
this binding python file and reload the module,
So now my python editor has the new python strings.
Also another advantages of this approach is if customer choses his own 
IDE he will still get the documentation of our APIs, by just ensuring 
these python files are in PYTHON_PATH
I think this is better approach, kindly please let me know your comments



Regards,
Anand


  

 
> 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
>   

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-list/attachments/20090814/54bdee38/attachment-0001.html>