browniebroke / pypackage-template Goto Github PK

View Code? Open in Web Editor NEW

55.0 4.0 15.0 907 KB

A project template for Python package with heavy use of Github actions

License: MIT License

Python 41.79% Makefile 4.92% Batchfile 4.94% JavaScript 1.56% Jinja 46.78%

python package pypi copier-template poetry-python

pypackage-template's Introduction

Python Package Template

Project template for a Python Package using Copier.

Features

Project for Python 3.8+.
Testing with Pytest using GitHub actions.
Packaging powered by poetry.
Optionally generates a CLI entry point powered by Typer and Rich.
Uses Ruff for formatting and linting.
Comes with pre-commit hook config for Ruff.
Style guide enforced on CI.
Dependencies kept up to date by Renovate.
Follow the all-contributors specification.
Follow to the conventional commits specification.
Automated releasing using python-semantic-release.
Documentation configured with Sphinx and MyST Parser.
Standardised list of GitHub labels synchronised on push to master using the labels CLI.

Usage

Generate a new project with:

copier copy --trust "gh:browniebroke/pypackage-template" path-to-project

This will prompt you for a few questions and create new directory with the name you used as project slug.

Note: the --trust option is required because this template may execute some tasks after generating the project, like initialising the git repo, installing dependencies and so forth. These are all listed in the copier.yml of this repo, under the _tasks key. They are all optional and safe to run. You can take my word for it, or better, check the code yourself!

Start developing

The project uses Poetry for dependencies management and packaging. Make sure you have it installed in your development machine. To install the development dependencies in a virtual environment, type:

poetry install

This will also generate a poetry.lock file, you should track this file in version control. To execute the test suite, call pytest inside Poetry's virtual environment via poetry run:

poetry run pytest

Check out the Poetry documentation for more information on the available commands.

GitHub Actions

When you first push to GitHub, it'll start a ci GitHub workflow that you can see in the "Actions" tab of your repository. This workflow runs a couple of jobs:

The test job will run your test suite with Pytest against all Python version from 3.8 to 3.11
A few things will run in the lint job:
- Ruff format
- Ruff lint with several flake8, isort and pyupgrade plugins.

A labels workflow will also run and synchronise the GitHub labels based on the .github/labels.toml file.

Secrets

The workflows need a few secrets to be setup in your GitHub repository:

GH_PAT a personal access token (PAT) with the repo scope for opening pull requests and updating the repository topics. This is used by the poetry-upgrade and labels workflows.
CODECOV_TOKEN to upload coverage data to codecov.io in the Test workflow.

If you have the GitHub CLI installed and chose to set up GitHub, they will be created with a dummy value (changeme).

Automated release

By following the conventional commits specification, we're able to completely automate versioning and releasing to PyPI. It runs on every push to your main branch, as part of the release job of the ci.yml workflow. You'll need to create the first version manually in PyPI and then setup trusted publisher for the project.

Here is an overview of its features:

Check the commit log since the last release, and determine the next version to be released.
If no significant change detected, stop here (e.g. just dependencies update).
Otherwise, bump the version in code locations specified in setup.cfg.
Update the CHANGELOG.md file.
Commit changes.
Create a git tag.
Push to GitHub.
Create a release in GitHub with the changes as release notes.
Build the source and binary distribution (wheel).
Upload the sources to PyPI and attach them to the Github release, using trusted publisher.

For more details, check out the conventional commits website and Python semantic release Github action.

Pre-commit

The project comes with the config for pre-commit. If you're not familiar with it, follow their documentation on how to install it and set it up.

Documentation

The project assumes that the documentation will be hosted on Read the Docs and written in Markdown with the MyST parser for Sphinx.

To enable it, you might need to go into your dashboard and import the project from Github. Everything else should work out of the box.

Dependencies update

The project dependencies are kept up to date with Renovate which requires the Github app to be installed.

The main advantage of Renovate over Dependabot is the auto-merge option, which is configured to automatically merge minor/patch updates with all the CI checks passing. It supports a variety of package managers, including Poetry, GitHub actions and pre-commit hooks which are used by default.

All contributors

This is a specification that help you highlight every open source contribution in your README. This is easy to maintain as it comes with a GitHub bot to do the updates for you, so more manual updates on the contributors file.

