Automatically generate docstrings for Python functions using Ollama

https://github.com/guylsmith1972/luci

Docstring Generator

This command-line tool helps to automatically generate, modify, validate, or strip docstrings in Python files. It utilizes a GPT model for generating docstrings based on the function's code and comments.

Note: Recent increases in context lengths available in Llama-3.1 have rendered the approach used in this tool obsolete.

Installation

For Windows or WSL users, put dist/luci.exe in a location listed in your PATH environment variable. Standalone executables for other operating systems will be added in time.

You will also need to have Ollama installed, and the ollama executable must be in the PATH. Luci expects llama3 to be installed in Ollama by default. You can install it manually with 'ollama pull llama3' or you can use luci to install it with 'luci --install-model llama3'.

Release Status

This software is in a pre-alpha state. While it provides the intended functionality for Python code, the documentation generated often contains hallucinations and guesses. Do not rely on it for documentation without oversight.

Usage

Create, update, or validate docstrings in Python files.

usage: luci [-h] [-a [1-100]] [-c] [-d [1-100]] [-l {0,1,2}] [-m] [-p] [-r] [-s] [-u] [-v]
            [--install-model MODEL_NAME] [--list] [--model MODEL] [--host HOST] [--port PORT]
            [filenames ...]

Positional Arguments

filenames List of filenames to process. If an undecorated filename is provided, all functions in the file will be examined. To limit the scope of operations, filenames can be decorated by adding a colon-separated list of fully-qualified function names of the form foo.bar.zoo, where foo, bar, and zoo can be the names of functions or classes. Nesting of functions and classes is allowed. If a path is longer than the --depth field, a warning is reported, and the function is not processed.

Options

-h, --help Show this help message and exit.
-a [1-100], --attempts [1-100] Set the number of attempts for processing. Must be an integer in the range [1-100].
-c, --create Create new docstrings for functions that do not currently have one.
-d [1-100], --depth [1-100] Set the depth for processing. Must be an integer in the range [1-100].
-l {0,1,2}, --log-level {0,1,2} Set the log level. 0 = no logs, 1 = brief logs, 2 = verbose logs.
-m, --modify Modify the original files with new changes. If -p or -r is also specified, the file will prompt the user before modifying.
-p, --preview Preview the content of the files without making changes unless -m is also specified, in which case, it will prompt the user before modifying.
-r, --report Show a report after each file is processed. If the -m flag is present, this flag will cause the user to be prompted before the modification occurs.
-s, --strip Strip existing docstrings. When used in conjunction with -v, it will only strip docstrings that fail validation. Incompatible with -u and -c.
-u, --update Update existing docstrings. If -v is specified, it will only update if the current docstring failed validation. Incompatible with -s.
-v, --validate Validate that the docstrings in the file correctly describe the source code. If -u is specified, an update will only occur if validation fails. If -s is specified, the docstring will be deleted if validation fails.
--install-model MODEL_NAME Install a model by name onto the Ollama server.
--list List all installed models available on the Ollama server.
--model MODEL Specify the model to operate on. Defaults to llama3.
--host HOST Specify the host of the Ollama server. Defaults to localhost.
--port PORT Specify the port of the Ollama server. Defaults to 11434.

Examples

Common Use Cases

To create docstrings for all functions in sample.py that lack them. This example uses -c to create docstrings, -p to preview changes, and -m to modify the file with the results.

To update docstrings for all functions in sample.py that lack them. This example uses -u to update existing docstrings, -p to preview changes, and -m to modify the file with the results.

To only update docstrings that are out of date, add the -v option:

Creation and updates can occur at the same time:

To produce a report on the correctness of existing docstrings, use the -r and -v options without using -c or -u:

To remove docstrings from a file, use the -s option:

You can focus on a specific function or functions by appending a colon-separated list of fully-qualified function names to the file name. The following example will only validate docstrings in the function named 'function_name' at the module level, and the method named 'method_name' that is part of the class 'class_name' which is defined at the module level.

luci -vr sample.py:function_name:class_name.method_name

