Project skeleton for Python

My copier Python project template. Tested with CTT.

Motivation

I was inspired by https://blog.jaraco.com/skeleton.

The goal of this project is to provide a skeleton for my Python projects, simultaneously trying to take on the following jaraco/skeleton challenges:

• Solve the History is Forever problem.
  • [x] The true history is not obscured.
  • [x] Existing histories are not broken until the handoff commit is pulled.
  • [ ] Attribution is not lost.
• Solve the Continuous Integration Mismatch problem.
  • [x] Downstream projects and the skeleton itself can have different CI configurations.
• Solve the Commit Integrations Mismatch problem.
  • [x] Downstream projects and the skeleton itself can reference different issues and pull requests in their commit histories.

Because the project does not copy the whole history from skeleton, many of the problems are solved by design.

How to use it

You might use this template or fork it and modify it to your needs.

Configure GitHub CLI

gh auth login

Install Redis, pipx, keyring and Copier

sudo apt update && sudo apt install pipx redis gnome-keyring
pipx install copier keyring
pipx inject copier copier-templates-extensions tomli
SKELETON=gh:skeleton-ci/skeleton-python

Create a new project

1. Make sure that you trust me.

2. Run the following command:

   copier copy --trust --vcs-ref HEAD "$SKELETON" path/to/project
   

3. Answer the questions.

4. Change directory to your project:

   cd path/to/project
   

5. Happy coding! Your repository is on GitHub and has:

• a release maker (💲 poe release),
• skeleton tool (💲 poe skeleton [upgrade|patch]),
• aesthetic badges in README.md,
• an auto-generated LICENSE file,
• a pre-configured pyproject.toml file,
• pre-configured towncrier tasks for changelog generation (💲 poe [added|changed|deprecated|removed|fixed|security]),
• a ready-to-use Poetry virtual environment with all the necessary dev dependencies installed, including poethepoet, pre-commit, mypy, Ruff, etc.
• a pre-configured CI suite for GitHub Actions (including coverage report) and pre-commit.

Incorporate to an existing project

Almost the same as above.

1. Change directory to your project:

   cd path/to/project
   

2. Run the following command:

   copier copy --trust --vcs-ref HEAD "$SKELETON" .
   

3. Answer the questions.

4. Allow copier to overwrite all files.

5. Patch your files (changes were locally reverted for your convenience). Be sure that the codebase is not lost but files maintained by skeleton are updated.

6. Run the following command:

   poe skeleton upgrade
   

7. Happy coding!

Bump the version of skeleton in your project

poe skeleton upgrade

Or, for a specific ref:

poe skeleton upgrade 1.0.0  # Upgrade to skeleton-ci/[email protected].
poe skeleton upgrade dev  # Upgrade to the latest commit on the dev branch.

Reconfigure the skeleton

poe skeleton patch

How to develop

1. Install Poetry and project dependencies.

   sudo apt install pipx  # If you don't have pipx installed yet.
   pipx install poetry
   pipx inject poetry "sync-pre-commit-lock[poetry]"
   poetry install
   

2. Install pre-commit hooks.

   pre-commit install
   

3. Test your skeleton.

   ctt
   

License

This project is licensed under the terms of the MIT License.

Credits

@jpsca, for creating Copier. @pawamoy, for creating a sample poetry project template.
@jaraco, for inspiring me to create my own skeleton, like the one he has.

Read more about copier.
Read more about jaraco/skeleton.

(C) 2023–present Bartosz Sławecki (@bswck).