gpt4docstrings
Generating Python docstrings with OpenAI ChatGPT!!
What is gpt4docstrings?
gpt4docstrings is a library that helps you to write docstrings
for your Python code. Select a path / paths where you want gpt4docstrings
to be applied and wait for the results!!
Requirements
gpt4docstrings supports Python 3.9 and above.
Installation
Warning: At the moment, this library is under heavy development, so it is recommended to always install the latest version.
You can install gpt4docstrings via pip from PyPI:
$ pip install -U gpt4docstrings
Usage
To run gpt4docstrings on a specific file, run this command.
gpt4docstrings my_file.py
Remember that, if you don’t have your OpenAI API Key defined as an Environment Variable (OPENAI_API_KEY),
gpt4docstrings can accept the API Key as an option.
gpt4docstrings --api_key sk-xxxxxxxxxxxx my_file.py
Be aware that, as a safety measure , gpt4docstrings won’t overwrite the file in place.
Instead, it will generate a patch called gpt4docstring_docstring_generator_patch.diff
that contains the information about all the changes.
If you want to apply the patch to the file, simply run:
patch -p1 < gpt4docstring_docstring_generator_patch.diff
In case you don’t want to generate a patch file and modify the files in place, you’ll
need to add the --overwrite, -w option:
gpt4docstrings -w my_file.py
You can also apply gpt4docstrings to folders recursively.
gpt4docstrings src/
Another quite common situation is that you may want to exclude the tests/ folder, for example,
from the generation of docstrings. Doing this is very simple.
gpt4docstrings --exclude tests/ src/
By default, gpt4docstrings generates google style docstrings. However,
you can choose between: google, numpy, epytext, reStructuredText.
You can specify the docstring style using the -st option. For example:
gpt4docstrings -st epytext my_file.py
For more information about all the available options, you can check
the help info:
Usage: gpt4docstrings [OPTIONS] [PATHS]...
Options:
-h, --help Show this message and exit.
-S, --ignore-setters Ignore methods with property setter
decorators.
-P, --ignore-property-decorators
Ignore methods with property setter/getter
decorators.
-n, --ignore-nested-functions Ignore nested functions and methods.
-C, --ignore-nested-classes Ignore nested classes.
-i, --ignore-init-method Ignore `__init__` method of classes.
-s, --ignore-semiprivate Ignore semiprivate classes, methods, and
functions starting with a single underscore.
-p, --ignore-private Ignore private classes, methods, and
functions starting with two underscores.
[default: False]
-w, --overwrite If `True`, it will directly write the
docstrings into the files (it will not
generate git patches)
-v, --verbose INTEGER Verbosity parameter. Defaults to 0.
-e, --exclude PATH Exclude PATHs of files and/or directories.
Multiple `-e/--exclude` invocations
supported.
-k, --api_key TEXT OpenAI's API key. If not provided,
`gpt4docstrings` will try to access
`OPENAI_API_KEY` environment variable.
-st, --style TEXT Docstring style, which must be one of
'google', 'reStructuredText', 'epytext',
'numpy'
-m, --model TEXT The model to be used by `gpt4docstrings`. By
default, `gpt-3.5-turbo`.
I also encourage you to see the [Command-line Reference] for more details!!
Example
Here is a full example using gpt4docstring to generate docstrings
for the python code inside example/example.py.
import asyncio
async def async_example():
await asyncio.sleep(2)
class MyClass:
def __init__(self, value):
self.value = value
@staticmethod
def nested_method():
def inner_function():
print("Nested method inner function")
print("Nested method start")
inner_function()
print("Nested method completed")
We’ll create numpy docstrings in this case and will generate a patch file (default) instead of directly overwriting
the file directly. We’ll also increase the level of verbosity to see some additional information.
Warning: We are assuming you already have the OpenAI API Key set as an Environment Variable. Otherwise, this example won’t work.
gpt4docstrings example/example.py -v 1 -st numpy
After it finishes documenting, we should see a new patch file on our directory called gpt4docstring_docstring_generator_patch.diff.
To apply the patch, simply run:
patch -p1 < gpt4docstring_docstring_generator_patch.diff
The result should be similar to the following (gpt-3.5-turbo temperature
is set to 1, so you should expect different results every time you run the command)
import asyncio
async def async_example():
"""
An asynchronous example function.
This function asynchronously sleeps for 2 seconds.
Returns
-------
None
This function does not return any value.
"""
await asyncio.sleep(2)
class MyClass:
"""
A class representing MyClass.
Parameters
----------
value : any
The initial value for MyClass.
Methods
-------
nested_method : static method
A nested static method within MyClass.
"""
def __init__(self, value):
"""
Initialize a new instance of the class.
Parameters
----------
value : any
The initial value for the instance.
Returns
-------
None
Raises
------
None
"""
self.value = value
@staticmethod
def nested_method():
"""
This static method demonstrates a nested method.
Raises
------
None
Returns
-------
None
"""
def inner_function():
"""
Inner function.
This function performs a nested method inner function.
Parameters
----------
None
Returns
-------
None
"""
print("Nested method inner function")
print("Nested method start")
inner_function()
print("Nested method completed")
Suppose now that we want to modify the docstring type. For example,
suppose we want to use epytext style. That’s very easy with
gpt4docstrings, we just need to run the same command changing the docstring style.
Be aware that, by default,
gpt4docstringswill allways generate docstrings for undocumented functions / classes and also translate the existing ones to follow the provided style. If you just want to generate docstrings (no translation), simply set the-tflag toFalse.
gpt4docstrings example/example.py -st epytext
If we apply the patch, we’ll get the previous code with the docstrings translated:
import asyncio
async def async_example():
"""
An asynchronous example function.
This function asynchronously sleeps for 2 seconds.
@rtype: None
@return: This function does not return any value.
"""
await asyncio.sleep(2)
class MyClass:
"""
A class representing MyClass.
@type value: any
@ivar value: The initial value for MyClass.
@type nested_method: static method
@ivar nested_method: A nested static method within MyClass.
"""
def __init__(self, value):
"""
Initialize a new instance of the class.
@param value: The initial value for the instance.
@type value: any
@return: None
@raise None
"""
self.value = value
@staticmethod
def nested_method():
"""
This static method demonstrates a nested method.
@rtype: None
@return: None
@raise: None
"""
def inner_function():
"""
Inner function.
This function performs a nested method inner function.
@rtype: None
"""
print("Nested method inner function")
print("Nested method start")
inner_function()
print("Nested method completed")
Contributing
Contributions are very welcome. To learn more, see the Contributor Guide.
License
Distributed under the terms of the MIT license, gpt4docstrings is free and open source software.
Issues
If you encounter any problems, please file an issue along with a detailed description.
Credits
This project was generated from @cjolowicz’s Hypermodern Python Cookiecutter template.