If you never used it before, you will have to install the Github app and give it access to your repo.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

_{Bruno Alla}
💻 🤔 📖

_{Jeff Tsay}
💻

_34j
💻

_{Stefan Rado}
📖

This project follows the all-contributors specification. Contributions of any kind welcome!

pypackage-template's People

Contributors

Stargazers

Watchers

Forkers

cloudreactor adsabs josekurian rodrigo-georgian gavincyi 34j cuinixam hvoecking sometxdude

pypackage-template's Issues

Increase the variety of available licenses

Is your feature request related to a problem? Please describe.
Copy-pasting the license is a pain.

Describe the solution you'd like
Add more licenses such as CC0, Unlicense, BSD, MS-PL, AGPL, etc.

Additional context

Add nb-clean

Is your feature request related to a problem? Please describe.
I'm always frustrated that import statements and example notebooks are messed up. It is a burden to manually add autoflake and nb-clean.

Describe the solution you'd like
Add autoflake and nb-clean. .pre-commit-config.yaml and pyproject.toml must be changed.

Additional context
I can send a PR for this. Thank you so much for this wonderful template.

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Repository problems

These problems occurred while renovating this repository. View logs.

WARN: Use matchDepNames instead of matchPackageNames

This repository currently has no open or pending branches.

Detected dependencies

github-actions

.github/workflows/ci.yml

actions/checkout v4

actions/setup-python v5

actions/checkout v4

actions/setup-python v5

.github/workflows/issue-manager.yml

tiangolo/issue-manager 0.5.0

.github/workflows/labels.yml

actions/checkout v4

actions/setup-python v5

.github/workflows/poetry-upgrade.yml

browniebroke/github-actions v1

project/.github/workflows/ci.yml

actions/checkout v4

actions/setup-python v5

pre-commit/action v3.0.1

actions/checkout v4

wagoid/commitlint-github-action v6.0.1

actions/checkout v4

actions/setup-python v5

codecov/codecov-action v4

actions/checkout v4

python-semantic-release/python-semantic-release v9.8.1

python-semantic-release/python-semantic-release v9.8.1

project/.github/workflows/issue-manager.yml

tiangolo/issue-manager 0.5.0

project/.github/workflows/labels.yml

actions/checkout v4

actions/setup-python v5

pep621

pyproject.toml

poetry-core >=1.0.0

poetry

pyproject.toml

python ^3.8

copier ^9.0.0

pytest ^8.0.0

pytest-mock ^3.3

pre-commit

.pre-commit-config.yaml

pre-commit/pre-commit-hooks v4.6.0

python-poetry/poetry 1.8.3

pre-commit/mirrors-prettier v3.1.0

astral-sh/ruff-pre-commit v0.4.8

codespell-project/codespell v2.3.0

project/.pre-commit-config.yaml

commitizen-tools/commitizen v3.27.0

pre-commit/pre-commit-hooks v4.6.0

python-poetry/poetry 1.8.3

pre-commit/mirrors-prettier v3.1.0

astral-sh/ruff-pre-commit v0.4.8

codespell-project/codespell v2.3.0

pre-commit/mirrors-mypy v1.10.0

Check this box to trigger a request for Renovate to run again on this repository

Action Required: Fix Renovate Configuration

There is an error with this repository's Renovate configuration that needs to be fixed. As a precaution, Renovate will stop PRs until it is resolved.

Error type: Cannot find preset's package (github>whitesource/merge-confidence:beta)

Github Access failed on Windows

Describe the bug
Creating repository from template failed, because of missing access to github.

To Reproduce
I hopefully installed finally all necessary but not really mentioned dependencies for this template. I've started creating the template and entered every informations. For the options after the License, I choosed for every option y. Afterwards an empty repository is created on github but the rest of the template setup is failing. I've provided the output below. You can also see, that something isn't working correctly with the virutalenv setup. So the recreating is not my normal procedure, I put my venv usually on project path.

Additional context

The virtual environment found in <mypath>\BiQueue\.venv seems to be broken.
Recreating virtualenv biqueue-3I_JrI2z-py3.9 in C:\Users\Admin\AppData\Local\pypoetry\Cache\virtualenvs\biqueue-3I_JrI2z-py3.9
Updating dependencies
Resolving dependencies...

Writing lock file

