Autodocstrings is a command-line tool with the following key features:
Updates the docstrings in Python files using the OpenAI API.
Can process a single file or a directory of files, including all subdirectories.
Autodocstrings uses the OpenAI api to generate docstrings, so these are not guaranteed to be perfect. However, they are a good starting point for writing your own docstrings.
The code-davinci-002 model is used to generate the docstrings. This model is trained on a large corpus of Python code, including docstrings. The model is able to generate docstrings that are similar to those found in the corpus.
Autodocstrings will work best for code that already has good type hints. Without type hints, the OpenAI API will have to guess input and return types, which may not be accurate.
Requirements
Python 3.6+
A valid openai api key. You can get one
here
. This is currently free.
Installation
$ pip install autodocstrings
Installation
To install the dependencies for this tool, run the following command:
pip install autodocstrings
Usage
To use this tool, run the following commands:
$ export OPENAI_API_KEY=1234567890
$ python update_docstrings.py INPUT `
[--replace-existing-docstrings] `
[--skip-constructor-docstrings] `
[--exclude-directories EXCLUDE_DIRECTORIES] `
[--exclude-files EXCLUDE_FILES]
Where INPUT is a Python file or directory containing Python files to update the docstrings in, API_KEY is your OpenAI API key, and the optional flags --replace-existing-docstrings and --skip-constructor-docstrings can be used to skip updating docstrings for constructors (init methods) and replacing existing docstirngs. EXCLUDE_DIRECTORIES and EXCLUDE_FILES are comma-separated lists of directories and files to exclude from the update.
Examples
Update the docstrings in all Python files in the my_code directory:
$ python update_docstrings.py my_code/
Update the docstrings in the my_file.py file:
$ python update_docstrings.py my_file.py
Update the docstrings in all Python files in the my_code directory and replace existing ones:
$ python update_docstrings.py my_code/ --replace-existing-docstrings
Update the docstrings in all Python files in the my_code directory, but skip updating docstrings for class constructors (init methods):
$ python update_docstrings.py my_code/ --skip-constructor-docstrings
Update the docstrings in all Python files in the my_code directory, but exlcude the exclude_dir directory and the exclude_file_1.py and exclude_file_2.py files:
$ python update_docstrings.py my_code/ --exclude-directories exclude_dir --exclude-files exclude_file_1.py,exclude_file_2.py
License
This project is licensed under the MIT License. See the LICENSE file for details.
Limitations
The python functions are being passed to the OpenAI API as independent code blocks. This means that the docstrings are not aware of the context of the function. If functions are written independently of each other, then this should not be a problem.
The format of the docstring is not always consistent, so you may need to manually fix some of the docstrings. You shouldn't use this in a ci/cd pipeline.
Input length is limited to the maximum input length of the OpenAI API. This is currently 2048 characters. If your function is larger than this then the docstring will not be updated.
OpenAI API can be slow.
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
"PyPI", "Python Package Index", and the blocks logos are registered
trademarks of the
Python Software Foundation.
© 2024
Python Software Foundation
Site map
