Python Project GH Workflow

Awesome python-project-gh-workflow is a Python cli/package created with https://gitlab.com/galactipy/galactipy

Very first steps

Initialize your code

1. Initialize git inside your repo:

cd python-project-gh-workflow && git init

2. If you don't have Poetry installed run:

invoke poetry-download

This installs Poetry as a standalone application. If you prefer, install it through your distribution's package manager.

3. Initialize Poetry and install pre-commit hooks:

invoke install
invoke pre-commit-install

4. Run the codestyle:

invoke codestyle

5. Upload initial code to GitHub:

git add .
git commit -m ":tada: Initial commit"
git branch -M main
git remote add origin https://github.com/galactipy/python-project-gh-workflow.git
git push -u origin main

Set up bots

• Set up Dependabot to ensure you have the latest dependencies;
• Set up Stale bot for automatic issue closing.

Poetry

Want to know more about Poetry? Check its documentation.

Details about Poetry

Poetry's commands are very intuitive and easy to learn, like:

• poetry add numpy@latest
• poetry run pytest
• poetry publish --build

etc.

Building and releasing your package

In order to release a new version of the application, a few steps are needed.

Make sure you have a PyPI account and generate an API token, you can then register it in your repository with

invoke pypi-config <API_token>

Then, you're all good to build and publish your package in one go!

invoke publish

You should also push a tag to GitLab or GitHub and create a Release for your application on the platform to ensure users can check the latest version contents.

Of course, you can also rely solely on the CI tools provided by Galactipy to handle building, publishing and releasing automatically, with minimal configuration required! 🥳

Pushing a tag to your repository will also set up the automated workflows to build and publish your image to Docker Hub.

🎯 What's next

Well, that's up to you. 💪

For further setting up your project:

• Look for files and sections marked with TODO (which must be addressed in order for your project to run properly) and UPDATEME (optional settings if you feel inclined to);

  • If you use VS Code, install the Todo Tree extension to easily locate and jump to these marks, they are already configured in your settings.json file;

• Make sure to create your desired Issue labels on your platform before you start tracking them so it ensures you will be able to filter them from the get-go;

• Make changes to your CI configurations to better suit your needs.

• In order to reduce user prompts and keep things effective, the template generates files with a few assumptions:

  • It assumes your main git branch is master. If you wish to use another branch name for development, be aware of changes you will have to make in the Issue and Merge Request templates and README.md file so links won't break when you push them to your repo;
  • It generates a PyPI badge assuming you will be able to publish your project under python-project-gh-workflow, change it otherwise;
  • It generates a Docker badge assuming you also use galactipy for Docker Hub and you will push your image under python-project-gh-workflow, change it otherwise.

If you want to put your project on steroids, here are a few Python tools which can help you depending on what you want to achieve with your application:

• Typer is great for creating CLI applications;
• Rich makes it easy to add beautiful formatting in the terminal;
• tqdm is a fast, extensible progress bar for Python and CLI;
• Python Prompt Toolkit allows you to create more advanced terminal applications, such as a text editor or even your own shell;
• orjson, an ultra fast JSON parsing library;
• Pydantic is data validation and settings management using Python type hinting;
• Returns makes you function's output meaningful, typed, and safe;
• Loguru makes logging (stupidly) simple;
• IceCream is a little library for sweet and creamy debugging;
• Hydra is a framework for elegantly configuring complex applications;
• FastAPI is a type-driven asynchronous web framework.

For taking development and exposition of your project to the next level:

• Try out some more badges, not only it looks good, but it also helps people better understand some intricate details on how your project works:
  • You can look at dynamic badges available at Shields.io;
  • There is a myriad of standardised static badges at Simple Badges;
  • awesome-badges provides a lot of useful resources to help you deal with badges;
• Setup a code coverage service for your tests, popular options include:
  • Coveralls and Codecov if you need solely test coverage;
  • Code Climate and Codacy for fully-featured code analysis;
• Add your project to [OpenSSF Best Practices][wno1] and [OSSRank][wno2] indexes. If you have greater ambitions for your project and/or expects it to scale at some point, it's worth considering adding it to these trackers;
  • There are already badges for those set up in your README.md file, just waiting for you to update their URLs with your project's index in both services :beaming_face_with_smiling_eyes:
• Setup a sponsorship page and allow users and organisations who appreciate your project to help raise for its development (and add a badge in the process! 😎). Popular platforms are:
  • Liberapay;
  • Open Collective;
  • Ko-fi;
  • You can set a Sponsors account directly integrated into GitHub;
  • Of course, you can also set any kind of gateway you wish, what works best for you and your project!

And here are a few articles which may help you:

• Open Source Guides;
• A handy guide to financial support for open source;
• GitHub Actions Documentation;
• A Comprehensive Look at Testing in Software Development is an article that lays out why testing is crucial for development success. Eric's blog is actually a great reference, covering topics ranging from the basics to advanced techniques and best practices;
• Robust Exception Handling;
• Why Your Mock Doesn't Work;
• Managing TODOs in a codebase;
• Maybe you would like to add gitmoji to commit names. This is really funny. 😁

🚀 Features

Development features

• Support for Python 3.9 and higher;
• Uses Poetry as the dependency manager and extends functionality with [dynamic versioning][new1], [virtual environment bundling][new2], dependency [export][new3] and [update resolution][new4]. See configuration in pyproject.toml;
• Automatic code formatting with ruff, with ready-to-use pre-commit hooks and several rules already selected for linting;
• Type checks with mypy, security checks with safety and bandit;
• Testing with pytest and behaviour-driven development configuration for managing scenarios; more details in the Behaviour-Driven Development section;
• Code quality integrations with Coveralls via CI/CD;
• Predefined VS Code settings.json with quality-of-life configuration for editor, workbench, debugging and more;
• Ready-to-use .editorconfig, .dockerignore and .gitignore files. You don't have to worry about those things.

