How to reset document string

[Anand K Rayudu]

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.

I tried to change <Module>.<MyAPI>.__doc__ = "My new doc"

This failles as it is read only attribute.

Another approach could be calling Py_InitModule("myModuleName",
myMethods); with new help string. But It is not working,
So I am not sure what is the right way to do it

Thanks in advance for all your kind help

Regards,
Anand

 

[Diez B. Roggisch]

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.

I tried to change <Module>.<MyAPI>.__doc__ = "My new doc"

This failles as it is read only attribute.

Another approach could be calling Py_InitModule("myModuleName",
myMethods); with new help string. But It is not working,
So I am not sure what is the right way to do it

To put the right docstrings into the embedded interpreter. I don't know
about your processes, but either the support just suggests better
strings & developers put them in there, or maybe some sort of shared
header-file could be used that the developers use & support enhances.
Something like this:


--- docstrings.h ---

#define VistaDbMethods__doc__ "usage: MyHelp"


And if that's enhanced over time by the support-staff, docs will get
better. Hopefully.

Alternatives are:

- beating your developers with a clue-stick into submission that good
docs are important
- write a usage-guide using e.g. sphinx and release that as add-on-docs.

Diez

 

[Carl Banks]

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