https://github.com/plasma-umass/commentator
Automatically comments Python code, adding docstrings and type annotations, with optional translation to other languages.
https://github.com/plasma-umass/commentator
amazon-web-services bedrock comments docstrings gpt-3 gpt-4 openai python types
Last synced: about 2 months ago
JSON representation
Automatically comments Python code, adding docstrings and type annotations, with optional translation to other languages.
- Host: GitHub
- URL: https://github.com/plasma-umass/commentator
- Owner: plasma-umass
- License: apache-2.0
- Created: 2023-03-05T17:06:36.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2024-02-29T00:43:47.000Z (almost 2 years ago)
- Last Synced: 2025-06-06T06:30:51.443Z (7 months ago)
- Topics: amazon-web-services, bedrock, comments, docstrings, gpt-3, gpt-4, openai, python, types
- Language: Python
- Homepage:
- Size: 143 KB
- Stars: 23
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Commentator
by [Emery Berger](https://emeryberger.com)
Commentator leverages large language models to add high-level
explanatory comments, docstrings, *and types* to Python code.
[](https://pypi.org/project/python-commentator/)
[](https://pepy.tech/project/python-commentator)
[](https://pepy.tech/project/python-commentator)
## Usage
>
> To work, Commentator needs to be connected to a local AI service, [OpenAI account](https://openai.com/api/), or an Amazon Web Services account.
>
> ### Local AI service (Ollama)
>
> Commentator can now use a locally installed AI service; it currently supports [Ollama](https://ollama.com). To use Ollama,
> install it and set the environment variable `USE_OLLAMA`:
>
> ```bash
> export USE_OLLAMA=1
> ```
>
> ### OpenAI
>
> _Your account will need to have a positive balance for this to work_
> ([check your OpenAI balance](https://platform.openai.com/usage)).
> [Get an OpenAI key here](https://platform.openai.com/api-keys).
>
> 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`.
>
> ```bash
> # On Linux/MacOS:
> export OPENAI_API_KEY=
>
> # On Windows:
> $env:OPENAI_API_KEY=
> ```
>
> ### Amazon Bedrock
>
> Commentator now supports Amazon Bedrock, using the Claude model.
> To use Bedrock, you need to set three environment variables.
>
> ```bash
> # On Linux/MacOS:
> export AWS_ACCESS_KEY_ID=
> export AWS_SECRET_ACCESS_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.