[GRASS-SVN] r61114 - in grass/trunk/lib/python/pygrass: . modules/interface
svn_grass at osgeo.org
svn_grass at osgeo.org
Wed Jul 2 03:02:41 PDT 2014
Author: zarch
Date: 2014-07-02 03:02:41 -0700 (Wed, 02 Jul 2014)
New Revision: 61114
Modified:
grass/trunk/lib/python/pygrass/functions.py
grass/trunk/lib/python/pygrass/modules/interface/flag.py
grass/trunk/lib/python/pygrass/modules/interface/module.py
grass/trunk/lib/python/pygrass/modules/interface/parameter.py
grass/trunk/lib/python/pygrass/modules/interface/typedict.py
Log:
pygrass: Fix generated documentation for decorated __doc__ methods, for more details about the problem look: https://bitbucket.org/birkenfeld/sphinx/issue/1273/error-when-__doc__-is-a-property, thanks to Luca.
Modified: grass/trunk/lib/python/pygrass/functions.py
===================================================================
--- grass/trunk/lib/python/pygrass/functions.py 2014-07-02 09:01:12 UTC (rev 61113)
+++ grass/trunk/lib/python/pygrass/functions.py 2014-07-02 10:02:41 UTC (rev 61114)
@@ -332,3 +332,60 @@
return False
one = cursor.fetchone() if cursor else None
return True if one and one[0] else False
+
+
+def docstring_property(class_doc):
+ """Property attribute for docstrings.
+ Took from: https://gist.github.com/bfroehle/4041015
+
+ Usage
+ -----
+
+ >>> class A(object):
+ ... '''Main docstring'''
+ ... def __init__(self, x):
+ ... self.x = x
+ ... @docstring_property(__doc__)
+ ... def __doc__(self):
+ ... return "My value of x is %s." % self.x
+
+ >>> A.__doc__
+ 'Main docstring'
+
+ >>> a = A(10)
+ >>> a.__doc__
+ 'My value of x is 10.'
+ """
+ def wrapper(fget):
+ return DocstringProperty(class_doc, fget)
+ return wrapper
+
+
+class DocstringProperty(object):
+ """Property for the `__doc__` attribute.
+
+ Different than `property` in the following two ways:
+
+ * When the attribute is accessed from the main class, it returns the value
+ of `class_doc`, *not* the property itself. This is necessary so Sphinx
+ and other documentation tools can access the class docstring.
+
+ * Only supports getting the attribute; setting and deleting raise an
+ `AttributeError`.
+ """
+
+ def __init__(self, class_doc, fget):
+ self.class_doc = class_doc
+ self.fget = fget
+
+ def __get__(self, obj, type=None):
+ if obj is None:
+ return self.class_doc
+ else:
+ return self.fget(obj)
+
+ def __set__(self, obj, value):
+ raise AttributeError("can't set attribute")
+
+ def __delete__(self, obj):
+ raise AttributeError("can't delete attribute")
Modified: grass/trunk/lib/python/pygrass/modules/interface/flag.py
===================================================================
--- grass/trunk/lib/python/pygrass/modules/interface/flag.py 2014-07-02 09:01:12 UTC (rev 61113)
+++ grass/trunk/lib/python/pygrass/modules/interface/flag.py 2014-07-02 10:02:41 UTC (rev 61114)
@@ -6,6 +6,7 @@
"""
from __future__ import (nested_scopes, generators, division, absolute_import,
with_statement, print_function, unicode_literals)
+from grass.pygrass.functions import docstring_property
from grass.pygrass.modules.interface import read
# TODO add documentation
@@ -50,7 +51,7 @@
def __repr__(self):
return "Flag <%s> (%s)" % (self.name, self.description)
- @property
+ @docstring_property(__doc__)
def __doc__(self):
"""
{name}: {default}
Modified: grass/trunk/lib/python/pygrass/modules/interface/module.py
===================================================================
--- grass/trunk/lib/python/pygrass/modules/interface/module.py 2014-07-02 09:01:12 UTC (rev 61113)
+++ grass/trunk/lib/python/pygrass/modules/interface/module.py 2014-07-02 10:02:41 UTC (rev 61114)
@@ -139,6 +139,7 @@
from grass.script.core import Popen, PIPE
from grass.pygrass.errors import GrassError, ParameterError
+from grass.pygrass.functions import docstring_property
from grass.pygrass.modules.interface.parameter import Parameter
from grass.pygrass.modules.interface.flag import Flag
from grass.pygrass.modules.interface.typedict import TypeDict
@@ -244,7 +245,7 @@
:param max_num_procs: The maximum number of Module processes that
can be run in parallel
- :type max_num_procs: int
+ :type max_num_procs: int
"""
self._num_procs = int(max_num_procs)
self.wait()
@@ -492,7 +493,7 @@
def __repr__(self):
return "Module(%r)" % self.name
- @property
+ @docstring_property(__doc__)
def __doc__(self):
"""{cmd_name}({cmd_params})
"""
@@ -547,7 +548,7 @@
This function will wait for the process to terminate in case
finish_==True and sets up stdout and stderr. If finish_==False this
- function will return after starting the process. Use
+ function will return after starting the process. Use
self.popen.communicate() of self.popen.wait() to wait for the process
termination. The handling of stdout and stderr must then be done
outside of this function.
@@ -555,7 +556,7 @@
if self.inputs['stdin'].value:
self.stdin = self.inputs['stdin'].value
self.stdin_ = PIPE
-
+
cmd = self.make_cmd()
start = time.time()
self.popen = Popen(cmd,
Modified: grass/trunk/lib/python/pygrass/modules/interface/parameter.py
===================================================================
--- grass/trunk/lib/python/pygrass/modules/interface/parameter.py 2014-07-02 09:01:12 UTC (rev 61113)
+++ grass/trunk/lib/python/pygrass/modules/interface/parameter.py 2014-07-02 10:02:41 UTC (rev 61114)
@@ -8,7 +8,7 @@
with_statement, print_function, unicode_literals)
import re
-
+from grass.pygrass.functions import docstring_property
from grass.pygrass.modules.interface.read import GETTYPE, element2dict, DOC
@@ -163,9 +163,7 @@
'raster', 'vector') else self.typedesc,
"yes" if self.multiple else "no")
- # here we use property with a decorator, in this way we mask a method as
- # a class attribute
- @property
+ @docstring_property(__doc__)
def __doc__(self):
"""Return the docstring of the parameter
Modified: grass/trunk/lib/python/pygrass/modules/interface/typedict.py
===================================================================
--- grass/trunk/lib/python/pygrass/modules/interface/typedict.py 2014-07-02 09:01:12 UTC (rev 61113)
+++ grass/trunk/lib/python/pygrass/modules/interface/typedict.py 2014-07-02 10:02:41 UTC (rev 61114)
@@ -12,7 +12,9 @@
except ImportError:
from grass.pygrass.orderdict import OrderedDict
+from grass.pygrass.functions import docstring_property
+
class TypeDict(OrderedDict):
def __init__(self, dict_type, *args, **kargs):
self._type = dict_type
@@ -39,7 +41,7 @@
str_err = 'The value: %r is not a %s instance.'
raise TypeError(str_err % (value, self._type.__name__))
- @property
+ @docstring_property(__doc__)
def __doc__(self):
return '\n'.join([self.__getitem__(obj).__doc__
for obj in self.__iter__()])
More information about the grass-commit
mailing list