Package operations: 33 installs, 0 updates, 0 removals

  • Installing attrs (21.4.0)
  • Installing pyparsing (3.0.7)
  • Installing atomicwrites (1.4.0)
  • Installing colorama (0.4.4)
  • Installing distlib (0.3.4)
  • Installing filelock (3.4.2)
  • Installing iniconfig (1.1.1)
  • Installing platformdirs (2.4.1)
  • Installing pluggy (1.0.0)
  • Installing packaging (21.3)
  • Installing py (1.11.0)
  • Installing toml (0.10.2)
  • Installing six (1.16.0)
  • Installing tomli (1.2.3)
  • Installing click (8.0.3)
  • Installing coverage (6.2)
  • Installing mypy-extensions (0.4.3)
  • Installing pycodestyle (2.8.0)
  • Installing pathspec (0.9.0)
  • Installing mccabe (0.6.1)
  • Installing virtualenv (20.13.0)
  • Installing typing-extensions (4.0.1)
  • Installing tokenize-rt (4.2.1)
  • Installing pytest (6.2.5)
  • Installing pyflakes (2.4.0)
  • Installing black (21.12b0)
  • Installing flake8 (4.0.1)
  • Installing isort (5.10.1)
  • Installing mypy (0.931)
  • Installing tox (3.24.5)
  • Installing pytest-srcpaths (1.2.1)
  • Installing pytest-cov (3.0.0)
  • Installing pyupgrade (2.31.0)

Installing the current project: biqueue (0.0.1)
Initialized empty Git repository in <mypath>/biqueue/.git/
warning: LF will be replaced by CRLF in poetry.lock.
The file will have its original line endings in your working directory
[master (root-commit) a5ff123] chore: initial commit
 41 files changed, 2968 insertions(+)
 create mode 100644 .all-contributorsrc
 create mode 100644 .editorconfig
 create mode 100644 .flake8
 create mode 100644 .github/FUNDING.yml
 create mode 100644 .github/ISSUE_TEMPLATE/1-bug_report.md
 create mode 100644 .github/ISSUE_TEMPLATE/2-feature-request.md
 create mode 100644 .github/labels.toml
 create mode 100644 .github/workflows/ci.yml
 create mode 100644 .github/workflows/hacktoberfest.yml
 create mode 100644 .github/workflows/issue-manager.yml
 create mode 100644 .github/workflows/labels.yml
 create mode 100644 .gitignore
 create mode 100644 .gitpod.yml
 create mode 100644 .idea/biqueue.iml
 create mode 100644 .idea/watcherTasks.xml
 create mode 100644 .idea/workspace.xml
 create mode 100644 .pre-commit-config.yaml
 create mode 100644 .readthedocs.yml
 create mode 100644 CHANGELOG.md
 create mode 100644 CONTRIBUTING.md
 create mode 100644 LICENSE
 create mode 100644 README.md
 create mode 100644 commitlint.config.js
 create mode 100644 docs/Makefile
 create mode 100644 docs/make.bat
 create mode 100644 docs/source/_static/.gitkeep
 create mode 100644 docs/source/changelog.md
 create mode 100644 docs/source/conf.py
 create mode 100644 docs/source/contributing.md
 create mode 100644 docs/source/index.md
 create mode 100644 docs/source/installation.md
 create mode 100644 docs/source/usage.md
 create mode 100644 poetry.lock
 create mode 100644 pyproject.toml
 create mode 100644 renovate.json
 create mode 100644 setup.py
 create mode 100644 src/biqueue/__init__.py
 create mode 100644 src/biqueue/main.py
 create mode 100644 src/biqueue/py.typed
 create mode 100644 tests/__init__.py
 create mode 100644 tests/test_main.py
