msclock / ss-python

A development-focused Python project template with various integrations, configurations and modules.

Serious Scaffold Python

An evolving Python project template that covers the full development lifecycle.

Warning

Serious Scaffold Python is in the Alpha phase. Frequent changes and instability should be anticipated. Any feedback, comments, suggestions and contributions are welcome!

Setting up a project often involves more than just establishing a basic project structure. It involves tasks like integrating GitHub Actions or GitLab CI/CD, configuring lint, test and documentation, as well as implementing settings, logging and other frequently used modules. Serious Scaffold Python streamlines this process. Powered by copier, bootstrapping a new Python project can be done with a single command. By answering a few questions, the project will be fully configured and ready for development. Furthermore, the project can be updated alongside the advancement of the template.

If you find this helpful, please consider sponsorship.

🛠️ Features

• Project setup and template update with copier.
• Manage dependencies and virtual environments with pdm.
• Version the package using dynamic SCM tag with pdm-backend.
• Containerization for development and deployment with dev container.
• Automate dependency updates with Renovate.
• Automate Git hooks with pre-commit hooks and local linters.
• Lint with mypy, ruff, toml-sort and commitlint.
• Test with pytest and coverage for threshold and reports.
• Documentation with sphinx, the furo theme, and mypy/coverage reports.
• Continuous Integration with GitHub Actions and GitLab CI/CD.
• Latest stable documentation published to GitHub/GitLab Pages.
• Versioned documentation and pull request previews with Read the Docs.
• Develop Command Line Interfaces with typer.
• Manage configurations with pydantic-settings.
• Centralize common actions with a unified Makefile.
• VSCode settings with recommended extensions.

🔧 Prerequisites

Certain system-level Python applications are needed and it is recommended to use pipx to install and run them in isolated environments. Refer to pipx's installation instructions here. Once pipx is set up, install the necessary tools using the following commands.

# Copier: Template rendering for projects.
pipx install copier==9.2.0
# PDM: A modern Python package and dependency manager supporting the latest PEP standards.
pipx install pdm==2.15.0
# Pre-commit: Automates Git hooks for code quality checks.
pipx install pre-commit==3.7.0

🚀 Quickstart

1. Generate the project.

   copier copy gh:serious-scaffold/ss-python /path/to/project

2. Navigate to the project directory and initialize a git repository.

   cd /path/to/project
   git init

3. Set up the development environment.

   make dev

4. Commit the initialized project.

   git add .
   git commit -m "Initialize from serious-scaffold."

5. That's it! Feel free to focus on the coding within src folder.

🛡 Badge

Badge for markdown:

[![Serious Scaffold Python](https://img.shields.io/endpoint?url=https://serious-scaffold.github.io/ss-python/_static/badges/logo.json)](https://serious-scaffold.github.io/ss-python)

Badge for restructuredtext:

.. image:: https://img.shields.io/endpoint?url=https://serious-scaffold.github.io/ss-python/_static/badges/logo.json
    :target: serious-scaffold.github.io/ss-python

It will look like this:

📜 License

MIT License, for more details, see the LICENSE file.