❗	This is a mirror repository to galactipy, which is currently being developed on GitLab. Feel free to fork it and take a look at CONTRIBUTING.md to know how to contribute to the project!

Galactipy

Expand your project structure from atoms of code to galactic dimensions. 🌌

TL;DR

cookiecutter gl:manoelpqueiroz/galactipy --checkout v0.1.0

All you need is the latest version of cookiecutter! :winking_face:

🚀 Features

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

Development features

• Supports Python 3.8 and higher;
• Poetry as a dependencies manager. See configuration in pyproject.toml;
• Automatic code formatting with black, isort and pyupgrade, with ready-to-use pre-commit hooks;
• Code and docstring linting with flake8, pydocstyle and pydoclint;
• Type checks with mypy, security checks with safety and bandit;
• Testing with pytest;
• Ready-to-use .editorconfig, .dockerignore, and .gitignore files. You don't have to worry about those things.

Deployment features

• Issue and Merge Request templates for easy integration with GitLab and GitHub;
• Predefined CI/CD build workflow for GitLab CI and Github Actions;
• Everything is already set up for security checks, codestyle checks, code formatting, testing, linting, docker builds etc. with Makefile. More details in makefile-usage;
• Dockerfile for your package.

GitLab vs. GitHub features

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:

Feature	GitLab	GitHub	Observations
Issue templates	:check_mark_button:	:check_mark_button:	Both options feature automatic labels, but GitHub has an extra configuration to prevent the creation of empty issues.
Merge/pull requests templates	:check_mark_button:	:check_mark_button:
Stale issues	:cross_mark:	:check_mark_button:	A specific configuration is available for GitHub to mark and automatically close stale issues.
Build workflow	:check_mark_button:	:check_mark_button:	A basic workflow to install the package and run tests, check codestyle and safety.
Greetings workflow	:cross_mark:	:check_mark_button:
Dependabot	:cross_mark:	:check_mark_button:	Dependabot is a feature now incorporated into GitHub Security. See here how to enable it.
Release drafter	:cross_mark:	:check_mark_button:	Release Drafter is a custom workflow available on GitHub Marketplace. You may see the list of labels in release-drafter.yml. Works perfectly with Semantic Versions specification.
Changelog configuration	:check_mark_button:	:cross_mark:	GitLab provides automatic changelog updates through their API. You may modify the template in changelog_config.yml.

Open source community features

• Ready-to-use Merge 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;
• For GitHub users, Stale bot closes abandoned issues after a period of inactivity. Configuration is here;
• Semantic Versions specification with Changelog entries or Release Drafter.

🤯 How to use it

Installation

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:manoelpqueiroz/galactipy --checkout v0.1.0

Input variables

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:

Parameter	Default value	Description
project_name	Python Project	A suitable name by which people will refer to, you are free to name it however you wish to.
repo_name	based on project_name	Name of the repository to develop the project on. Check the availability of possible names before creating the project.
package_name	based on project_name	PyPI-compliant Python package name. Check the availability of possible names before creating the project.
project_description	based on project_name	A brief description of your project.
version	0.1.0	Initial version of the package. Make sure it follows the Semantic Versions specification.
author	Manoel Pereira de Queiroz	Name of the author or organisation. Used to generate LICENCE and to specify ownership in pyproject.toml.
scm_platform	GitLab	One of GitLab and GitHub. Depending on the choice you will have different features to work with.
scm_username	manoelpqueiroz	GitHub or GitLab username for hosting. Also used to set up README.md, pyproject.toml and template files for either platform.
email	based on scm_username	Email for CODE_OF_CONDUCT.md, SECURITY.md files and to specify the ownership of the project in pyproject.toml.
licence	MIT	One of MIT, BSD-3, GNU GPL v3.0, GNU AGLP v3.0, GNU LGPL v3.0, Mozilla Public License 2.0 and Apache Software License 2.0, or Not open source.
minimal_python_version	3.8	Minimal Python version. All versions since 3.8 are available to choose. It is used for builds, pipelines and formatters.
use_formatters	True	:red_triangle_pointed_up: Option to use code formatters black, isort and pyupgrade as pre-commit hooks.
line_length	88	The max length per line, dismiss if use_formatters is not used. NOTE: This value must be between 50 and 300.
use_linters	True	:red_triangle_pointed_up: Option to use linters flake8 and pydocstyle. Depending on the value of docstring_style, will also use pydoclint.
docstring_style	numpy	One of numpy, pep257 or google, dismiss if use_linters is not used. You can choose other to disable pydoclint and checks on your docstrings.
create_cli	True	:red_triangle_pointed_up: Option to create a simple CLI application with Typer and Rich libraries.
create_docker	True	:red_triangle_pointed_up: Option to create a Dockerfile to build an image for your project.
create_docs	True	:red_triangle_pointed_up: Option to create documentation files with Sphinx.

