How to create a python package with GitHub Action

I recently published pymermaiddiagram, a python package that allows you to create mermaid.js diagrams from python, using a webservice.

For publishing, I chose Github Actions, to automate releases when I push new versions. The goal of this guide is to show, in the most direct way possible, how to create a package and how to publish it on pypi with GitHub Actions. I will avoid accessory considerations to focus on the essentials, because when I look for a guide of this type I like to read a few practical, precise and accurate indications.

Folder Structure

This is the folder structure I used for pymermaiddiagram, based on the reference structure given in the[https://packaging.python.org/en/latest/tutorials/packaging-projects/\](official documentation).

├── src
│   ├── pymermaiddiagram
│   │   ├── __init__.py
│   │   ├── pymermaid.py
├── test
│   ├── test_pymermaid.py
├── LICENSE.txt
├── README.md
├── pyproject.toml

Configuration File

The pyproject.toml file contains all the information needed by the build system to create the packages to be distributed. This is the pymermaiddiagram file, which you can use as a basis for your project:

[build-system]
requires = ["setuptools>=61.0", "pillow>=9", "requests>=2"]
build-backend = "setuptools.build_meta"


[project]
name = "pymermaiddiagram"
version = "0.0.2"
authors = [
    { name="Gioele SL Fierro", email="hck@gslf.it" },
]
description = "A library to create mermaid.js diagrams using python"
readme = "README.md"
requires-python = ">=3.7"
classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
]


[project.urls]
"Homepage" = "https://github.com/gslf/PyMermade"
"Bug Tracker" = "https://github.com/gslf/PyMermade/issues"

PyPi Token

Before continuing you need a PyPi API Token, which authorizes you to upload your package by linking it to a specific account. These are the steps to get the token

1. Register at https://pypi.org
2. Create a new API token from [https://pypi.org/manage/account/#api-tokens\](this link).
3. Copy the token somewhere, otherwise you won't be able to recover it and you will have to generate a new one.

Github Actions

To create a GitHub Action just insert a configuration file in the path:

.github/workflows

In my case the file is called python-puglish.yml. If desired, it can also be done via GUI from the Actions tab of the repository, using the "New Workdlow" button.

The file that loads the package is the following (I added some comments to make the various steps clearer):

# This workflow will upload a Python Package on pypi

# The name of the Workflow
name: Upload Python Package

# This action start on every push
on: push

# This action can read the content of the repository
permissions:
  contents: read


# Action job
jobs:
  deploy:
    # Build the package
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - name: Set up Python
      uses: actions/setup-python@v3
      with:
        python-version: '3.x'
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install build
    - name: Build package
      run: python -m build

    # Publish the package on pypi
    - name: Publish package
      uses: pypa/gh-action-pypi-publish@27b31702a0e7fc50959f5ad993c78deac1bdfc29
      with:
        user: __token__
        password: ${{ secrets.PYPI_API_TOKEN }}

This action needs a secrets variable called PYPI_API_TOKEN, to set it follow these steps from the GitHub repository web page:

1. Go to the Settings tab
2. In the sidebar open the Secrets and Variables menu and select Action
3. In the Secrets tab use the New repository secret button
4. In the Name field enter PYPI_API_TOKEN
5. In the Secret field, paste the key you generated on pypi.org in the previous steps

Publication

Now the publication of the package on PyPi will be managed automatically at each new push. To test, give a git push of a commit and follow the action from the Actions tab of the repo's GitHub page.

If the package is not published, you will surely find the reason in the logs for the execution of the Action that was not successful. Just fix the bug, good luck! 😉