def test_str(self):
uut = DocumentationComment.from_docstring('''
Description of something. No params.
''')
self.assertEqual(str(uut), "Description of something. No params.")
uut = DocumentationComment.from_docstring('''
Description of something with params.
:param x: Imagine something.
:param y: x^2
''')
self.assertEqual(str(uut), "Description of something with params.")
def test_str(self):
uut = DocumentationComment.from_docstring(
'''
Description of something. No params.
''')
self.assertEqual(str(uut), "Description of something. No params.")
uut = DocumentationComment.from_docstring(
'''
Description of something with params.
:param x: Imagine something.
:param y: x^2
''')
self.assertEqual(str(uut), "Description of something with params.")
def from_function(cls, func, omit=frozenset()):
"""
Creates a FunctionMetadata object from a function. Please note that any
variable argument lists are not supported. If you do not want the
first (usual named 'self') argument to appear please pass the method of
an actual INSTANCE of a class; passing the method of the class isn't
enough. Alternatively you can add "self" to the omit set.
:param func: The function. If __metadata__ of the unbound function is
present it will be copied and used, otherwise it will be
generated.
:param omit: A set of parameter names that are to be ignored.
:return: The FunctionMetadata object corresponding to the given
function.
"""
if hasattr(func, "__metadata__"):
metadata = copy(func.__metadata__)
metadata.omit = omit
return metadata
doc = func.__doc__ or ""
doc_comment = DocumentationComment.from_docstring(doc)
non_optional_params = OrderedDict()
optional_params = OrderedDict()
argspec = getfullargspec(func)
args = argspec.args or ()
defaults = argspec.defaults or ()
num_non_defaults = len(args) - len(defaults)
for i, arg in enumerate(args):
# Implicit self argument or omitted explicitly
if i < 1 and ismethod(func):
continue
if i < num_non_defaults:
non_optional_params[arg] = (
doc_comment.param_dict.get(arg, cls.str_nodesc),
argspec.annotations.get(arg, None),
)
else:
optional_params[arg] = (
doc_comment.param_dict.get(arg, cls.str_nodesc)
+ " ("
+ cls.str_optional.format(str(defaults[i - num_non_defaults]))
+ ")",
argspec.annotations.get(arg, None),
defaults[i - num_non_defaults],
)
return cls(
name=func.__name__,
desc=doc_comment.desc,
retval_desc=doc_comment.retval_desc,
non_optional_params=non_optional_params,
optional_params=optional_params,
omit=omit,
)
def from_function(cls, func, omit=frozenset()):
"""
Creates a FunctionMetadata object from a function. Please note that any
variable argument lists are not supported. If you do not want the
first (usual named 'self') argument to appear please pass the method of
an actual INSTANCE of a class; passing the method of the class isn't
enough. Alternatively you can add "self" to the omit set.
:param func: The function. If __metadata__ of the unbound function is
present it will be copied and used, otherwise it will be
generated.
:param omit: A set of parameter names that are to be ignored.
:return: The FunctionMetadata object corresponding to the given
function.
"""
if hasattr(func, "__metadata__"):
metadata = copy(func.__metadata__)
metadata.omit = omit
return metadata
doc = func.__doc__ or ""
doc_comment = DocumentationComment.from_docstring(doc)
non_optional_params = OrderedDict()
optional_params = OrderedDict()
argspec = getfullargspec(func)
args = argspec.args or ()
defaults = argspec.defaults or ()
num_non_defaults = len(args) - len(defaults)
for i, arg in enumerate(args):
# Implicit self argument or omitted explicitly
if i < 1 and ismethod(func):
continue
if i < num_non_defaults:
non_optional_params[arg] = (
doc_comment.param_dict.get(arg, cls.str_nodesc),
argspec.annotations.get(arg, None))
else:
optional_params[arg] = (
doc_comment.param_dict.get(arg, cls.str_nodesc) + " (" +
cls.str_optional.format(str(defaults[i-num_non_defaults]))
+ ")",
argspec.annotations.get(arg, None),
defaults[i-num_non_defaults])
return cls(name=func.__name__,
desc=doc_comment.desc,
retval_desc=doc_comment.retval_desc,
non_optional_params=non_optional_params,
optional_params=optional_params,
omit=omit)
def from_function(cls, func, omit=[]):
"""
Creates a FunctionMetadata object from a function. Please note that any
variable argument lists are not supported. If you do not want the
first (usual named 'self') argument to appear please pass the method of
an actual INSTANCE of a class; passing the method of the class isn't
enough. Alternatively you can add "self" to the omit list.
:param func: The function.
:param omit: A list of parameter names that are to be ignored.
:return: The FunctionMetadata object corresponding to the given
function.
"""
if not isfunction(func) and not ismethod(func):
raise TypeError("function has to be a function")
if not isinstance(omit, list):
raise TypeError("omit has to be a list")
doc = func.__doc__
if doc is None:
doc = ""
doc_comment = DocumentationComment.from_docstring(doc)
non_optional_params = {}
optional_params = {}
argspec = getfullargspec(func)
args = argspec.args if argspec.args is not None else ()
defaults = argspec.defaults if argspec.defaults is not None else ()
num_non_defaults = len(args) - len(defaults)
for i, arg in enumerate(args):
# Implicit self argument or omitted explicitly
if (i < 1 and ismethod(func)) or arg in omit:
continue
if i < num_non_defaults:
non_optional_params[arg] = (
doc_comment.param_dict.get(arg, cls.str_nodesc),
argspec.annotations.get(arg, None))
else:
optional_params[arg] = (
doc_comment.param_dict.get(arg, cls.str_nodesc) + " (" +
cls.str_optional.format(str(defaults[i-num_non_defaults]))
+ ")",
argspec.annotations.get(arg, None),
defaults[i-num_non_defaults])
return cls(name=func.__name__,
desc=doc_comment.desc,
retval_desc=doc_comment.retval_desc,
non_optional_params=non_optional_params,
optional_params=optional_params)
def check_from_docstring_dataset(self,
docstring,
desc="",
param_dict=None,
retval_desc=""):
param_dict = param_dict or {}
self.assertIsInstance(docstring, str,
"docstring needs to be a string for this test.")
doc_comment = DocumentationComment.from_docstring(docstring)
self.assertEqual(doc_comment.desc, desc)
self.assertEqual(doc_comment.param_dict, param_dict)
self.assertEqual(doc_comment.retval_desc, retval_desc)
def from_function(cls, func, omit=[]):
"""
Creates a FunctionMetadata object from a function. Please note that any
variable argument lists are not supported. If you do not want the
first (usual named 'self') argument to appear please pass the method of
an actual INSTANCE of a class; passing the method of the class isn't
enough. Alternatively you can add "self" to the omit list.
:param func: The function.
:param omit: A list of parameter names that are to be ignored.
:return: The FunctionMetadata object corresponding to the given
function.
"""
if not isfunction(func) and not ismethod(func):
raise TypeError("function has to be a function")
if not isinstance(omit, list):
raise TypeError("omit has to be a list")
doc = func.__doc__
if doc is None:
doc = ""
doc_comment = DocumentationComment.from_docstring(doc)
non_optional_params = {}
optional_params = {}
argspec = getfullargspec(func)
args = argspec.args if argspec.args is not None else ()
defaults = argspec.defaults if argspec.defaults is not None else ()
num_non_defaults = len(args) - len(defaults)
for i, arg in enumerate(args):
# Implicit self argument or omitted explicitly
if (i < 1 and ismethod(func)) or arg in omit:
continue
if i < num_non_defaults:
non_optional_params[arg] = (doc_comment.param_dict.get(
arg, cls.str_nodesc), argspec.annotations.get(arg, None))
else:
optional_params[arg] = (
doc_comment.param_dict.get(arg, cls.str_nodesc) +
" (" + cls.str_optional.format(
str(defaults[i - num_non_defaults])) + ")",
argspec.annotations.get(arg, None),
defaults[i - num_non_defaults])
return cls(name=func.__name__,
desc=doc_comment.desc,
retval_desc=doc_comment.retval_desc,
non_optional_params=non_optional_params,
optional_params=optional_params)
def check_from_docstring_dataset(self,
docstring,
desc="",
param_dict=None,
retval_desc=""):
param_dict = param_dict or {}
self.assertIsInstance(docstring,
str,
"docstring needs to be a string for this test.")
doc_comment = DocumentationComment.from_docstring(docstring)
self.assertEqual(doc_comment.desc, desc)
self.assertEqual(doc_comment.param_dict, param_dict)
self.assertEqual(doc_comment.retval_desc, retval_desc)