✳️ Input variables marked with :red_triangle_pointed_up: are boolean variables, you can dismiss those by typing either 0, false, f, no, n or off.

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

Demo

$ cookiecutter gl:manoelpqueiroz/galactipy
  [1/24] Project name (Python Project): A Decent Python Project
  [2/24] Project slug (a-decent-python-project): a-different-slug
  [3/24] Package name (a_decent_python_project): a_viable_package
  [4/24] Short description of the project (Awesome `a-different-slug` is a Python cli/package created with
https://gitlab.com/manoelpqueiroz/galactipy): Let's try a cool description
  [5/24] Project version (0.1.0): 1.100.9-rc7+build.456893a
  [6/24] Author or Organisation (Manoel Pereira de Queiroz):
  [7/24] In which platform would you like to host your code?
    1 - GitLab
    2 - GitHub
    Choose from [1/2] (1): 2
  [8/24] Platform username (manoelpqueiroz): myuniqueusername
  [9/24] e-Mail ([email protected]): [email protected]
  [10/24] Which licence would you like to use for your project?
    1 - MIT Licence
    2 - 3-Clause BSD
    3 - GNU GPL v3.0
    4 - GNU AGPL v3.0
    5 - GNU LGPL v3.0
    6 - Mozilla Public License 2.0
    7 - Apache Software License 2.0
    8 - Not open source
    Choose from [1/2/3/4/5/6/7/8] (1): 4
  [11/24] Minimal Python version
    1 - 3.8
    2 - 3.9
    3 - 3.10
    4 - 3.11
    Choose from [1/2/3/4] (1): 3
  [12/24] Use Black, isort and pyupgrade for formatting? [y/n] (y): yes
  [13/24] Maximum line length (88):
  [14/24] Use flake8 and pydocstyle for linting? [y/n] (y): true
  [15/24] Which docstring style would you like to use? "numpy" and "google" styles will add pydoclint as a dependency.
    1 - numpy
    2 - google
    3 - pep257
    4 - other
    Choose from [1/2/3/4] (1): 4
  [16/24] create_cli [y/n] (y): on
  [17/24] Containerize your application with Docker? [y/n] (y): no
  [18/24] Create project documentation with Sphinx? [y/n] (y): false

Your project A Decent Python Project is created.

1) Now you can start working on it:

    $ cd a-different-slug && git init

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

    $ make poetry-download

3) Initialize poetry and install pre-commit hooks:

    $ make install
    $ make pre-commit-install

4) Run codestyle:

    $ make codestyle

5) Upload initial code to GitHub:

    $ git add .
    $ git commit -m ":tada: Initial commit"
    $ git remote add origin https://github.com/myuniqueusername/a-different-slug.git
    $ git push -u origin master

More details

Your project will contain README.md file with instructions for development, deployment etc. You can read the project README.md template before.

Initial set up

Initialize poetry

By running make install

After you create a project, it will appear in your directory, and will display a message about how to initialize the project.

Initialize pre-commit

By running make pre-commit-install. Make sure to set up git first via git init.

Package example

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.

CLI example

If you set create_cli to True the template comes with a cute little CLI application example. It utilises Typer and Rich for CLI input validation and beautiful formatting in the terminal.

After installation via make install (preferred) or poetry install you can try to play with the example:

poetry run <repo_name> --help

poetry run <repo_name> --name Manoel

Building and releasing your package

Building a new version of the application contains steps:

• Bump the version of your package poetry version <version>. You can pass the new version explicitly, or a rule such as major, minor, or patch. For more details, refer to the Semantic Versions standard;
• Make a commit to GitLab or GitHub, depending on where you are hosting your code;
• Create a Release for your package on the platform;
• And... publish 🙂 poetry publish --build.

