Commentator

by Emery Berger

Commentator leverages large language models to add high-level explanatory comments, docstrings, and types to Python code.

Usage

To work, Commentator needs to be connected to a local AI service, OpenAI account, or an Amazon Web Services account.

Local AI service (Ollama)

Commentator can now use a locally installed AI service; it currently supports Ollama. To use Ollama, install it and set the environment variable USE_OLLAMA:

  export USE_OLLAMA=1

OpenAI

Your account will need to have a positive balance for this to work (check your OpenAI balance). Get an OpenAI key here.

Commentator currently defaults to GPT-4, and falls back to GPT-3.5-turbo if a request error occurs. For the newest and best model (GPT-4) to work, you need to have purchased at least $1 in credits (if your API account was created before August 13, 2023) or $0.50 (if you have a newer API account).

Once you have an API key, set it as an environment variable called OPENAI_API_KEY.

# On Linux/MacOS:
export OPENAI_API_KEY=<your-api-key>

# On Windows:
$env:OPENAI_API_KEY=<your-api-key>

Amazon Bedrock

Commentator now supports Amazon Bedrock, using the Claude model. To use Bedrock, you need to set three environment variables.

# On Linux/MacOS:
export AWS_ACCESS_KEY_ID=<your-access-key>
export AWS_SECRET_ACCESS_KEY=<your-secret-key>
export AWS_REGION_NAME=us-west-2

If you do not already have access keys, you should be able create them by modifying this link with your own username and region:

https://us-east-1.console.aws.amazon.com/iam/home?region=us-east-1#/users/details/YOUR_USER_NAME?section=security_credentials

You also need to request access to Claude (change region as needed):

https://us-east-1.console.aws.amazon.com/bedrock/home?region=us-east-1#/modelaccess

Commentator will automatically select which AI service to use (local, OpenAI or AWS Bedrock) when it detects that the appropriate environment variables have been set.

Commentator takes a path to a Python file and an optional language parameter. If language is specified, Commentator translates each docstring and comment in the code to the specified language. The default language is English.

Installation

To install Commentator, you can use pip:

$ pip install python-commentator

Example

Suppose you have a file called example.py with the following code:

def absolutely(n):
    if n < 0:
        return -n
    else:
        return n

Run Commentator on this file to add comments and type annotations:

$ commentator example.py

The resulting code might be:

def absolutely(n: int) -> int:
    """
    Return the absolute value of a number.
    
    Args:
    - n (int): the number whose absolute value we want to find
    
    Returns:
    - int: the absolute value of n
    """
    if n < 0:
        # If n is negative
        # Return the negative version of n (i.e. its absolute value)
        return -n
    else:
        # Otherwise (if n is non-negative)
        # Return n as-is (it already is its absolute value)
        return n

Note that Commentator has added a docstring and type annotations.