Hello, Blog!
If you have just stumbled upon my OSD600 series of blog posts, it has been created to document and share my learnings as I progress through my Open Source Development college course.
In this blog post, I want to go over the steps I took to publish my CLI tool - addcom to PyPi.
ADDCOM
addcom is a CLI source code documenter tool which provides coders with an easy way to add comments to their source code files
Give it a relative/absolute path to your file and it will analyze its contents and add comments using a Large Language Model's chat completion.
See a demo of the functionality on YouTube: addcom-demo
Setup Instructions
Prerequisites
Make sure Python is installed on your system (you can download it here: https://www.python.org/downloads/).
1. Install the tool using pip
pip install addcom
2. Default: Create an account and generate the API key here: https://console.groq.com/
By default, addcom uses the Groq API endpoint for chat completion. However, you can specify a custom endpoint using the --base-url or -u flag option. (If you do this, make sure to obtain an appropriate API key and specify the model supported by the chosen provider using the --model/ -m option).
3. Set
…I welcome feedback/contributions, so don’t hesitate to take a look and get involved 😊
Preparing for Release
Before releasing my tool, I integrated Poetry for dependency management and packaging into my project, replacing the good old setuptools. This decision was inspired by recommendations from peers and various blog posts highlighting Poetry’s simplicity and modern features.
I removed the setup.py file, which handled the tools' packaging. Then, moved the metadata from __init__.py into a pyproject.toml file, which I created a couple of labs back to add configs for the source code formatter and linter.
Additionally, I did a bit of refactoring to make the project's structure a bit cleaner. To do so I moved all source code files into a single app package and updated the imports across the project.
For guidance, I referred to Poetry's official documentation and studied similar Python projects on GitHub.
Below are the final configurations I used for Poetry:
# Poetry - project metadata
[tool.poetry]
name = "addcom"
version = "1.0.2"
description = "a CLI tool for adding comments to your source code files"
authors = ["Arina Kolodeznikova <arinak1017@gmail.com>"]
license = "MIT"
readme = "README.md"
repository = "https://github.com/arilloid/addcom"
packages = [{include = "app"}]
# Dependencies required for running the project
[tool.poetry.dependencies]
python = "^3.12"
typer = "^0.12"
openai = "^1.46"
rich = "^13.8"
typing_extensions = "^4.12"
# Dev dependencies (not required for run-time)
[tool.poetry.group.dev.dependencies]
black = "^24.10"
ruff = "^0.7"
pytest = "^8.3"
pytest-mock = "^3.14"
# Project's CLI commands
[tool.poetry.scripts]
addcom = 'app.main:app'
# Build configurations
[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"
Publishing addcom to PyPi
After setting up Poetry and verifying that everything was working as expected, I tweaked my CI workflow file, updated the tool’s documentation, and went on to publishing my tool to PyPi (The Python Package Index).
You can find the guide that I followed here: Publishing packages with Poetry
Steps to publish
1. Tagging the Release
I started by tagging the release using an annotated Git tag to mark the version:
git tag -a v1.0.0 -m "my version 1.0.0"
2. Configuring PyPI Credentials
Next, I configured Poetry to use my PyPI credentials (this step required obtaining a PyPI API token):
poetry config pypi-token.pypi <your-pypi-token>
To generate a PyPI token, I created an account on PyPI, navigated to Account Settings, and selected Add API Tokens.
3. Building and Publishing the Package
Finally, I built and published the package using Poetry (which I specified as the build backend in the pyproject.toml):
poetry publish --build
You can find my release here: addcom
Testing the Release
After testing the release myself, I invited my friend, roommate, and fellow developer, Tatiana, for a dedicated testing session. Although I was nervous to show her my tool, the testing process went pretty smoothly, thanks to the effort I put into creating detailed instructions in the projects README.md. However, there were still a few issues during the review. The instructions for setting up the API key were poorly structured, causing confusion. Tatiana also noted that the .toml configuration section assumed users were working from a cloned repository, which wouldn't be the case for most users installing the tool using pip. The most significant feedback, which echoed a remark made by my professor David, was about the tool’s handling of multiple files. When generating comments for several files, the tool saved everything to a single file, with no option to split the output. Additionally, at times the generated comments were inconsistent, even with the given "context" code used for reference.
To address these issues, I edited the API key setup instructions in the README and updated the .toml configuration section. As for the file output logic and comment consistency, I plan to look into updating them after the term comes to an end.
How to install ADDCOM
You can now install addcom using pip:
pip install addcom
By default, addcom uses the Groq API for chat completion. To get started quickly, create an account on the Groq Console, generate an API key, and run the tool with the following command:
addcom FILE_PATH(S) -a "your_api_key"
For detailed information on the tool's functionality, usage, and instructions, visit the release page on PyPI.
Top comments (0)