✓ Created repository MaKaNu/biqueue on GitHub
✓ Added remote [email protected]:MaKaNu/biqueue.git
[email protected]: Permission denied (publickey).
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.
E:\Git\cmd\git.exe: exit status 128
Traceback (most recent call last):
  File "C:\Users\Admin\AppData\Local\Temp\tmpq0xk341d.py", line 116, in <module>
    main()
  File "C:\Users\Admin\AppData\Local\Temp\tmpq0xk341d.py", line 106, in main
    setup_github()
  File "C:\Users\Admin\AppData\Local\Temp\tmpq0xk341d.py", line 39, in setup_github
    run_cmd(
  File "C:\Users\Admin\AppData\Local\Temp\tmpq0xk341d.py", line 5, in run_cmd
    return subprocess.run(args, check=True, **kwargs)
  File "F:\Programme\Python3_9\lib\subprocess.py", line 528, in run
    raise CalledProcessError(retcode, process.args,
subprocess.CalledProcessError: Command '['gh', 'repo', 'create', 'MaKaNu/biqueue', '-d', 'BiQueue is a opencv based bidirectional threaded videostream.', '--public', '--disable-wiki=true', '--remote=origin', '--source=.', '--push']' returned non-zero exit status 1.
ERROR: Stopping generation because post_gen_project hook script didn't exit successfully
Hook script failed (exit status: 1)

Improvements for docs/conf.py

Is your feature request related to a problem? Please describe.
It is a pain to set up automatic documentation.

Describe the solution you'd like
Add "sphinx.ext.napoleon", "sphinx.ext.autodoc". and "sphinx.ext.viewcode". I think these are all commonly used extensions.

Additional context
Example
I can send a PR for this.

Add a Pull Request Template

Is your feature request related to a problem? Please describe.
The lack of a Pull Request Template disrupts the project.

Describe the solution you'd like
At least add a checkbox for pre-commit because too many people don't run pre-commit.

Additional context

Change `rangeStrategy` for `python`

Is your feature request related to a problem? Please describe.
I am frustrated when Renovate opens a PR that tries to shrink the Python version.
(e.g. >=3.8,<3.12 -> >=3.12,<3.13)

Describe the solution you'd like
I am not very familiar with Renovate, but I was wondering if this could be accomplished by setting the rangeStrategy to widen (only for python).
https://docs.renovatebot.com/configuration-options/#rangestrategy

Additional context
34j/cached-historical-data-fetcher#17

"Release" step not evaluated

Describe the bug

Step "release" is not evaluated.
I would expect not to be run if evaluated as false, but I miss the full step in the below log.

Debug log is not helpful either.

To Reproduce

Copy this repo with copier
Commit code
Wait for CI to make a release

Additional context
Log: https://github.com/chemelli74/fitbit-web-api/actions/runs/7193699069/job/19592762516

Improvements for copier.yml

Is your feature request related to a problem? Please describe.
It's a pain to enter GITHUB_TOKEN, EMAIL and manually create the venv then install packages then run pre-commit.

Describe the solution you'd like
Use my jinja2_env to get GITHUB_TOKEN and EMAIL from environment variables and automate. Also create venv automatically by command. The operation must be different depending on the operating system. Example In addition, the copyright year can be automatically entered using jinja2_time. This allows more options to be turned on by default.

Additional context
Setting GITHUB_TOKEN as an environment variable is a security concern, but I think it is a win-win to implement as only those who have no concerns can use it. I think I can send a PR for this.

Set `separateMultipleMinor` for `python` to `"true"` in Renovate configs

Is your feature request related to a problem? Please describe.
I am frustrated that Renovate PRs for Python version updates are never automatically merged because it is very rare to be able to update to the latest minor version of Python at once (e.g. when relying on libraries such as numpy and numba).

Describe the solution you'd like
Change the settings after this issue (feature request) is resolved.
renovatebot/renovate#6576
renovatebot/renovate#24538

Additional context

It might be better to configure each repository individually.
Related: #597
Sorry for opening so many issues.

Support https://reuse.software/

Is your feature request related to a problem? Please describe.
I would like to have solid licensing of my software.

Describe the solution you'd like
https://reuse.software/ is the best approach to do that I know of.

Additional context
I have been using REUSE for some time now. Adding the license info to every file looks bulky at first but as each file might be under a different license, I came to like this explicit way of doing things.

browniebroke / pypackage-template Goto Github PK

pypackage-template's Introduction

Python Package Template

Features

Usage

Start developing

GitHub Actions

Secrets

Automated release

Pre-commit

Documentation

Dependencies update

All contributors

Contributors ✨

pypackage-template's People

Contributors

Stargazers

Watchers

Forkers

pypackage-template's Issues

Repository problems

Detected dependencies

Recommend Projects

Recommend Topics

Recommend Org