Deployment features

• Predefined CI/CD build workflow with Github Actions;
• Automatic package uploads to PyPI test and production repositories;
• Everything is already set up for security checks, codestyle checks, code formatting, testing, linting, docker builds etc with Invoke. More details in Invoke Usage;
• Dockerfile for your package, with CI/CD workflows to publish your image to a container registry;
• Always up-to-date dependencies with Dependabot. You will only need to enable it;
• Automatic drafts of new releases with Release Drafter. You may see the list of labels in release-drafter.yml.

Project management features

• Issue and Pull Request templates for easy integration with GitHub;
• Workflows to mark and close abandoned issues after a period of inactivity with Stale Bot.

Open source community features

• Ready-to-use Pull Request templates and several Issue templates;
• Files such as: LICENCE, CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SECURITY.md are generated automatically;
• Loads of predefined badges to make your project stand out, you can either keep them, remove as you wish or be welcome to add even more.

Installation

pip install -U python-project-gh-workflow

or install with Poetry:

poetry add python-project-gh-workflow

Then you can run

python-project-gh-workflow --help

or with Poetry:

poetry run python-project-gh-workflow --help

Invoke usage

invoke contains a lot of functions for faster development.

1. Download or remove Poetry

To download and install Poetry as a standalone application run:

invoke poetry-download

To uninstall

invoke poetry-remove

Alternatively, you can install it via your package manager (preferred) or any method provided by the documentation.

2. Install all dependencies and pre-commit hooks

Install requirements with

invoke install

And then add Poetry plugins to make development easier with

invoke poetry-plugins

Pre-commit hooks could be installed after git init via

invoke pre-commit-install

3. Codestyle

Automatic formatting uses ruff, and can be run with

invoke codestyle

# or use synonym
invoke format

For formatting checks only, without rewriting files:

invoke codestyle --check

Aside from the formatter, you can also use ruff to lint project files with several preconfigured rules defined in pyproject.toml:

invoke check-linter

4. Code security

invoke check-safety

This command launches Poetry integrity checks as well as identifies security issues with Safety and Bandit.

Update all dev libraries to the latest version using one command:

invoke update-dev-deps

5. Type checks

Run mypy static type checker with

invoke mypy

6. Tests

Run pytest with all essential parameters predefined with

invoke test

7. All code-related checks

Of course there is a command to rule run all linters in one:

invoke sweep

The same as:

invoke test check-linter codestyle mypy check-safety

8. Docker

Build your Docker image with the latest tag preconfigured with

invoke docker-build

Remove docker image with

invoke docker-remove

More information about Docker here.

9. Cleanup

Delete pycache files:

invoke pycache-remove

Remove package build:

invoke build-remove

Delete .DS_STORE files:

invoke dsstore-remove

Remove .mypycache:

invoke mypycache-remove

Or to remove all above run:

invoke cleanup

Behaviour-Driven Development

A features directory is placed under tests, with pytest-bdd added as a dependency. You should create .feature files inside this folder to specify them and describe scenarios using the Gherkin language:

# tests/features/divide.feature
Feature: Divide numbers
  Scenario: Full division
    When I ask the calculator to divide "21" by "7"
    Then the screen should return "3" as an integer

  Scenario: Division by zero
    When I ask the calculator to divide any number by "0"
    Then the screen should return an error message

You would then use pytest-bdd to wrap each scenario referred in the feature file as a step by step validation:

from mypackage import divide
from pytest_bdd import scenario, when, then

@scenario("divide.feature", "Full Division")
def test_full_division():
    pass

@when("I ask the calculator to divide \"21\" by \"7\"")
def divide_21_7():
    calculation = divide(21, 7)

    return calculation

@then("The screen should return \"3\" as an integer")
def return_integer():
    assert calculation.display == "3"


@scenario("divide.feature", "Division by Zero")
def test_zero_division():
    pass

@when("I ask the calculator to divide any number by \"0\"")
def divide_by_zero():
    calculation = divide(15, 0)

    return calculation

@then("The screen should return an error message")
def return_integer():
    assert calculation.display == "Error"

Then you can simply use pytest as you normally would to run the test suite and check the results.

For more information on behaviour-driven development and more advanced cases, please check out the Cucumber documentation.

📈 Releases

You can see the list of available releases on the GitHub Releases page.

We follow Semantic Versions specification.

We use Release Drafter. As pull requests are merged, a draft release is kept up-to-date listing the changes, ready to publish when you’re ready. With the categories option, you can categorize pull requests in release notes using labels.

List of labels and corresponding titles

Label	Title in Releases
enhancement, feature	🚀 Features
bug, refactoring, bugfix, fix	🔧 Fixes & Refactoring
build, ci, testing	📦 Build System & CI/CD
breaking	💥 Breaking Changes
documentation	📝 Documentation
dependencies	⬆️ Dependencies updates

You can update it in release-drafter.yml.

GitHub creates the bug, enhancement, and documentation labels for you. Dependabot creates the dependencies label. Create the remaining labels on the Issues tab of your GitHub repository, when you need them.

🛡️ Licence

This project is licenced under the terms of the MIT licence. See LICENCE for more details.

📃 Citation

@misc{Python Project GH Workflow,
  author = {The Galactipy Contributors},
  title = {Awesome `python-project-gh-workflow` is a Python cli/package created with https://gitlab.com/galactipy/galactipy},
  year = {2025},
  publisher = {GitHub},
  journal = {GitHub repository},
  howpublished = {\url{https://github.com/galactipy/python-project-gh-workflow}}
}

Credits

This project was generated with galactipy.