Makefile usage

Makefile contains a lot of functions for faster development.

1. Download and remove Poetry

To download and install Poetry as a standalone application run:

make poetry-download

To uninstall

make poetry-remove

Or you can install it with pip inside your virtual environment if you prefer.

2. Install all dependencies and pre-commit hooks

Install requirements with

make install

Pre-commit hooks could be installed after git init via

make pre-commit-install

3. Codestyle

Automatic formatting uses pyupgrade, isort and black, and can be run with

make codestyle

# or use synonym
make formatting

For codestyle checks only, without rewriting files:

make check-codestyle

Update all dev libraries to the latest version using one command

make update-dev-deps

4. Code security

make check-safety

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

make check-safety

5. Type checks

Run mypy static type checker with

make mypy

6. Tests with coverage badges

Run pytest with all essential parameters predefined with

make test

7. Linters

Run code and docstring linters with flake8, pydocstyle and, if you choose numpy or google style, pydoclint.

make lint

8. All linters

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

make lint-all

the same as:

make test && make check-codestyle && make lint && make mypy && make check-safety

9. Docker

make docker-build

which is equivalent to:

make docker-build VERSION=latest

Remove docker image with

make docker-remove

More information about docker.

10. Cleanup

Delete pycache files

make pycache-remove

Remove package build

make build-remove

Delete .DS_STORE files

make dsstore-remove

Remove .mypycache

make mypycache-remove

Or to remove all above run:

make cleanup

:bullseye: What's next

Well, that's up to you :flexed_biceps:.

For further setting up your project:

• Look for files and sections marked with UPDATEME, these should be updated according to the needs and characteristics of your project;
  • Tip: If you use VS Code's Todo Tree extension, you can even set a specific tag to quickly locate these marks. Update your settings.json with:

"todo-tree.highlights.customHighlight": {
    "UPDATEME": {
        "icon": "pencil",
        "iconColour": "#E63946"
    }
},
"todo-tree.general.tags": [
    "BUG",
    "HACK",
    "FIXME",
    "UPDATEME",
    "TODO",
    "XXX",
    "[ ]"
]

• 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_username for Docker Hub and you will push your image under repo_name, change it otherwise;
• 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.

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. If you chose to generate a CLI example during the Cookiecutter setup, Typer will already be among your dependencies;
• Rich makes it easy to add beautiful formatting in the terminal. If you chose to generate a CLI example during the Cookiecutter setup, Rich will already be among your dependencies;
• 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;
• 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 :beaming_face_with_smiling_eyes:
• 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;
• 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! :smiling_face_with_sunglasses:). 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!

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;
• Makefile tutorial;
• Maybe you would like to add gitmoji to commit names. This is really funny. :grinning_face_with_smiling_eyes:

:chart_increasing: Releases

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

We follow Semantic Versions specification.

We use GitLab Changelog entries to track changes. You can categorise commits and Merge Requests made to this project using git trailers in your commit messages.

List of trailers and corresponding categories

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

🧪 TODOs

This template will continue to develop and follow the bleeding edge new tools and best practices to improve the Python development experience.

Here is a list of things that have yet to be implemented:

• Tests coverage reporting with Coveralls;
• Auto uploading your package to PyPI when new release is created;
• Automatic creation of documentation. We will be using Sphinx with Furo design;
• Code metrics with Radon;
• Docstring coverage with interrogate;
• Dockerfile linting with dockerfilelint;
• Hall of fame from Sourcerer;
• Some advanced Python linting (?);
• End-to-end testing and validation of the cookiecutter template;
• Add Invoke;
• Add Earthly.

🛡️ Licence

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

:sports_medal: Acknowledgements

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 :glowing_star: 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.

Give them your ⭐, these resources are amazing! :winking_face:

📃 Citation

@misc{galactipy,
  author = {Manoel Pereira de Queiroz},
  title = {Galactipy Python Package Project Generator},
  year = {2023},
  publisher = {GitLab},
  journal = {GitLab repository},
  howpublished = {\url{https://gitlab.com/manoelpqueiroz/galactipy}}
}

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)