cookiecutter gl:galactipy/galactipy --checkout v0.20.0

All you need is the latest version of cookiecutter! 😉

In this cookiecutter 🍪 template we combine state-of-the-art libraries and best development practices for Python.

• Supports Python 3.10 and higher;
• Provides minimal boilerplate code for CLI/TUI applications with Typer and Textual -- or no code at all, you choose! With it, you have:
  • Batteries-included configuration setup and management with Orbittings;
  • Both beautiful logging on the terminal and easy-to-parse log files thanks to Nebulog;
  • Preconfigured Noctis themes to make your application shine on the terminal;
• Uses Poetry as the dependency manager and extends functionality with dynamic versioning, virtual environment bundling, dependency export and update resolution; 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 Bandit;
• Testing with Pytest and an option to use behaviour-driven development for managing scenarios; more details in How to Handle the Development Cycle with BDD;
• Code quality integrations with either Coveralls for more basic test coverage or Codacy for full code analysis, both integrated into your project's workflow via CI/CD;
• Everything is already set up for security checks, codestyle checks, code formatting, testing, linting, docker builds etc. with Invoke; more details in Invoke Usage;
• 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.

• The boilerplate code is already 100% covered by unit tests so you can fully commit to working on your project instead of dealing with test cases;
• Predefined CI/CD build workflow with GitLab CI and Github Actions;
• Automatic package uploads to PyPI test and production repositories;
• Dockerfile for your package, with CI/CD workflows to publish your image to a container registry;
• Semantic Versions specification with GitLab Changelog or Release Drafter.

• Ready-to-use Merge Request templates and several Issue templates for easy integration with GitLab and GitHub;
• Workflows to mark and close abandoned issues after a period of inactivity for both GitLab with Triage Policies and GitHub with Stale Bot;
• Option to choose between Gitmoji, Conventional Commits or a mix of both to standardise your commit titles.

• Files such as LICENCE, CONTRIBUTING.md, CODE_OF_CONDUCT.md, CITATION.cff 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.

You are free to choose whichever platform works best for you and your project. The original template by TezRomacH was created originally with GitHub in mind, which prompted the creation of a similarly fully-featured template for GitLab users as well.

However, not everything that is available for GitHub users is available to GitLab users, and vice-versa. Please mind the differences between both options.

Below is a comparison between the features available in this package depending on which platform you choose to host your project:

To begin using the template consider updating cookiecutter:

pip install -U cookiecutter

then go to a directory where you want to create your project and run:

cookiecutter gl:galactipy/galactipy --checkout v0.20.0

Cookiecutter will ask you to fill some variables in order to generate the files with everything you need already set up.

The input variables, with their default values, are as follows:

All input values will be saved in the cookiecutter-config-file.yml file so that you won't lose them. 😉

You must have Poetry installed to leverage the features provided with the Galactipy template.

After creating a project, ensure you have Invoke installed and run the following command to install dependencies and pre-commit hooks:

invoke install

If you don't have Invoke available in your system, run this instead:

poetry install
invoke hooks

Want to know more about Poetry? Check its documentation. Poetry's commands are very intuitive and easy to learn, streamlining your development process.

Galactipy is best used for terminal applications, either a TUI or a simple CLI interface. If you choose any of the options for app_type excluding Bare repository, your project will embed Typer as a dependency, and Textual will be provided for the Integrated CLI+TUI and Hybrid CLI/TUI options.

For any of the options providing an interface, you can call the application after setting up the virtual environment via invoke install or poetry install:

poetry run <repo_name> --help

poetry run <repo_name> --version

Then you can use the structure provided with Galactipy to build your application upon the barebones codebase. 😄

To release a new version of the application, you must first have a PyPI account and generate an API token.

Then, add the registry to the Poetry configuration with

invoke config <API_token>

You'll be all set 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, enabling users to download, track and inspect the changes made to the API.

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! 🥳

[!note] To allow releasing directly via CI/CD workflows, besides setting up a canonical PyPI token, you must also generate a API toke for the TestPyPI repository.

If you have generated your project with the Docker option enabled, pushing a tag to your repository will also set up the automated workflows to build and publish your image to a container registry.

invoke is a library that enables easy configuration of shell-oriented subprocesses as Python functions, essentially organising a collection of aliases for all project developers to use.

Below is a list with the main task groups and details when relevant. Available tasks can be viewed at anytime with the invoke --list command.

[!warning] :small_red_triangle: Invoke must be installed and callable. Otherwise, it is recommended to run poetry install to set up the repository.

The invoke sweep task groups all tasks except for coverage into a single command.

