This week we're releasing version 1.0.0 of our repository context packager. This was an interesting process, and easier than I expected, but a little tricky to set up right.
I followed this guide to packaging python project using PyPI. I chose the backend setuptools since it is the most traditional and widely used packaging tool.
Release Process
First thing I needed to do was restructure my project. I needed to move everything into a repository_context_packager directory and rename my main script to scan_repo.py with an underscore, because Python packaged need underscores. I already had an __init__.py file, but had to move it into the main directory, so this ended up being the new directory structure:
Next I created the pyproject.toml file to configure the package metadata, dependencies, and the CLI entry point to allow users to run scan-repo from the command line.
Now it was time to build and test the package. This was done by installing the build tool with pip install build twine and running python -m build to create the necessary files in a dist/ folder. Then I needed to make an account to upload to Test PyPI to make sure everything was in working order before uploading to the real PyPI. Both sites required making an account, and setting up 2-factor authentication before I could generate the API key necessary to upload builds.
What I Learned
The biggest "aha!" moment was understanding relative imports after getting a bunch of errors. When your code is a script, you use from analyzer import cli, but once it's a package, you need from .analyzer import cli. I had to change every single import statement in my code, including imports between modules in my analyzer folder.
I also learned the hard way that you can't delete or replace versions on PyPI. I accidentally uploaded broken test versions (1.0.1, 1.0.2) to the real PyPI after forgetting to remove them, and once they're up, they're permanent for that version number. I guess I had made them to test, and when I removed and rebuilt version 1.0.0 for the real PyPI, it uploaded the other two at the same time. I had to yank those releases (which hides them from normal pip installs) and will need to upload 1.0.3 as my next version now.
Code Alterations
On top of the structure changes and the addition of the pyproject.toml file, I needed to update my GitHub Actions workflow to run python -m repository_context_packager.scan_repo --help instead of directly calling the script. This was due to changing to relative imports, and it took me a few pushes to realize I had broken this.
User Testing
I had my friend from my last co-op test the installation and it went off without a hitch. Of course, he decided to run it on a huge Github project he had on his computer and it took like 5 mins to get through it but it -did- work exactly as was laid out in the instructions and exactly as I had hoped.
Installing and Running
Installing is really simple now. Just run:
pip install repository-context-packager
Then to use it:
scan-repo . # Analyze current directory
scan-repo ./project -o output.md # Save to file
scan-repo . --recent --remove-comments # Recent files only, no comments
More detailed usage is outlined in the README.
Overall, it was a good learning experience. The official Python packaging tutorial made it way easier than I expected, and now anyone can install my tool with one command instead of cloning the repo and setting up dependencies manually. The hardest part was definitely getting the imports right- I must have uploaded five broken versions to Test PyPI before I got them all fixed!
Top comments (0)