| Name | docstring-auditor JSON |
| Version |
0.1.10
JSON |
| download |
| home_page | |
| Summary | A tool to analyze Python functions' docstrings and provide critiques and suggestions for improvement |
| upload_time | 2023-04-28 10:49:10 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | |
| license | |
| keywords |
auditor
docstring
gpt
openai
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Docstring Auditor
[](https://badge.fury.io/py/docstring-auditor)
[](https://github.com/agencyenterprise/docstring-auditor/actions/workflows/test.yml)
[](https://github.com/agencyenterprise/docstring-auditor/actions/workflows/release.yml)
[](https://github.com/agencyenterprise/docstring-auditor/pkgs/container/docstring-auditor)
Meet _Docstring Auditor_, your go-to solution for maintaining precise and up-to-date Python code documentation.
Tired of misleading or outdated docstrings? Docstring Auditor harnesses the power of large language models to analyze and critique your docstrings,
ensuring they align with your code's true purpose. Accessible to both experts and novices,
Docstring Auditor is your ultimate companion for clear, concise, and informative docstrings.
Say hello to better code documentation!
## Motivation
Recognizing the need for a reliable tool to address the challenge of keeping code documentation in sync with evolving codebases, we developed Docstring Auditor to tackle this issue head-on. Our motivation was to create an accessible, user-friendly solution that empowers developers to maintain clear and up-to-date documentation with ease, enhancing their workflow and reducing misunderstandings.
Docstring Auditor leverages the advanced capabilities of GPT-4, a powerful language model designed to deeply understand both code and natural language. By incorporating GPT-4 into our tool, Docstring Auditor examines the docstrings in your Python code, identifying discrepancies between the documentation and the actual code implementation. The analysis covers errors, warnings, and potential improvements, providing valuable critiques and suggestions to help you keep your documentation accurate and coherent. Docstring Auditor not only ensures that technical details, such as variables and types, are consistent, but it also verifies that the docstrings' meanings are in harmony with the code's functionality.
With Docstring Auditor, you can trust that your documentation stays relevant, informative, and accessible to all members of your team, making collaboration smoother and more efficient than ever before.
## Features
- Analyzes Python functions' docstrings in a given file
- Identifies errors, warnings, and possible improvements
- Provides detailed critiques and suggestions for better docstrings
- Powered by OpenAI's GPT for accurate and insightful analysis
- Easy to use command-line interface
## Installation
The easiest way to use Docstring Auditor is with Docker
1. Install [Docker](https://docs.docker.com/get-docker/)
2. Run the following command:
```bash
# If your code lives in the directory /Path/to/code
# And you wish to analyse all files in that directory
docker run -it --rm -e OPENAI_API_KEY=sk-XXXX -v /Path/to/code:/repo docstring-auditor
```
```bash
# If your code lives in the directory /Path/to/code
# And you wish to analyse a file called module/file.py
docker run -it --rm -e OPENAI_API_KEY=sk-XXXX -v /Path/to/code:/repo docstring-auditor module/file.py
```
## Usage
If you use the docker command above, Docstring Auditor will analyse all python files in your directory.
If you wish for it to analyse a single file, pass in the file name with the repo prefix.
For example, to analyse the file in `src/module/file.py`...
```bash
docker run -it --rm -e OPENAI_API_KEY=sk-XXXX -v /Path/to/code:/repo docstring-auditor /repo/src/module/file.py
```
The tool will then analyze the functions' docstrings in the specified file and display the critiques and suggestions for improvement.
## Example
Let's say you have a Python file called example.py with the following content:
```python
def compute(a, b):
"""
Add two numbers.
Parameters
----------
a : int or float
The first number to be added or from which 'b' will be subtracted.
b : int or float
The second number to be added or subtracted.
Returns
-------
int or float
The result of the addition operation.
"""
if a > 0:
return a + b
else:
return a - b
```
To analyze the docstring of the add function, run:
```bash
docstring-auditor example.py
```
Docstring Auditor will then provide you with a detailed analysis of the docstring, including any errors, warnings, and suggestions for improvement.
The output may look like...
```bash
Processing function 1 of 1...
--------------------------------------------------------------------------------
An error was found in the function: compute
The docstring states that the function adds two numbers, but the code also performs subtraction if 'a' is less than or equal to 0. The docstring should accurately describe both addition and subtraction operations.
A warning was found in the function: compute
The docstring does not follow the numpydoc style completely. The summary line should be a one-line summary, and the extended description should be provided in a separate paragraph.
A proposed solution to these concerns is:
"""
Add or subtract two numbers based on the value of 'a'.
This function performs addition if 'a' is greater than 0, and subtraction if 'a' is less than or equal to 0.
Parameters
----------
a : int or float
The first number to be added or from which 'b' will be subtracted.
b : int or float
The second number to be added or subtracted.
Returns
-------
int or float
The result of the addition or subtraction operation.
"""
```
## Limitations
1. There is currently no checking for malformed json from GPT4. Occasionaly GPT4 will return a bad json and the program will crash.
2. There is no rate limiting on the GPT4 calls.
3. Only GPT4 is included. It would be trivial to make this a variable. Pull requests are welcome.
## Contributing
We welcome contributions to Docstring Auditor! If you'd like to contribute, please fork the repository and submit a pull request with your changes. We also appreciate bug reports and feature requests submitted through the GitHub issues page.
## Advanced Usage
### Local Installation
You can also run Docstring Auditor locally by following these steps:
1. Install [Python 3.6+](https://www.python.org/downloads/)
2. Install [Git](https://git-scm.com/downloads)
3. Clone the repository: `git clone git@github.com:agencyenterprise/docstring-auditor.git`
4. Setup hatch: `pip install hatch`
5. Run the package `hatch run docstring-auditor /path/to/your/python_file.py`
Raw data
{
"_id": null,
"home_page": "",
"name": "docstring-auditor",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "auditor,docstring,gpt,openai",
"author": "",
"author_email": "Rob Luke <rob.luke@ae.studio>",
"download_url": "https://files.pythonhosted.org/packages/6e/0f/0fea56d0fdcee7b5ab9b7247748d775efda2aa0bfc248beb5b50f8e67c60/docstring_auditor-0.1.10.tar.gz",
"platform": null,
"description": "# Docstring Auditor\n\n[](https://badge.fury.io/py/docstring-auditor)\n\n[](https://github.com/agencyenterprise/docstring-auditor/actions/workflows/test.yml)\n[](https://github.com/agencyenterprise/docstring-auditor/actions/workflows/release.yml)\n[](https://github.com/agencyenterprise/docstring-auditor/pkgs/container/docstring-auditor)\n\n\nMeet _Docstring Auditor_, your go-to solution for maintaining precise and up-to-date Python code documentation.\nTired of misleading or outdated docstrings? Docstring Auditor harnesses the power of large language models to analyze and critique your docstrings,\nensuring they align with your code's true purpose. Accessible to both experts and novices,\nDocstring Auditor is your ultimate companion for clear, concise, and informative docstrings.\nSay hello to better code documentation!\n\n## Motivation\n\nRecognizing the need for a reliable tool to address the challenge of keeping code documentation in sync with evolving codebases, we developed Docstring Auditor to tackle this issue head-on. Our motivation was to create an accessible, user-friendly solution that empowers developers to maintain clear and up-to-date documentation with ease, enhancing their workflow and reducing misunderstandings.\n\nDocstring Auditor leverages the advanced capabilities of GPT-4, a powerful language model designed to deeply understand both code and natural language. By incorporating GPT-4 into our tool, Docstring Auditor examines the docstrings in your Python code, identifying discrepancies between the documentation and the actual code implementation. The analysis covers errors, warnings, and potential improvements, providing valuable critiques and suggestions to help you keep your documentation accurate and coherent. Docstring Auditor not only ensures that technical details, such as variables and types, are consistent, but it also verifies that the docstrings' meanings are in harmony with the code's functionality.\n\nWith Docstring Auditor, you can trust that your documentation stays relevant, informative, and accessible to all members of your team, making collaboration smoother and more efficient than ever before.\n\n\n## Features\n- Analyzes Python functions' docstrings in a given file\n- Identifies errors, warnings, and possible improvements\n- Provides detailed critiques and suggestions for better docstrings\n- Powered by OpenAI's GPT for accurate and insightful analysis\n- Easy to use command-line interface\n\n\n## Installation\n\nThe easiest way to use Docstring Auditor is with Docker\n\n1. Install [Docker](https://docs.docker.com/get-docker/)\n2. Run the following command:\n\n```bash\n# If your code lives in the directory /Path/to/code\n# And you wish to analyse all files in that directory\ndocker run -it --rm -e OPENAI_API_KEY=sk-XXXX -v /Path/to/code:/repo docstring-auditor\n```\n\n```bash\n# If your code lives in the directory /Path/to/code\n# And you wish to analyse a file called module/file.py\ndocker run -it --rm -e OPENAI_API_KEY=sk-XXXX -v /Path/to/code:/repo docstring-auditor module/file.py\n```\n\n## Usage\nIf you use the docker command above, Docstring Auditor will analyse all python files in your directory.\nIf you wish for it to analyse a single file, pass in the file name with the repo prefix.\nFor example, to analyse the file in `src/module/file.py`...\n\n```bash\ndocker run -it --rm -e OPENAI_API_KEY=sk-XXXX -v /Path/to/code:/repo docstring-auditor /repo/src/module/file.py\n```\nThe tool will then analyze the functions' docstrings in the specified file and display the critiques and suggestions for improvement.\n\n## Example\nLet's say you have a Python file called example.py with the following content:\n\n```python\n\ndef compute(a, b):\n \"\"\"\n Add two numbers.\n\n Parameters\n ----------\n a : int or float\n The first number to be added or from which 'b' will be subtracted.\n b : int or float\n The second number to be added or subtracted.\n\n Returns\n -------\n int or float\n The result of the addition operation.\n \"\"\"\n if a > 0:\n return a + b\n else:\n return a - b\n\n```\n\nTo analyze the docstring of the add function, run:\n\n```bash\ndocstring-auditor example.py\n```\nDocstring Auditor will then provide you with a detailed analysis of the docstring, including any errors, warnings, and suggestions for improvement.\nThe output may look like...\n\n```bash\nProcessing function 1 of 1...\n--------------------------------------------------------------------------------\nAn error was found in the function: compute\n\nThe docstring states that the function adds two numbers, but the code also performs subtraction if 'a' is less than or equal to 0. The docstring should accurately describe both addition and subtraction operations.\n\nA warning was found in the function: compute\n\nThe docstring does not follow the numpydoc style completely. The summary line should be a one-line summary, and the extended description should be provided in a separate paragraph.\n\nA proposed solution to these concerns is:\n\n\"\"\"\nAdd or subtract two numbers based on the value of 'a'.\n\nThis function performs addition if 'a' is greater than 0, and subtraction if 'a' is less than or equal to 0.\n\nParameters\n----------\na : int or float\n The first number to be added or from which 'b' will be subtracted.\nb : int or float\n The second number to be added or subtracted.\n\nReturns\n-------\nint or float\n The result of the addition or subtraction operation.\n\"\"\"\n\n```\n\n## Limitations\n\n1. There is currently no checking for malformed json from GPT4. Occasionaly GPT4 will return a bad json and the program will crash.\n2. There is no rate limiting on the GPT4 calls.\n3. Only GPT4 is included. It would be trivial to make this a variable. Pull requests are welcome.\n\n\n## Contributing\nWe welcome contributions to Docstring Auditor! If you'd like to contribute, please fork the repository and submit a pull request with your changes. We also appreciate bug reports and feature requests submitted through the GitHub issues page.\n\n\n## Advanced Usage\n\n### Local Installation\nYou can also run Docstring Auditor locally by following these steps:\n\n1. Install [Python 3.6+](https://www.python.org/downloads/)\n2. Install [Git](https://git-scm.com/downloads)\n3. Clone the repository: `git clone git@github.com:agencyenterprise/docstring-auditor.git`\n4. Setup hatch: `pip install hatch`\n5. Run the package `hatch run docstring-auditor /path/to/your/python_file.py`\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "A tool to analyze Python functions' docstrings and provide critiques and suggestions for improvement",
"version": "0.1.10",
"split_keywords": [
"auditor",
"docstring",
"gpt",
"openai"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b5de007a5706a9d07a4353034829d786507ecb9bed87c2529730384f5e967d8d",
"md5": "8e26b892e4ec9a5c82d3939e294839cc",
"sha256": "b02be53ab70a3297be8a213c54b25dff2bb28f2451ce4dd2e2defafe6c19a4fd"
},
"downloads": -1,
"filename": "docstring_auditor-0.1.10-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "8e26b892e4ec9a5c82d3939e294839cc",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 11458,
"upload_time": "2023-04-28T10:49:08",
"upload_time_iso_8601": "2023-04-28T10:49:08.183468Z",
"url": "https://files.pythonhosted.org/packages/b5/de/007a5706a9d07a4353034829d786507ecb9bed87c2529730384f5e967d8d/docstring_auditor-0.1.10-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6e0f0fea56d0fdcee7b5ab9b7247748d775efda2aa0bfc248beb5b50f8e67c60",
"md5": "4f43cf48c83c9a4cf9a3641f2ab14bfe",
"sha256": "c16e60e11c1b52ad2fb45c75dffb159237f23135e25398526a13bc5261d8e18c"
},
"downloads": -1,
"filename": "docstring_auditor-0.1.10.tar.gz",
"has_sig": false,
"md5_digest": "4f43cf48c83c9a4cf9a3641f2ab14bfe",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 16077,
"upload_time": "2023-04-28T10:49:10",
"upload_time_iso_8601": "2023-04-28T10:49:10.159464Z",
"url": "https://files.pythonhosted.org/packages/6e/0f/0fea56d0fdcee7b5ab9b7247748d775efda2aa0bfc248beb5b50f8e67c60/docstring_auditor-0.1.10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-28 10:49:10",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "docstring-auditor"
}
