Re: How to reset document string
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...@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
--
http://mail.python.org/mailman/listinfo/python-list
Re: How to reset document string
Anand K Rayudu schrieb:
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
--
http://mail.python.org/mailman/listinfo/python-list
Re: How to reset document string
On Aug 7, 2:54 am, Anand K Rayudu an...@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
--
http://mail.python.org/mailman/listinfo/python-list
