P3G - Python Packages Project Generator

English 中文

[![Build status](https://github.com/Undertone0809/python-package-template/workflows/build/badge.svg?branch=main&event=push)](https://github.com/Undertone0809/python-package-template/actions?query=workflow%3Abuild) [![Dependencies Status](https://img.shields.io/badge/dependencies-up%20to%20date-brightgreen.svg)](https://github.com/Undertone0809/python-package-template/pulls?utf8=%E2%9C%93&q=is%3Apr%20author%3Aapp%2Fdependabot) [![🚀 Your next Python package needs a bleeding-edge project structure.](https://img.shields.io/badge/python--package--template-%F0%9F%9A%80-brightgreen)](https://github.com/Undertone0809/python-package-template) [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![Pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/Undertone0809/python-package-template/blob/main/.pre-commit-config.yaml) [![Semantic Versions](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--versions-e10079.svg)](https://github.com/Undertone0809/python-package-template/releases) [![License](https://img.shields.io/github/license/Undertone0809/python-package-template)](https://github.com/Undertone0809/python-package-template/blob/main/LICENSE) ![Coverage Report](assets/images/coverage.svg) Your next Python package needs a bleeding-edge project structure.

This version is fork from https://github.com/TezRomacH/python-package-template. As a comparison, the current project provides better compatibility with Windows and faster lint construction. And a more lightweight way to create.

TL;DR

If you don't want to read the whole README, just click the Use this template button and start coding your Python package right now! 🚀

pip install p3g -U
p3g generate

🚀 Features

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

Development features

Supports Python 3.7 and higher.
Poetry as a dependencies manager. See configuration in pyproject.toml and setup.cfg.
Faster formatter tool, automatic codestyle with ruff to replace black, isort and pyupgrade.
Ready-to-use pre-commit hooks with code-formatting.
Type checks with ruff; docstring checks with darglint; security checks with safety and bandit
Testing with pytest.
Ready-to-use .editorconfig, .dockerignore, and .gitignore. You don't have to worry about those things.
The ability of building docker.

Deployment features

GitHub integration: issue and pr templates.
Github Actions with predefined build workflow as the default CI/CD.
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.
Always up-to-date dependencies with @dependabot. You only need to enable it.
Automatic release notes with Release Drafter. You may see the list of labels in release-drafter.yml. Works perfectly with Semantic Versions specification.

Open source community features

Ready-to-use Pull Requests templates and several Issue templates.
Files such as: LICENSE, CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SECURITY.md are generated automatically.
Stale bot that closes abandoned issues after a period of inactivity. (You will only need to setup free plan). Configuration is here.
Semantic Versions specification with Release Drafter.

🤯 How to use it

Installation

To begin using the template consider updating p3g

pip install -U p3g

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

p3g generate

Input variables

Template generator will ask you to fill some variables.

The input variables, with their default values:

Parameter	Default value	Description
`project_name`	`python-project`	Check the availability of possible name before creating the project.
`project_description`	based on the `project_name`	Brief description of your project.
`organization`	based on the `project_name`	Name of the organization. We need to generate LICENCE and to specify ownership in `pyproject.toml`.
`license`	`MIT`	One of `MIT`, `BSD-3`, `GNU GPL v3.0` and `Apache Software License 2.0`.
`minimal_python_version`	`3.7`	Minimal Python version. One of `3.7`, `3.8` and `3.9`. It is used for builds, GitHub workflow and formatters (`black`, `isort` and `pyupgrade`).
`github_name`	based on the `organization`	GitHub username for hosting. Also used to set up `README.md`, `pyproject.toml` and template files for GitHub.
`email`	based on the `organization`	Email for `CODE_OF_CONDUCT.md`, `SECURITY.md` files and to specify the ownership of the project in `pyproject.toml`.
`version`	`0.1.0`	Initial version of the package. Make sure it follows the Semantic Versions specification.
`line_length`	88	The max length per line (used for codestyle with `black` and `isort`). NOTE: This value must be between 50 and 300.
`using_tsinghua_mirror_source`	false	The tsinghua poetry mirror source
`create_example_template`	`cli`	If `cli` is chosen generator will create simple CLI application with `Typer` and `Rich` libraries. One of `cli`, `none`

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

Demo

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 pip install poetry & 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`

pre-commit is already installed if you initialize git repo before running make install. If it fails without initialization, run make install again to install pre-commit to .git.

Package example

Want to know more about Poetry? Check its documentation.

Details about Poetry

Poetry's [commands](https://python-poetry.org/docs/cli/#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_example_template to be cli 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 <project_name> --help

poetry run <project_name> --name Roman

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 GitHub.
Create a GitHub release.
And... publish 🙂 poetry publish --build

Makefile usage

Makefile contains a lot of functions for faster development.

1. Install all dependencies and pre-commit hooks

Install requirements: ```bash make install ``` Pre-commit hooks coulb be installed after `git init` via ```bash make pre-commit-install ```

2. Codestyle and type checks

Automatic formatting uses `ruff`. ```bash make format ``` Codestyle checks only, without rewriting files: ```bash make check-codestyle ``` > Note: `check-codestyle` uses `ruff` and `darglint` library

3. Code security

```bash make check-safety ``` This command launches `Poetry` integrity checks as well as identifies security issues with `Safety` and `Bandit`. ```bash make check-safety ```

4. Tests with coverage badges

Run `pytest` ```bash make test ```

5. All linters

Of course there is a command to run all linters in one: ```bash make lint ``` the same as: ```bash make check-codestyle && make test && make check-safety ```

6. Docker

```bash make docker-build ``` which is equivalent to: ```bash make docker-build VERSION=latest ``` Remove docker image with ```bash make docker-remove ``` More information [about docker](https://github.com/Undertone0809/python-package-template/tree/main/%7B%7B%20cookiecutter.project_name%20%7D%7D/docker).

7. Cleanup

Delete pycache files ```bash make pycache-remove ``` Remove package build ```bash make build-remove ``` Delete .DS_STORE files ```bash make dsstore-remove ``` Remove .mypycache ```bash make mypycache-remove ``` Or to remove all above run: ```bash make cleanup ```

🎯 What's next

Well, that's up to you 💪🏻. I can only recommend the packages and articles that helped me.

Typer is great for creating CLI applications.
Rich makes it easy to add beautiful formatting in the terminal.
Pydantic – data validation and settings management using Python type hinting.
Loguru makes logging (stupidly) simple.
tqdm – fast, extensible progress bar for Python and CLI.
IceCream is a little library for sweet and creamy debugging.
orjson – ultra fast JSON parsing library.
Returns makes you function's output meaningful, typed, and safe!
Hydra is a framework for elegantly configuring complex applications.
FastAPI is a type-driven asynchronous web framework.

Articles:

Open Source Guides.
A handy guide to financial support for open source
GitHub Actions Documentation.
Maybe you would like to add gitmoji to commit names. This is really funny. 😄

📈 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

🧪 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 (Codecov ?).
Auto uploading your package to PyPI when new GitHub release is created.
Automatic creation and deployment of documentation to GitHub pages. I look at MkDocs with Material Design theme and mkdocstrings.
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 Earthly

🛡 License

This project is licensed under the terms of the MIT license. See LICENSE for more details.

🏅 Acknowledgements

This template was inspired by several great articles:

and repositories:

Give them your ⭐️, these resources are amazing! 😉

📃 Citation

@misc{python-package-template,
  author = {Zeeland},
  title = {Python Packages Project Generator},
  year = {2023},
  publisher = {GitHub},
  journal = {GitHub repository},
  howpublished = {\url{https://github.com/Undertone0809/python-package-template}}
}

Markdown source for the badge

[![🚀 Your next Python package needs a bleeding-edge project structure.](https://img.shields.io/badge/python--package--template-%F0%9F%9A%80-brightgreen)](https://github.com/Undertone0809/python-package-template)

Undertone0809 / P3G

readme

P3G - Python Packages Project Generator

TL;DR

🚀 Features

Development features

Deployment features

Open source community features

🤯 How to use it

Installation

Input variables

Demo

More details

Initial set up

Initialize `poetry`

Initialize `pre-commit`

Package example

CLI example

Building and releasing your package

Makefile usage

🎯 What's next

📈 Releases

List of labels and corresponding titles

🧪 TODOs

🛡 License

🏅 Acknowledgements

📃 Citation

Undertone0809 / P3G

readme

P3G - Python Packages Project Generator

TL;DR

🚀 Features

Development features

Deployment features

Open source community features

🤯 How to use it

Installation

Input variables

Demo

More details

Initial set up

Initialize poetry

Initialize pre-commit

Package example

CLI example

Building and releasing your package

Makefile usage

🎯 What's next

📈 Releases

List of labels and corresponding titles

🧪 TODOs

🛡 License

🏅 Acknowledgements

📃 Citation

Initialize `poetry`

Initialize `pre-commit`