Releasing my First Open Source Project

#programming #opensource #python

Hi everyone, if you've been following my blog posts for a while, you may know that I have been working on an open source project called TXT to HTML Converter. Well, I recently released it. You can find it here, on PyPI. I'll talk about the release process below.

What Platform did I use to Release my project

As mentioned above, I used PyPI. PyPI is a service used to host packages or projects made by you. It's used by open source projects like Black.

What was the Release Process Like?

The release process was a little bit complicated for me, as I originally had a hard time with having it run on PC. I'll talk about part of the setup process below, to hopefully help out others releasing their first project on PyPI.

PyPI provides a tutorial that you can use when you're getting ready to release a package. I based majority of the setup process off of this tutorial. I created a new file called __init__.py. I also moved all of my source code, including __init__.py, into a folder that has the name of my package. I left __init__.py empty. I also made changes to my toml file called pyproject.toml. As you may know, I've used this toml file to configure my formatter, Black, and linter, Ruff. Now I'm also using it to configure the release of my package, I'll show what the file looks like for me.

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "text-to-html-converter"
version = "1.0.2"
authors = [
  { name="Marco Pasqua", email="email@gmail.com" },
]
description = "A package that allows for txt and md conversion to HTML files."
readme = "README.md"
requires-python = ">=3.11"
classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
]

[project.urls]
Homepage = "https://github.com/Pasqua101/txt-to-HTML-converter"
Issues = "https://github.com/Pasqua101/txt-to-HTML-converter/issues"

PyPI provides a good explanation in their tutorial. However, I'll explain some of the things I did. While most of it is self-explanatory, you can see that I've stated that my program requires Python 3.11 and above. This is due to a library I used called TOMLlib, which is built into Python 3.11 and above. You can also see that I've provided a version number, which I can update for each release, as well as a description. The build system part is something that is necessary for uploading the package to PyPI. Other than that, I did make changes to my import statements. Instead of doing something like from helper import extension_checker, my imports now looked like this from . import helper as h. According to my peer, I had to do this to get my code to be able to work with PyPI. Even if it didn't work on my computer in the end. Moving on, when I did all that, I then made sure to set my PyPI token. The tutorial should mention how to get and use this token for releasing your package. Afterwards, I ran this command python -m build. This command builds my program, and puts the required files to be uploaded in a dist folder. To upload the dist files, I first had to install Twine by doing this python -m pip install --upgrade twine. I was then ready to upload it with this command py -m twine upload --repository pypi dist/*. This is where the token comes into play. The token is able to create a project on my account for the files to be hosted and downloaded from as a package. If I needed to fix my code, I could make my changes, then change the version number in the pyproject.toml file and run the same upload command from earlier.

Testing my Package

I had a peer testing my work, who also helped me solve most of the problem with my code not being able to run. They seemed to have no problems with running my package, during the testing phase. However, I did notice that since I moved my source code into a new folder, I had to make some changes to my testers. This is something that I set as an issue for myself on my repo.

How to Install my Program

To install my program, you can navigate to this link that it's hosted at. Here, you can choose to learn more about it, or run this command, pip install text-to-html-converter, to get started. Once the package is installed, you should then be able to run it like so python -m text-to-html.text_to_html -h. This will display some information about the app, and how to use it. After that, you're all set! Enjoy using my program and feel free to report any bugs or problems you come across by going to my repo.

Thank you all for following my journey of creating and publishing this program! I hope it has some use to you all, despite the simple problem it accomplishes. See you in the next blog post.