{"id":24956419,"url":"https://github.com/shin-sforzando/python-boilerplate","last_synced_at":"2026-05-09T14:38:55.735Z","repository":{"id":39887999,"uuid":"449939846","full_name":"shin-sforzando/python-boilerplate","owner":"shin-sforzando","description":"Template repository for using Docker \u0026 Python","archived":false,"fork":false,"pushed_at":"2024-07-10T06:07:05.000Z","size":7443,"stargazers_count":1,"open_issues_count":3,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-02-03T06:35:35.401Z","etag":null,"topics":["boilerplate","docker","docker-compose","python3","template-repository"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shin-sforzando.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-01-20T03:23:19.000Z","updated_at":"2023-11-30T04:52:34.000Z","dependencies_parsed_at":"2024-01-16T18:58:49.717Z","dependency_job_id":"a98e92ee-326a-4249-a4a2-334a5f4641b7","html_url":"https://github.com/shin-sforzando/python-boilerplate","commit_stats":null,"previous_names":[],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shin-sforzando%2Fpython-boilerplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shin-sforzando%2Fpython-boilerplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shin-sforzando%2Fpython-boilerplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shin-sforzando%2Fpython-boilerplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shin-sforzando","download_url":"https://codeload.github.com/shin-sforzando/python-boilerplate/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246098108,"owners_count":20723175,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["boilerplate","docker","docker-compose","python3","template-repository"],"created_at":"2025-02-03T06:35:16.132Z","updated_at":"2026-05-09T14:38:55.703Z","avatar_url":"https://github.com/shin-sforzando.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# python-boilerplate\n\n\u003c!-- Badges --\u003e\n[![Last Commit](https://img.shields.io/github/last-commit/shin-sforzando/python-boilerplate)](https://github.com/shin-sforzando/python-boilerplate/graphs/commit-activity)\n[![CI](https://github.com/shin-sforzando/python-boilerplate/actions/workflows/ci.yml/badge.svg)](https://github.com/shin-sforzando/python-boilerplate/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/shin-sforzando/python-boilerplate/branch/main/graph/badge.svg?token=TDCVLUJ4RF)](https://codecov.io/gh/shin-sforzando/python-boilerplate)\n[![GitHub Pages](https://github.com/shin-sforzando/python-boilerplate/actions/workflows/pages.yml/badge.svg)](https://shin-sforzando.github.io/python-boilerplate/)\n[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/6067/badge)](https://bestpractices.coreinfrastructure.org/projects/6067)\n\n\u003c!-- Screenshots --\u003e\n| ![Screenshot 1](https://placehold.jp/32/3d4070/ffffff/720x480.png?text=Screenshot%201) | ![Screenshot 2](https://placehold.jp/32/703d40/ffffff/720x480.png?text=Screenshot%202) |\n|:--------------------------------------------------------------------------------------:|:--------------------------------------------------------------------------------------:|\n|                                      Screenshot 1                                      |                                      Screenshot 2                                      |\n\n\u003c!-- Synopsis --\u003e\n**python-boilerplate** is a template repository for using Docker \u0026 Python.\n\n## *Use this template*\n\n- [ ] Replace the string `shin-sforzando` with the actual project owner\n- [ ] Replace the string `python-boilerplate` with the actual project name\n- [ ] Create an issue `#1` for screenshots\n- [ ] `lefthook install` to install git hooks\n- [ ] Check the [repository secrets](https://github.com/shin-sforzando/python-boilerplate/settings/secrets/actions)\n  - [ ] `git secret remove dev@sforzando.co.jp.asc` to delete it\n  - [ ] Set `SCORECARD_READ_TOKEN` for OpenSSF\n  - [ ] Set `CODECOV_TOKEN` of this repository if it's **private**\n  - [ ] Check `codecov` step in `.github/workflows/ci.yml` if it's **private**\n- [ ] Prepare [GitHub Pages](https://github.com/shin-sforzando/python-boilerplate/settings/pages)\n- [ ] Arrange `sider.yml` to match the project\n- [ ] Delete `.github/workflows/codeql-analysis.yml` if it's **private**\n- [ ] Submit [OpenSSF Best Practices Badge Program](https://bestpractices.coreinfrastructure.org/en)\n- [ ] Integrate with Slack: `/github subscribe shin-sforzando/python-boilerplate reviews comments branches commits:*`\n- [ ] **Delete this section!**\n\n\u003c!-- TOC --\u003e\n- [*Use this template*](#use-this-template)\n- [Prerequisites](#prerequisites)\n- [How to](#how-to)\n  - [First time preparation](#first-time-preparation)\n    - [Init](#init)\n    - [Reveal Secrets](#reveal-secrets)\n    - [Setup Git Hooks (Lefthook)](#setup-git-hooks-lefthook)\n  - [Develop](#develop)\n    - [`.env`](#env)\n    - [Start](#start)\n    - [Shell](#shell)\n    - [Format](#format)\n    - [Lint](#lint)\n    - [Test](#test)\n  - [Document](#document)\n    - [API Document](#api-document)\n    - [CHANGELOG](#changelog)\n  - [Deploy](#deploy)\n  - [Clean](#clean)\n- [Misc](#misc)\n- [Notes](#notes)\n  - [LICENSE](#license)\n  - [Contributors](#contributors)\n\n## Prerequisites\n\n```mermaid\n%%{init: {'theme': 'neutral' } }%%\ngraph LR\n    subgraph D[Docker]\n      P(Python)\n    end\n```\n\n- [Docker](https://www.docker.com) as *Environment Isolator*\n  - [Python](https://www.python.org) (Version 3.10 or higher)\n    - Production Dependencies\n      - (T. B. D.)\n    - Development Dependencies\n      - [black](https://github.com/psf/black) as *Python Formatter*\n      - [flake8](https://pypi.org/project/flake8/) as *Python Code Linter*\n      - [Sphinx](https://www.sphinx-doc.org/) as *Python Document Generator*\n      - [loguru](https://github.com/Delgan/loguru) as *Application Logger*\n      - [pytest](https://pypi.org/project/pytest/) for *Application Test*\n        - [pytest-xdist](https://pypi.org/project/pytest-xdist/) for *Parallel Testing*\n  - [secretlint](https://github.com/secretlint/secretlint) as *Credential Linter*\n- [Lefthook](https://github.com/evilmartians/lefthook) as *Git Hooks Manager*\n- [git-secret](https://git-secret.io/) as *Secret File Manager*\n- [direnv](https://direnv.net) as *`.env` Loader*\n\n## How to\n\n```shell\n$ make help\ndefault              常用\ninit                 初期\nps                   状況\nbuild                構築\nup                   起動\nrenew                転生\nshell                接続\nlogs                 記録\nfollow               追跡\nopen                 閲覧\nhide                 秘匿\nreveal               暴露\nstart                開始\nformat               整形\nlint                 検証\ntest                 試験\npytest               試験\ndoc                  文書\nsphinx               文書\ndeploy               配備\nstop                 停止\ndown                 削除\nclean                掃除\nprune                破滅\nhelp                 助言\n```\n\n### First time preparation\n\n#### Init\n\nTo install some development commands, run below.\n\n```shell\nmake init\n```\n\n#### Reveal Secrets\n\nTo install [git-secret](https://git-secret.io/) via [Homebrew](https://brew.sh) manually, `brew install git-secret`.\nTo install [direnv](https://direnv.net) via [Homebrew](https://brew.sh) manually, `brew install direnv`.\n\nDevelopers who share a GPG key with their team can decrypt confidential information.\n\nTo reveal the secret information (= `*.secrets`), run below.\n\n```shell\nmake reveal\n```\n\nIf there are `.env` -like files included in `*.secrets`, [direnv](https://direnv.net) try to load them automatically.\n`direnv allow` to approve it.\n\nOn the other hand, to encrypt the updated secret information, run below.\n\n```shell\nmake hide\n```\n\n#### Setup Git Hooks (Lefthook)\n\nTo install [Lefthook](https://github.com/evilmartians/lefthook) via [Homebrew](https://brew.sh), `brew install lefthook`.\n\n```shell\nlefthook install\n```\n\nThereafter, each commit will validate by `make format` and `make lint`, and each push will validate by `make test` and [secretlint](https://github.com/secretlint/secretlint).\n\n### Develop\n\nCommands that are often used during development should be prepared in `default`.\n\n```shell\nmake\n```\n\n#### `.env`\n\nMake sure there is `.env` like below before starting development.\n\n```.env\nDEBUG=True\n```\n\nUsually, `.env` is prepared by [Reveal Secrets](#reveal-secrets) action.\nDon't forget that it needs to run `direnv allow` every time the `.env` is changed.\n\n`docker-compose` automatically loads `.env` at build.\nTo apply even inside the Docker container, use `env_files` in `docker-compose.yml`.\n\n#### Start\n\nIf it succeeds, [http.server](https://docs.python.org/3/library/http.server.html) will start waiting on `http://0.0.0.0:8000/`.\nTo check this address, run below.\n\n```shell\nmake open\n```\n\nTo view container's log, run one of the following commands.\n\n```shell\nmake logs    # View last output from containers.\nmake follow  # Follow outputs from containers.\n```\n\n#### Shell\n\nTo connect `app` container using Bash, run below.\n\n```shell\nmake bash\n```\n\n#### Format\n\nTo format Python source codes using [Black](https://github.com/psf/black) manually, run below.\n\n```shell\nmake format\n```\n\n#### Lint\n\nTo lint Python source codes using [flake8](https://pypi.org/project/flake8/) manually, run below.\n\n```shell\nmake lint\n```\n\n#### Test\n\nTo test Python source codes using [pytest](https://docs.pytest.org/) manually, run below.\n\n```shell\nmake test\n```\n\n### Document\n\n#### API Document\n\nWhen the main branch is updated, `pages.yml` will update the [API Document](https://shin-sforzando.github.io/python-boilerplate/).\n\nTo generate API Documents using [Sphinx](https://www.sphinx-doc.org/) manually, run below.\n\n```shell\nmake doc\n```\n\n#### CHANGELOG\n\nTo install [git-cliff](https://github.com/orhun/git-cliff) via [Homebrew](https://brew.sh) manually, `brew install git-cliff`.\n\nTo update `CHANGELOG.md` manually, run [git-cliff](https://github.com/orhun/git-cliff) like below.\n\n```shell\ngit cliff --output CHANGELOG.md\n```\n\n### Deploy\n\nTo deploy this to `(T. B. D.)` manually, run below.\n\n```shell\nmake deploy\n```\n\n### Clean\n\nTo clean up miscellaneous files, run below.\n\n```shell\nmake clean\n```\n\n## Misc\n\n## Notes\n\nThis repository is [Commitizen](https://commitizen.github.io/cz-cli/) friendly, following [GitHub flow](https://docs.github.com/en/get-started/quickstart/github-flow).\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for details.\n\n### LICENSE\n\nSee [LICENSE](LICENSE).\n\n### Contributors\n\n- [sforzando LLC. and Inc.](https://sforzando.co.jp/)\n  - [Shin'ichiro Suzuki](https://github.com/shin-sforzando)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshin-sforzando%2Fpython-boilerplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshin-sforzando%2Fpython-boilerplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshin-sforzando%2Fpython-boilerplate/lists"}