robodair / pydocstring Goto Github PK

View Code? Open in Web Editor NEW

21.0 4.0 5.0 114 KB

Python package for autogenerating python docstrings, and switching between common docstring formats

License: MIT License

Python 100.00%

pydocstring's Introduction

pydocstring

https://readthedocs.org/projects/pydocstring/badge/?version=latest

Python package for autogenerating python docstrings, built on top of Parso.

This project can be wrapped by an editor extension to provide docstrings as autocompletion or in response to a shortcut command.

Status

Ready for basic use - Supports Google, Numpy, and reST docstring formats, and it's pretty simple to create your own formatter.

Types are able to be inferred for some things, but if they can't be worked out 'TYPE' is just inserted instead.

Doesn't support more complicated things like converting between styles or updating docstrings.

Future

Check the issues for any more, but the nice-to-haves are:

Docstring insertion for a whole file
Updating docstrings for methods with changed paramenters/exeptions/Types
Conversion between docstring styles

Docs

Documentation is on Read The Docs

API

For integration with editors, there's a really simple api avaialble (just a single call), check out the docs for more on that.

Download

pydocstring is on PyPI and can be installed with pip:

pip install pydocstring

Development

Testing/Coverage is automanted with tox. Pull requests are welcome.

pydocstring's People

Contributors

Stargazers

Watchers

Forkers

hydrox24 benmaier lucazampieri wizmer agware

pydocstring's Issues

Failure on run

I have cloned your repository and then run python setup.py develop --user. Then I switched to the repository with my project (it is M2Crypto, BTW) and then this happened:

 $ pydocstring -f reST M2Crypto/BIO.py
Traceback (most recent call last):
  File "/home/matej/.local/bin/pydocstring", line 9, in <module>
    load_entry_point('pydocstring==0.0.dev14', 'console_scripts', 'pydocstring')()
  File "/home/matej/archiv/knihovna/repos/tmp/pydocstring/pydocstring/cli.py", line 42, in main
    print('"""\n' + output + '"""\n')
TypeError: cannot concatenate 'str' and 'NoneType' objects
 $

Using python 2.7 on RHEL-7 (if it matters, the same happened with python 3.4.5).

Updating Docstrings with parameters/exceptions/etc that change

Missing support for typing.List etc

Hi!
I wanted to try this module, version 0.2.1 on my linux machine, but when it detects line like:

def configure_channels(self, ch: typing.List[str], all_ch: bool = False):

Then it throws this error

pydocstring -f numpy /home/khazakar/Projects/autorok/autorok/sigrokcli.py '(111, 5)' --debug
(111, 5)
Traceback (most recent call last):
  File "/home/khazakar/.local/bin/pydocstring", line 8, in <module>
    sys.exit(main())
  File "/home/khazakar/.local/lib/python3.8/site-packages/pydocstring/cli.py", line 81, in main
    raise ex
  File "/home/khazakar/.local/lib/python3.8/site-packages/pydocstring/cli.py", line 75, in main
    output = pydocstring.generate_docstring(source,
  File "/home/khazakar/.local/lib/python3.8/site-packages/pydocstring/__init__.py", line 65, in generate_docstring
    return formatter_module.function_docstring(scope)
  File "/home/khazakar/.local/lib/python3.8/site-packages/pydocstring/formatters/numpy.py", line 39, in function_docstring
    docstring += "    {0} : {1}\n        {2}\n".format(*get_param_info(param))
  File "/home/khazakar/.local/lib/python3.8/site-packages/pydocstring/formatters/format_utils.py", line 41, in get_param_info
    param_type = param.annotation.value if param.annotation else "TYPE"
AttributeError: 'PythonNode' object has no attribute 'value'

doc_text = pydocstring.generate_docstring(
  File "/usr/local/lib/python3.8/site-packages/pydocstring/__init__.py", line 65, in generate_docstring
    return formatter_module.function_docstring(scope)
  File "/usr/local/lib/python3.8/site-packages/pydocstring/formatters/google.py", line 46, in function_docstring
    *get_return_info(ret, parso_function.annotation))
  File "/usr/local/lib/python3.8/site-packages/pydocstring/formatters/format_utils.py", line 61, in get_return_info
    expression = "".join(x.get_code().strip() for x in ret.children[1:])
AttributeError: 'Keyword' object has no attribute 'children'

the generation code is def report(loan_data, all_amount=False, balance=False):

Backdrop:
I am trying to build a plugin for Geany.
Its [here] (https://github.com/sagarchalise/geany-pycoding/blob/peasy/peasypycoding.py#L416).
Basically, it calls pydocstring on source content.