If you want to affect deeply-nested functions, you will need to increase the depth. By default, luci will only document top-level functions and methods of classes that are defined at the top level. Use -d to increase the depth:

luci -vr -d 2 sample.py:function_name.nested_function_name:class_name.nested_class_name.method_name

Managing Ollama

luci uses Ollama to manage the llama models used to generate docstrings. By default it uses llama3. Other models may be used by setting the --model option

luci -cupm sample.py --model llama2

You can list available models with --list:

You can install a model with the --install-model option:

luci --install-model llama2:latest

You can set the host and port of the ollama server with --host and --port:

luci -cupm sample.py --host <some_hostname> --port <some_port>

Tips and Tricks

Sometimes the GPT will "embellish" the documentation by making claims about the code that are not true. You can guide the GPT to better documentation by adding clarifying comments to the code. These comments need to be placed within the function body that contains the erroneous documentation. After adding the clarifying comments, delete the documentation for the function and re-generate it. GPT misunderstandings can show you ways in which your code is not clear and "encourage" you to improve clarity.

Roadmap

Future enhancements:

Extend to support additional programming languages (in progress but not ready yet)
Add change history to docstring or in comments following docstring
LSP support / IDE integration
Either remove the examples section from generated docs or improve it so the examples are good.
Have it decide between brief documentation for small or simple functions and verbose documentation for large or complex functions
Pass scope information about class membership and nesting to ollama when generating documentation
Improve instructions to reduce hallucinations
Improve instructions to reduce occurence of useless notes (for example, notes warning the developer to import packages containing functions that are referenced)
Include list of imports for each function in instructions to ollama

{
  "by": "llmblockchain",
  "descendants": 0,
  "id": 40249589,
  "score": 1,
  "time": 1714754407,
  "title": "Automatically generate docstrings for Python functions using Ollama",
  "type": "story",
  "url": "https://github.com/guylsmith1972/luci"
}

{
  "author": "guylsmith1972",
  "date": null,
  "description": "Automatically generate docstrings for Python functions using Ollama. - guylsmith1972/luci",
  "image": "https://opengraph.githubassets.com/ec043ef84139867b13a74f9a0cdc5042cdc32bddc7bdf238da4330af55885ff9/guylsmith1972/luci",
  "logo": "https://logo.clearbit.com/github.com",
  "publisher": "GitHub",
  "title": "GitHub - guylsmith1972/luci: Automatically generate docstrings for Python functions using Ollama.",
  "url": "https://github.com/guylsmith1972/luci"
}

