def test_params_py3(self):
method = \
"""
def method(p1, p2: int,
p3=3, p4={'a':'b'},
p5=[1,2,3], p6=True,
p7=set([1,2,3]), p8={1,2,3},
p9=(1,2,3)):
pass
"""
docstring = generate_docstring(
method, position=(2, 2), formatter="google")
expected = """
Args:
p1 (TYPE): \n\
p2 (int): \n\
p3 (int): default: ``3``
p4 (dict): default: ``{'a':'b'}``
p5 (list): default: ``[1,2,3]``
p6 (bool): default: ``True``
p7 (set): default: ``set([1,2,3])``
p8 (set): default: ``{1,2,3}``
p9 (tuple): default: ``(1,2,3)``
"""
assert docstring == expected
def test_module_attributes(self):
module = \
"""
from somewhere import var
mattr1 = 3 * var
mattr2 = 2
def some_func():
pass
class InnerClass():
pass
"""
docstring = generate_docstring(module,
position=(2, 2),
formatter="reST")
expected = """
:var mattr1: 3 * var
:type mattr1: TYPE
:var mattr2: 2
:type mattr2: int
"""
assert docstring == expected
def test_yields_statement_multiline(self):
method = \
"""
def method():
\"\"\"
yield {
2:3
}
"""
docstring = generate_docstring(method,
position=(3, 7),
formatter="numpy",
autocomplete=True)
expected = """
Yields
------
TYPE
{ 2:3 }
"""
assert docstring == expected
def test_params_no_literal_set(self):
method = \
"""
def method(p1, p2=2,
p3=3, p4={'a':'b'},
p5=[1,2,3], p6=True,
p7=set([1,2,3]),
p9=(1,2,3)):
pass
"""
docstring = generate_docstring(method,
position=(2, 2),
formatter="reST")
expected = """
:param p1: \n\
:type p1: TYPE
:param p2: default: ``2``
:type p2: int
:param p3: default: ``3``
:type p3: int
:param p4: default: ``{'a':'b'}``
:type p4: dict
:param p5: default: ``[1,2,3]``
:type p5: list
:param p6: default: ``True``
:type p6: bool
:param p7: default: ``set([1,2,3])``
:type p7: set
:param p9: default: ``(1,2,3)``
:type p9: tuple
"""
assert docstring == expected
def test_two_exceptions(self):
method = \
"""
def method():
\"\"\"
if 1==1:
raise MyException()
else:
raise Exception
"""
docstring = generate_docstring(method,
position=(3, 7),
formatter="numpy",
autocomplete=True)
expected = """
Raises
------
MyException
\n\
Exception
\n\
"""
assert docstring == expected
def test_class_attributes(self):
code = \
"""
class HelloWorld():
\"\"\"
attr1 = 3 * some_var
attr2 = 2
def some_func():
pass
class InnerClass():
pass
"""
docstring = generate_docstring(code,
position=(3, 7),
formatter="numpy",
autocomplete=True)
expected = """
Attributes
----------
attr1 : TYPE
3 * some_var
attr2 : int
2
"""
assert docstring == expected
def test_module_attributes(self):
module = \
"""\
\"\"\"
from somewhere import var
mattr1 = 3 * var
mattr2 = 2
def some_func():
pass
class InnerClass():
pass
"""
docstring = generate_docstring(module,
position=(1, 3),
formatter="numpy",
autocomplete=True)
expected = """
Attributes
----------
mattr1 : TYPE
3 * var
mattr2 : int
2
"""
assert docstring == expected
def test_two_exceptions(self):
method = \
"""
def method():
if 1==1:
raise MyException()
else:
raise Exception
"""
docstring = generate_docstring(
method, position=(2, 2), formatter="numpy")
expected = """
Raises
------
MyException
\n\
Exception
\n\
"""
assert docstring == expected
def test_none(self):
module = ""
docstring = generate_docstring(
module, position=(1, 0), formatter="google")
expected = """
Empty Module
"""
assert docstring == expected
def main(): #pragma: no cover
"""
CLI entrypoint
"""
parser = argparse.ArgumentParser(prog="pydocstring")
parser.add_argument("source",
type=str,
help="Source code to process, or the path to a file")
parser.add_argument(
"position",
nargs="?",
type=ast.literal_eval,
help="Position of the cursor in the document, defaults to the end. \
Row, then column, presented as a string python tuple. E.g. '(10, 15)'"
)
parser.add_argument("-f",
"--formatter",
choices=['google', 'numpy', 'reST'],
default='google',
type=str,
help="docstring formatter to use")
parser.add_argument('--version',
action='version',
version='%(prog)s {0}'.format(pydocstring.__version__))
parser.add_argument('--debug',
action="store_true",
help="Show stacktraces")
args = parser.parse_args()
source = args.source
if os.path.exists(args.source):
with open(args.source) as source_file:
source = source_file.read()
lines = source.splitlines()
position = tuple(args.position) if args.position else (len(lines),
len(lines[-1]))
print(position)
try:
output = pydocstring.generate_docstring(source,
position=position,
formatter=args.formatter)
print('"""\n' + output + '"""\n')
except Exception as ex:
if args.debug:
raise ex
sys.stderr.write(
"Could not generate a docstring for the given source:\n")
sys.stderr.write(repr(ex))
sys.exit(1)
def test_none(self):
module = """\
\"\"\"\
"""
docstring = generate_docstring(module,
position=(1, 0),
formatter="numpy",
autocomplete=True)
expected = """
Empty Module
"""
assert docstring == expected
def test_one_exception_uninstantiated(self):
method = \
"""
def method():
raise MyExceptionUninstantiated
"""
docstring = generate_docstring(
method, position=(2, 2), formatter="google")
expected = """
Raises:
MyExceptionUninstantiated: \n\n"""
assert docstring == expected
def test_return_statement_expression(self):
method = \
"""
def method():
return 2*2
"""
docstring = generate_docstring(
method, position=(2, 2), formatter="google")
expected = """
Returns:
TYPE: 2*2
"""
assert docstring == expected
def test_return_annotation_only(self):
method = \
"""
def method() -> int:
pass
"""
docstring = generate_docstring(
method, position=(2, 2), formatter="google")
expected = """
Returns:
int: \n\
"""
assert docstring == expected
def test_return_statement_simple(self):
method = \
"""
def method():
return var1
"""
docstring = generate_docstring(method,
position=(2, 2),
formatter="reST")
expected = """
:return: var1
:rtype: TYPE
"""
assert docstring == expected
def test_return_type_and_statement(self):
method = \
"""
def method() -> int:
return var1
"""
docstring = generate_docstring(
method, position=(2, 2), formatter="google")
expected = """
Returns:
int: var1
"""
assert docstring == expected
def test_params_args_kwargs(self):
method = \
"""
def method(*args, **kwargs):
pass
"""
docstring = generate_docstring(
method, position=(2, 2), formatter="google")
expected = """
Args:
*args: Variable length argument list.
**kwargs: Arbitrary keyword arguments.
"""
assert docstring == expected
def test_return_statement_expression(self):
method = \
"""
def method():
return 2*2
"""
docstring = generate_docstring(method,
position=(2, 2),
formatter="reST")
expected = """
:return: 2*2
:rtype: TYPE
"""
assert docstring == expected
def test_params_args_kwargs(self):
method = \
"""
def method(*args, **kwargs):
\"\"\"
pass
"""
docstring = generate_docstring(method,
position=(3, 7),
formatter="reST")
expected = """
:param *args: Variable length argument list.
:param **kwargs: Arbitrary keyword arguments.
"""
assert docstring == expected
def test_return_statement_multiline(self):
method = \
"""
def method():
return {
'a':'b'
}
"""
docstring = generate_docstring(
method, position=(2, 2), formatter="google")
expected = """
Returns:
TYPE: { 'a':'b' }
"""
assert docstring == expected
def test_return_annotation_only(self):
method = \
"""
def method() -> int:
pass
"""
docstring = generate_docstring(method,
position=(2, 2),
formatter="reST")
expected = """
:return: \n\
:rtype: int
"""
assert docstring == expected
def test_one_exception_instantiated(self):
method = \
"""
def method():
raise MyException()
"""
docstring = generate_docstring(method,
position=(2, 2),
formatter="reST")
expected = """
:raises MyException: \n\
"""
assert docstring == expected
def test_yields_statement_simple(self):
method = \
"""
def method():
yield var1
"""
docstring = generate_docstring(
method, position=(2, 2), formatter="google")
expected = """
Yields:
TYPE: var1
"""
assert docstring == expected
def test_yield_statement_expression(self):
method = \
"""
def method():
yield 2*2
"""
docstring = generate_docstring(method,
position=(2, 2),
formatter="reST")
expected = """
:yields: 2*2
:ytype: TYPE
"""
assert docstring == expected
def test_return_statement_simple(self):
method = \
"""
def method():
return var1
"""
docstring = generate_docstring(
method, position=(2, 2), formatter="numpy")
expected = """
Returns
-------
TYPE
var1
"""
assert docstring == expected
def test_yield_statement_simple(self):
method = \
"""
def method():
yield var1
"""
docstring = generate_docstring(method,
position=(2, 2),
formatter="reST")
expected = """
:yields: var1
:ytype: TYPE
"""
assert docstring == expected
def test_yields_statement_expression(self):
method = \
"""
def method():
yield 2*2
"""
docstring = generate_docstring(
method, position=(2, 2), formatter="numpy")
expected = """
Yields
------
TYPE
2*2
"""
assert docstring == expected
def test_return_statement_expression(self):
method = \
"""
def method():
\"\"\"
return 2*2
"""
docstring = generate_docstring(method,
position=(3, 7),
formatter="reST",
autocomplete=True)
expected = """
:return: 2*2
:rtype: TYPE
"""
assert docstring == expected
def test_return_type_and_statement(self):
method = \
"""
def method() -> int:
\"\"\"
return var1
"""
docstring = generate_docstring(method,
position=(3, 7),
formatter="reST",
autocomplete=True)
expected = """
:return: var1
:rtype: int
"""
assert docstring == expected
def test_one_exception_uninstantiated(self):
method = \
"""
def method():
\"\"\"
raise MyExceptionUninstantiated
"""
docstring = generate_docstring(method,
position=(3, 7),
formatter="reST",
autocomplete=True)
expected = """
:raises MyExceptionUninstantiated: \n\
"""
assert docstring == expected