python-boilerplate

Screenshot 1	Screenshot 2

python-boilerplate is a template repository for using Docker & Python.

Use this template

• Replace the string shin-sforzando with the actual project owner
• Replace the string python-boilerplate with the actual project name
• Create an issue #1 for screenshots
• lefthook install to install git hooks
• Check the repository secrets
  • git secret remove [email protected] to delete it
  • Set SCORECARD_READ_TOKEN for OpenSSF
  • Set CODECOV_TOKEN of this repository if it's private
  • Check codecov step in .github/workflows/ci.yml if it's private
• Prepare GitHub Pages
• Arrange sider.yml to match the project
• Delete .github/workflows/codeql-analysis.yml if it's private
• Submit OpenSSF Best Practices Badge Program
• Integrate with Slack: /github subscribe shin-sforzando/python-boilerplate reviews comments branches commits:*
• Delete this section!

• Use this template
• Prerequisites
• How to
  • First time preparation
    • Init
    • Reveal Secrets
    • Setup Git Hooks (Lefthook)
  • Develop
    • .env
    • Start
    • Shell
    • Format
    • Lint
    • Test
  • Document
    • API Document
    • CHANGELOG
  • Deploy
  • Clean
• Misc
• Notes
  • LICENSE
  • Contributors

Prerequisites

%%{init: {'theme': 'neutral' } }%%
graph LR
    subgraph D[Docker]
      P(Python)
    end

Loading

• Docker as Environment Isolator
  • Python (Version 3.10 or higher)
    • Production Dependencies
      • (T. B. D.)
    • Development Dependencies
      • black as Python Formatter
      • flake8 as Python Code Linter
      • Sphinx as Python Document Generator
      • loguru as Application Logger
      • pytest for Application Test
        • pytest-xdist for Parallel Testing
  • secretlint as Credential Linter
• Lefthook as Git Hooks Manager
• git-secret as Secret File Manager
• direnv as .env Loader

How to

$ make help
default              常用
init                 初期
ps                   状況
build                構築
up                   起動
renew                転生
shell                接続
logs                 記録
follow               追跡
open                 閲覧
hide                 秘匿
reveal               暴露
start                開始
format               整形
lint                 検証
test                 試験
pytest               試験
doc                  文書
sphinx               文書
deploy               配備
stop                 停止
down                 削除
clean                掃除
prune                破滅
help                 助言

First time preparation

Init

To install some development commands, run below.

make init

Reveal Secrets

To install git-secret via Homebrew manually, brew install git-secret. To install direnv via Homebrew manually, brew install direnv.

Developers who share a GPG key with their team can decrypt confidential information.

To reveal the secret information (= *.secrets), run below.

make reveal

If there are .env -like files included in *.secrets, direnv try to load them automatically. direnv allow to approve it.

On the other hand, to encrypt the updated secret information, run below.

make hide

Setup Git Hooks (Lefthook)

To install Lefthook via Homebrew, brew install lefthook.

lefthook install

Thereafter, each commit will validate by make format and make lint, and each push will validate by make test and secretlint.

Develop

Commands that are often used during development should be prepared in default.

make

.env

Make sure there is .env like below before starting development.

DEBUG=True

Usually, .env is prepared by Reveal Secrets action. Don't forget that it needs to run direnv allow every time the .env is changed.

docker-compose automatically loads .env at build. To apply even inside the Docker container, use env_files in docker-compose.yml.

Start

If it succeeds, http.server will start waiting on http://0.0.0.0:8000/. To check this address, run below.

make open

To view container's log, run one of the following commands.

make logs    # View last output from containers.
make follow  # Follow outputs from containers.

Shell

To connect app container using Bash, run below.

make bash

Format

To format Python source codes using Black manually, run below.

make format

Lint

To lint Python source codes using flake8 manually, run below.

make lint

Test

To test Python source codes using pytest manually, run below.

make test

Document

API Document

When the main branch is updated, pages.yml will update the API Document.

To generate API Documents using Sphinx manually, run below.

make doc

CHANGELOG

To install git-cliff via Homebrew manually, brew install git-cliff.

To update CHANGELOG.md manually, run git-cliff like below.

git cliff --output CHANGELOG.md

Deploy

To deploy this to (T. B. D.) manually, run below.

make deploy

Clean

To clean up miscellaneous files, run below.

make clean

Misc

Notes

This repository is Commitizen friendly, following GitHub flow. See CONTRIBUTING.md for details.

LICENSE

See LICENSE.

Contributors

• sforzando LLC. and Inc.
  • Shin'ichiro Suzuki