{
  "url": "https://github.com/guylsmith1972/luci",
  "title": "GitHub - guylsmith1972/luci: Automatically generate docstrings for Python functions using Ollama.",
  "description": "Docstring Generator This command-line tool helps to automatically generate, modify, validate, or strip docstrings in Python files. It utilizes a GPT model for generating docstrings based on the function's...",
  "links": [
    "https://github.com/guylsmith1972/luci"
  ],
  "image": "https://opengraph.githubassets.com/ec043ef84139867b13a74f9a0cdc5042cdc32bddc7bdf238da4330af55885ff9/guylsmith1972/luci",
  "content": "<div><article><p></p><h2>Docstring Generator</h2><a target=\"_blank\" href=\"https://github.com/guylsmith1972/luci#docstring-generator\"></a><p></p>\n<p>This command-line tool helps to automatically generate, modify, validate, or strip docstrings in Python files. It utilizes a GPT model for generating docstrings based on the function's code and comments.</p>\n<p>Note: Recent increases in context lengths available in Llama-3.1 have rendered the approach used in this tool obsolete.</p>\n<p></p><h2>Installation</h2><a target=\"_blank\" href=\"https://github.com/guylsmith1972/luci#installation\"></a><p></p>\n<p>For Windows or WSL users, put dist/luci.exe in a location listed in your PATH environment variable. Standalone executables for other operating systems will be added in time.</p>\n<p>You will also need to have <a target=\"_blank\" href=\"https://ollama.com/download\">Ollama</a> installed, and the ollama executable must be in the PATH. Luci expects llama3 to be installed in Ollama by default. You can install it manually with 'ollama pull llama3' or you can use luci to install it with 'luci --install-model llama3'.</p>\n<p></p><h2>Release Status</h2><a target=\"_blank\" href=\"https://github.com/guylsmith1972/luci#release-status\"></a><p></p>\n<p>This software is in a pre-alpha state. While it provides the intended functionality for Python code, the documentation generated often contains hallucinations and guesses. Do not rely on it for documentation without oversight.</p>\n<p></p><h2>Usage</h2><a target=\"_blank\" href=\"https://github.com/guylsmith1972/luci#usage\"></a><p></p>\n<p>Create, update, or validate docstrings in Python files.</p>\n<div><pre>usage: luci [-h] [-a [1-100]] [-c] [-d [1-100]] [-l {0,1,2}] [-m] [-p] [-r] [-s] [-u] [-v]\n            [--install-model MODEL_NAME] [--list] [--model MODEL] [--host HOST] [--port PORT]\n            [filenames ...]</pre></div>\n<p></p><h2>Positional Arguments</h2><a target=\"_blank\" href=\"https://github.com/guylsmith1972/luci#positional-arguments\"></a><p></p>\n<ul>\n<li><code>filenames</code>\nList of filenames to process. If an undecorated filename is provided, all functions in the\nfile will be examined. To limit the scope of operations, filenames can be decorated by adding\na colon-separated list of fully-qualified function names of the form <code>foo.bar.zoo</code>, where <code>foo</code>,\n<code>bar</code>, and <code>zoo</code> can be the names of functions or classes. Nesting of functions and classes is\nallowed. If a path is longer than the <code>--depth</code> field, a warning is reported, and the function\nis not processed.</li>\n</ul>\n<p></p><h2>Options</h2><a target=\"_blank\" href=\"https://github.com/guylsmith1972/luci#options\"></a><p></p>\n<ul>\n<li><code>-h, --help</code>\nShow this help message and exit.</li>\n<li><code>-a [1-100], --attempts [1-100]</code>\nSet the number of attempts for processing. Must be an integer in the range [1-100].</li>\n<li><code>-c, --create</code>\nCreate new docstrings for functions that do not currently have one.</li>\n<li><code>-d [1-100], --depth [1-100]</code>\nSet the depth for processing. Must be an integer in the range [1-100].</li>\n<li><code>-l {0,1,2}, --log-level {0,1,2}</code>\nSet the log level. 0 = no logs, 1 = brief logs, 2 = verbose logs.</li>\n<li><code>-m, --modify</code>\nModify the original files with new changes. If -p or -r is also specified, the file will\nprompt the user before modifying.</li>\n<li><code>-p, --preview</code>\nPreview the content of the files without making changes unless -m is also specified, in which\ncase, it will prompt the user before modifying.</li>\n<li><code>-r, --report</code>\nShow a report after each file is processed. If the -m flag is present, this flag will cause\nthe user to be prompted before the modification occurs.</li>\n<li><code>-s, --strip</code>\nStrip existing docstrings. When used in conjunction with -v, it will only strip docstrings\nthat fail validation. Incompatible with -u and -c.</li>\n<li><code>-u, --update</code>\nUpdate existing docstrings. If -v is specified, it will only update if the current docstring\nfailed validation. Incompatible with -s.</li>\n<li><code>-v, --validate</code>\nValidate that the docstrings in the file correctly describe the source code. If -u is\nspecified, an update will only occur if validation fails. If -s is specified, the docstring\nwill be deleted if validation fails.</li>\n<li><code>--install-model MODEL_NAME</code>\nInstall a model by name onto the Ollama server.</li>\n<li><code>--list</code>\nList all installed models available on the Ollama server.</li>\n<li><code>--model MODEL</code>\nSpecify the model to operate on. Defaults to llama3.</li>\n<li><code>--host HOST</code>\nSpecify the host of the Ollama server. Defaults to localhost.</li>\n<li><code>--port PORT</code>\nSpecify the port of the Ollama server. Defaults to 11434.</li>\n</ul>\n<p></p><h3>Examples</h3><a target=\"_blank\" href=\"https://github.com/guylsmith1972/luci#examples\"></a><p></p>\n<p></p><h4>Common Use Cases</h4><a target=\"_blank\" href=\"https://github.com/guylsmith1972/luci#common-use-cases\"></a><p></p>\n<p>To create docstrings for all functions in <code>sample.py</code> that lack them. This example uses -c to create docstrings, -p to preview changes, and -m to modify the file with the results.</p>\n<p>To update docstrings for all functions in <code>sample.py</code> that lack them. This example uses -u to update existing docstrings, -p to preview changes, and -m to modify the file with the results.</p>\n<p>To only update docstrings that are out of date, add the -v option:</p>\n<p>Creation and updates can occur at the same time:</p>\n<p>To produce a report on the correctness of existing docstrings, use the -r and -v options without using -c or -u:</p>\n<p>To remove docstrings from a file, use the -s option:</p>\n<p>You can focus on a specific function or functions by appending a colon-separated list of fully-qualified function names to the file name. The following example will only validate docstrings in the function named 'function_name' at the module level, and the method named 'method_name' that is part of the class 'class_name' which is defined at the module level.</p>\n<div><pre><code>luci -vr sample.py:function_name:class_name.method_name\n</code></pre></div>\n<p>If you want to affect deeply-nested functions, you will need to increase the depth. By default, luci will only document top-level functions and methods of classes that are defined at the top level. Use -d to increase the depth:</p>\n<div><pre><code>luci -vr -d 2 sample.py:function_name.nested_function_name:class_name.nested_class_name.method_name\n</code></pre></div>\n<p></p><h4>Managing Ollama</h4><a target=\"_blank\" href=\"https://github.com/guylsmith1972/luci#managing-ollama\"></a><p></p>\n<p>luci uses Ollama to manage the llama models used to generate docstrings. By default it uses llama3. Other models may be used by setting the --model option</p>\n<div><pre><code>luci -cupm sample.py --model llama2\n</code></pre></div>\n<p>You can list available models with --list:</p>\n<p>You can install a model with the --install-model option:</p>\n<div><pre><code>luci --install-model llama2:latest\n</code></pre></div>\n<p>You can set the host and port of the ollama server with --host and --port:</p>\n<div><pre><code>luci -cupm sample.py --host &lt;some_hostname&gt; --port &lt;some_port&gt;\n</code></pre></div>\n<p></p><h3>Tips and Tricks</h3><a target=\"_blank\" href=\"https://github.com/guylsmith1972/luci#tips-and-tricks\"></a><p></p>\n<ol>\n<li>Sometimes the GPT will \"embellish\" the documentation by making claims about the code that are not true. You can guide the GPT to better documentation by adding clarifying comments to the code. These comments need to be placed within the function body that contains the erroneous documentation. After adding the clarifying comments, delete the documentation for the function and re-generate it. GPT misunderstandings can show you ways in which your code is not clear and \"encourage\" you to improve clarity.</li>\n</ol>\n<p></p><h3>Roadmap</h3><a target=\"_blank\" href=\"https://github.com/guylsmith1972/luci#roadmap\"></a><p></p>\n<p>Future enhancements:</p>\n<ol>\n<li>Extend to support additional programming languages (in progress but not ready yet)</li>\n<li>Add change history to docstring or in comments following docstring</li>\n<li>LSP support / IDE integration</li>\n<li>Either remove the examples section from generated docs or improve it so the examples are good.</li>\n<li>Have it decide between brief documentation for small or simple functions  and verbose documentation for large or complex functions</li>\n<li>Pass scope information about class membership and nesting to ollama when generating documentation</li>\n<li>Improve instructions to reduce hallucinations</li>\n<li>Improve instructions to reduce occurence of useless notes (for example, notes warning the developer to import packages containing functions that are referenced)</li>\n<li>Include list of imports for each function in instructions to ollama</li>\n</ol>\n</article></div>",
  "author": "",
  "favicon": "https://github.githubassets.com/favicons/favicon.svg",
  "source": "github.com",
  "published": "",
  "ttr": 216,
  "type": "object"
}