{"id":28573426,"url":"https://github.com/plasma-umass/commentator","last_synced_at":"2025-10-28T00:10:28.528Z","repository":{"id":113531986,"uuid":"609933045","full_name":"plasma-umass/commentator","owner":"plasma-umass","description":"Automatically comments Python code, adding docstrings and type annotations, with optional translation to other languages.","archived":false,"fork":false,"pushed_at":"2024-02-29T00:43:47.000Z","size":146,"stargazers_count":23,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-06T06:30:51.443Z","etag":null,"topics":["amazon-web-services","bedrock","comments","docstrings","gpt-3","gpt-4","openai","python","types"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/plasma-umass.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2023-03-05T17:06:36.000Z","updated_at":"2025-05-15T10:59:45.000Z","dependencies_parsed_at":"2024-02-08T22:16:28.168Z","dependency_job_id":"462bf8b0-ca16-4416-b468-7e8996d1de20","html_url":"https://github.com/plasma-umass/commentator","commit_stats":null,"previous_names":["emeryberger/commentator","emeryberger/commentaire"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plasma-umass%2Fcommentator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plasma-umass%2Fcommentator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plasma-umass%2Fcommentator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plasma-umass%2Fcommentator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/plasma-umass","download_url":"https://codeload.github.com/plasma-umass/commentator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plasma-umass%2Fcommentator/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259152777,"owners_count":22813225,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["amazon-web-services","bedrock","comments","docstrings","gpt-3","gpt-4","openai","python","types"],"created_at":"2025-06-10T21:18:06.358Z","updated_at":"2025-10-28T00:10:23.494Z","avatar_url":"https://github.com/plasma-umass.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Commentator\n\nby [Emery Berger](https://emeryberger.com)\n\nCommentator leverages large language models to add high-level\nexplanatory comments, docstrings, *and types* to Python code.\n\n[![PyPI](https://img.shields.io/pypi/v/python-commentator.svg)](https://pypi.org/project/python-commentator/)\n[![downloads](https://static.pepy.tech/badge/python-commentator)](https://pepy.tech/project/python-commentator)\n[![downloads/month](https://static.pepy.tech/badge/python-commentator/month)](https://pepy.tech/project/python-commentator)\n![Python versions](https://img.shields.io/pypi/pyversions/python-commentator.svg?style=flat-square)\n\n## Usage\n\n \u003e  \n \u003e  To work, Commentator needs to be connected to a local AI service, [OpenAI account](https://openai.com/api/), or an Amazon Web Services account.\n \u003e\n \u003e  ### Local AI service (Ollama)\n \u003e  \n \u003e  Commentator can now use a locally installed AI service; it currently supports [Ollama](https://ollama.com). To use Ollama,\n \u003e  install it and set the environment variable `USE_OLLAMA`:\n \u003e  \n \u003e  ```bash\n \u003e    export USE_OLLAMA=1\n \u003e  ```\n \u003e  \n \u003e  ### OpenAI\n \u003e\n \u003e  _Your account will need to have a positive balance for this to work_\n \u003e  ([check your OpenAI balance](https://platform.openai.com/usage)).\n \u003e  [Get an OpenAI key here](https://platform.openai.com/api-keys).\n \u003e \n \u003e  Commentator currently defaults to GPT-4, and falls back to GPT-3.5-turbo if a request error occurs. For the newest and best\n \u003e  model (GPT-4) to work, you need to have purchased  at least $1 in credits (if your API account was created before\n \u003e  August 13, 2023) or $0.50 (if you have a newer API account).\n \u003e \n \u003e  Once you have an API key, set it as an environment variable called `OPENAI_API_KEY`.\n \u003e \n \u003e  ```bash\n \u003e  # On Linux/MacOS:\n \u003e  export OPENAI_API_KEY=\u003cyour-api-key\u003e\n \u003e  \n \u003e  # On Windows:\n \u003e  $env:OPENAI_API_KEY=\u003cyour-api-key\u003e\n \u003e  ```\n \u003e\n \u003e  ### Amazon Bedrock\n \u003e\n \u003e  Commentator now supports Amazon Bedrock, using the Claude model.\n \u003e  To use Bedrock, you need to set three environment variables.\n \u003e\n \u003e  ```bash\n \u003e  # On Linux/MacOS:\n \u003e  export AWS_ACCESS_KEY_ID=\u003cyour-access-key\u003e\n \u003e  export AWS_SECRET_ACCESS_KEY=\u003cyour-secret-key\u003e\n \u003e  export AWS_REGION_NAME=us-west-2\n \u003e  ```\n \u003e\n \u003e  If you do not already have access keys, you should be able create them by\n \u003e  modifying this link with your own username and region:\n \u003e\n \u003e     https://us-east-1.console.aws.amazon.com/iam/home?region=us-east-1#/users/details/YOUR_USER_NAME?section=security_credentials\n \u003e\n \u003e  You also need to request access to Claude (change region as needed):\n \u003e\n \u003e     https://us-east-1.console.aws.amazon.com/bedrock/home?region=us-east-1#/modelaccess\n \u003e\n \u003e  Commentator will automatically select which AI service to use (local, OpenAI or AWS Bedrock) when it detects that the appropriate\n \u003e  environment variables have been set.\n\nCommentator takes a path to a Python file and an optional language\nparameter. If language is specified, Commentator translates each\ndocstring and comment in the code to the specified language. The\ndefault language is English.\n\n\n## Installation\n\nTo install Commentator, you can use pip:\n\n```\n$ pip install python-commentator\n```\n\n## Example\n\nSuppose you have a file called `example.py` with the following code:\n\n```\ndef absolutely(n):\n    if n \u003c 0:\n        return -n\n    else:\n        return n\n```\n\nRun Commentator on this file to add comments and type annotations:\n\n```\n$ commentator example.py\n```\n\nThe resulting code might be:\n\n```\ndef absolutely(n: int) -\u003e int:\n    \"\"\"\n    Return the absolute value of a number.\n    \n    Args:\n    - n (int): the number whose absolute value we want to find\n    \n    Returns:\n    - int: the absolute value of n\n    \"\"\"\n    if n \u003c 0:\n        # If n is negative\n        # Return the negative version of n (i.e. its absolute value)\n        return -n\n    else:\n        # Otherwise (if n is non-negative)\n        # Return n as-is (it already is its absolute value)\n        return n\n```\n\nNote that Commentator has added a docstring and type annotations.\n\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplasma-umass%2Fcommentator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fplasma-umass%2Fcommentator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplasma-umass%2Fcommentator/lists"}