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, gpt4docstrings will 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 -t flag to False.

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.