[!note] :small_red_triangle: When provided with no --repo option, Invoke will configure the connection to the canonical PyPI repository, with only the API token being required. When provided with the --repo testpypi option instead, it will configure the connection to TestPyPI and no URL is needed. Other --repo values must also receive a --url argument pointing to the desired custom registry.

The invoke cleanup task groups all tasks except for remove-build into a single command.

Behaviour-driven development is a software development paradigm in which domain language is used to describe the behaviour of the code. It emerged as a sophisticated evolution of test-driven development.

If you choose to use BDD for your project, a features directory will be created under tests and pytest-bdd will be added as a dependency. You should place .feature files inside this folder to describe real-life usage scenarios using the Gherkin language:

# tests/features/root_command.feature
Feature: Command-line interface

  Scenario: Check program version
    When the root program receives the `--version` option
    Then the terminal displays the program's version
    And the program exits without errors

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

from typer.testing import CliRunner
from pytest_bdd import scenario, when, then, parsers
from python_project.cli.commands.root_command import app

runner = CliRunner()

@scenario("root_command.feature", "Check program version")
def test_cli_with_version_arg():
    pass

@when("the root program receives the `--version` option", target_fixture="cli_run")
def invoke_version_arg():
    return runner.invoke(app, args=["--version"])

@then("the terminal displays the program's version")
def version_display(cli_run, version_string):
    assert cli_run.stdout == version_string

@then("the program exits without errors")
def successful_termination(cli_run):
    assert cli_run.exit_code == 0

Once the tests are defined, 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 tools to handle more complex conditions, please check out the Cucumber documentation.

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 the 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 repo_name, change it otherwise;
  • It generates a Docker badge assuming you also use scm_namespace for Docker Hub and you will push your image under repo_name, 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:

• Rich makes it easy to add beautiful formatting in the terminal. If you chose to generate a TUI or CLI example during the Cookiecutter setup, Rich will already be among your dependencies;
• tqdm is a fast, extensible progress bar for Python and CLI;
• 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;
• Add your project to OpenSSF Best Practices and OSSRank 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; 😀
• 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;
  • If you host on GitHub, you can set a Sponsors account directly integrated into the platform;
  • Of course, you can also set any kind of gateway you wish, what works best for you and your project!
• If you are unsure about the versioning logic to use, check this list with a plethora of options to choose from.

And here are a few articles which may help you:

• Open Source Guides;
• A handy guide to financial support for open source;
• GitLab CI Documentation;
• 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.

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

We follow Intended Effort Versioning specification, details can be found in our CONTRIBUTING guide.

Galactipy's roadmap is managed through our Milestones page, which lays out the current development streams mapped for delivery. All official details on development, timeline and deliverables are found through those pages. The project's milestones are also presented in the ROADMAP file purely for informational purposes.

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

Firstly, there is no way this template would exist without the previous phenomenal work by Roman Tezikov and his fully-featured python-package-template. If there is anyone more deserving of a 🌟 and acknowledgement, it's him! Please give a shoutout and support if possible.

The original template was inspired by several articles that might be helpful if you are starting out managing projects:

• Hypermodern Python;
• Ultimate Setup for Your Next Python Project;
• Nine simple steps for better-looking python code;
• Modern Python developer's toolkit.

And also there are some projects which can be studied as references in project management and template design:

• Cookiecutter;
• Audreyr's cookiecutter-pypackage;
• Cookiecutter Data Science Template: cdst;
• Full Stack FastAPI and PostgreSQL - Base Project Generator;
• The importance of layered thinking in data engineering.

Additionally, we would like to thank the teams of the following projects for either aiding us directly during our research of best practices and tools for Python development or whose documentation have inspired parts of the project:

• Pelican;
• Spark;
• React;
• Chai;
• Harbor.

Give them your ⭐, these resources are amazing! 😉

Galactipy Bot avatar created by Smashicons.

We provide a CITATION.cff file to make it easier to cite this project in your paper.

Add the badge to your project! It would be really appreciated to spread the word of this template.

Here is the Markdown source for it:

[![Expand your project structure from atoms of code to galactic dimensions.](https://img.shields.io/badge/made%20with-galactipy%20%F0%9F%8C%8C-179287?style=for-the-badge&labelColor=193A3E)](https://kutt.it/7fYqQl)

We would be equally grateful if you could also do any of the following:

• Set the notification level to "Watch" to receive our latest updates; 🔔
• Star the project! 🌟
• Share the project with colleagues; 🗣️
• Write a short article on how you are using Galactipy on your projects; ✏️
• Share best practices, references and tools for project management with us! 🍻