{"id":38054682,"url":"https://github.com/johnnymillergh/python-boilerplate","last_synced_at":"2026-04-06T05:03:41.312Z","repository":{"id":46246990,"uuid":"424551877","full_name":"johnnymillergh/python-boilerplate","owner":"johnnymillergh","description":"python_boilerplate is a boilerplate project for Python. Based on template sourcery-ai/python-best-practices-cookiecutter.","archived":false,"fork":false,"pushed_at":"2026-02-14T02:23:37.000Z","size":1039,"stargazers_count":4,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-14T08:30:51.094Z","etag":null,"topics":["black","boilerplate-template","docker","flake8","isort","matplotlib","mypy","numpy","pandas","peewee","pipenv","pydantic","pytest","python3","tenacity"],"latest_commit_sha":null,"homepage":"https://johnnymillergh.github.io/python-boilerplate/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/johnnymillergh.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-11-04T10:18:20.000Z","updated_at":"2025-08-24T07:30:58.000Z","dependencies_parsed_at":"2023-10-31T01:27:52.378Z","dependency_job_id":"e464b124-af0c-4cd4-aaef-3f9a17b6c41e","html_url":"https://github.com/johnnymillergh/python-boilerplate","commit_stats":null,"previous_names":["johnnymillergh/python-boilerplate","johnnymillergh/python_boilerplate"],"tags_count":20,"template":true,"template_full_name":null,"purl":"pkg:github/johnnymillergh/python-boilerplate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnnymillergh%2Fpython-boilerplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnnymillergh%2Fpython-boilerplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnnymillergh%2Fpython-boilerplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnnymillergh%2Fpython-boilerplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/johnnymillergh","download_url":"https://codeload.github.com/johnnymillergh/python-boilerplate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnnymillergh%2Fpython-boilerplate/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31460106,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T21:22:52.476Z","status":"online","status_checked_at":"2026-04-06T02:00:07.287Z","response_time":112,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["black","boilerplate-template","docker","flake8","isort","matplotlib","mypy","numpy","pandas","peewee","pipenv","pydantic","pytest","python3","tenacity"],"created_at":"2026-01-16T20:22:28.769Z","updated_at":"2026-04-06T05:03:41.306Z","avatar_url":"https://github.com/johnnymillergh.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Python Boilerplate Social Image](./python_boilerplate.png)\n[![GitHub release](https://img.shields.io/github/release/johnnymillergh/python_boilerplate.svg)](https://github.com/johnnymillergh/python_boilerplate/releases)\n[![Github Actions workflow status](https://github.com/johnnymillergh/python_boilerplate/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/johnnymillergh/python_boilerplate/actions)\n[![GitHub issues](https://img.shields.io/github/issues/johnnymillergh/python_boilerplate)](https://github.com/johnnymillergh/python_boilerplate/issues)\n[![GitHub forks](https://img.shields.io/github/forks/johnnymillergh/python_boilerplate)](https://github.com/johnnymillergh/python_boilerplate/network)\n[![GitHub stars](https://img.shields.io/github/stars/johnnymillergh/python_boilerplate)](https://github.com/johnnymillergh/python_boilerplate)\n[![GitHub license](https://img.shields.io/github/license/johnnymillergh/python_boilerplate)](https://github.com/johnnymillergh/python_boilerplate/blob/master/LICENSE)\n[![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/johnnymillergh/python_boilerplate.svg?style=popout)](https://github.com/johnnymillergh/python_boilerplate)\n[![GitHub repo size](https://img.shields.io/github/repo-size/johnnymillergh/python_boilerplate.svg)](https://github.com/johnnymillergh/python_boilerplate)\n[![Twitter](https://img.shields.io/twitter/url/https/github.com/johnnymillergh/python_boilerplate?style=social)](https://twitter.com/intent/tweet?text=Wow:\u0026url=https%3A%2F%2Fgithub.com%2Fjohnnymillergh%2Fpython_boilerplate)\n\n# Python Boilerplate\n\n**python_boilerplate** is a boilerplate project for Python. Based on template [sourcery-ai/python-best-practices-cookiecutter](https://github.com/sourcery-ai/python-best-practices-cookiecutter).\n\n[Official Docker Image](https://github.com/johnnymillergh/python_boilerplate/pkgs/container/python_boilerplate%2Fpython_boilerplate)\n\n## Features\n\nHere are the highlights of **python_boilerplate**:\n\n1. Inherited from modern and the latest Python technologies:\n\n   `Python` - [![Python](https://img.shields.io/badge/Python-v3.13-blue)](https://www.python.org/downloads/)\n\n   `uv` is a fast Python package installer and dependency management tool for the project.\n\n\n2. Data validation using Python type hints with [Pydantic](https://github.com/pydantic/pydantic).\n\n3. Highly customizable data analysis with [pandas](https://pandas.pydata.org/), enhanced array operation with [NumPy](https://numpy.org/). Supports CSV, Excel, JSON, and so on.\n\n4. Data persistence with [peewee](http://docs.peewee-orm.com/en/latest/), [SQLite3](https://sqlite.org/index.html) as a local database.\n\n5. Simple and flexible retry with [Tenacity](https://github.com/jd/tenacity).\n\n6. Environment variable and configuration with [pyhocon](https://pythonhosted.org/pyhocon/_modules/pyhocon.html). Read `${ENVIRONMENT_VARIABLE}` when startup.\n\n7. Sensible and human-friendly approach to creating, manipulating, formatting and converting dates, times, and timestamps with [Arrow](https://pypi.org/project/arrow/).\n\n8. Generate fake data with [Faker](https://pypi.org/project/Faker/).\n\n9. Customized function decorator `@async_function` to enable function to run asynchronously; `@peewee_table` class decorator to register ORM tables; `@elapsed_time(level=\"INFO\")` to profile a function elapsed time.\n\n10. Testing with [pytest](https://docs.pytest.org/en/latest/), integrating [pytest-mock](https://pypi.org/project/pytest-mock/) for mocking, [pytest-cov](https://pypi.org/project/pytest-cov/) for code coverage analysis and [pyinstrument](https://github.com/joerick/pyinstrument) for Python stack profiler.\n\n11. Linting, formatting, and import sorting with [Ruff](https://docs.astral.sh/ruff/).\n\n12. Static typing with [mypy](http://mypy-lang.org/).\n\n13. Git hooks that run all the above with [pre-commit](https://pre-commit.com/).\n\n14. Deployment ready with [Docker](https://docker.com/).\n\n15. Continuous Integration with [GitHub Actions](https://github.com/features/actions).\n\n16. Loguru logging configuration. The log sample,\n\n   ```\n   2022-09-17 14:13:52.385 | ⚠️ WARNING  | 6860 | MainThread      | python_boilerplate.repository.model.base_model.\u003cmodule\u003e:24 - SQLite database created. Path: [/Users/johnny/Projects/PyCharmProjects/python_boilerplate/data/python_boilerplate.db], \u003cpeewee.SqliteDatabase object at 0x1191e1390\u003e\n   2022-09-17 14:13:52.386 | ℹ️ INFO     | 6860 | MainThread      | python_boilerplate.common.orm.peewee_table:16 - Registering peewee table: StartupLog\n   2022-09-17 14:13:52.387 | 🐞 DEBUG    | 6860 | MainThread      | peewee.execute_sql:3185 - ('CREATE TABLE IF NOT EXISTS \"startup_log\" (\"id\" INTEGER NOT NULL PRIMARY KEY, \"current_user\" VARCHAR(50) NOT NULL, \"host\" VARCHAR(50) NOT NULL, \"command_line\" TEXT NOT NULL, \"current_working_directory\" TEXT NOT NULL, \"startup_time\" DATETIME NOT NULL, \"created_by\" VARCHAR(50) NOT NULL, \"created_time\" DATETIME NOT NULL, \"modified_by\" VARCHAR(50) NOT NULL, \"modified_time\" DATETIME NOT NULL)', [])\n   2022-09-17 14:13:52.530 | ℹ️ INFO     | 6860 | MainThread      | python_boilerplate.\u003cmodule\u003e:53 - Started python_boilerplate in 0.117 seconds (117.26 ms)\n   ```\n\n## Usage\n\n1. Clone or download this project.\n\n   ```shell\n   $ git clone https://github.com/johnnymillergh/python_boilerplater.git\n   ```\n\n2. Build with the newest PyCharm.\n\n3. Click the green triangle to Run.\n\n## Setup\n\n1. Setup the development environment\n\n   ```shell\n   # Install uv\n   $ curl -LsSf https://astral.sh/uv/install.sh | sh\n\n   # For Windows PowerShell\n   $ powershell -ExecutionPolicy ByPass -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n   # Or use winget\n   $ winget install --id=astral-sh.uv\n   ```\n\n2. Install dependencies, with optional dependency group `test`\n\n   ```shell\n   $ uv sync --extra test --extra dev\n   ```\n\n3. Install mypy types\n\n   ```shell\n   $ uv run mypy --install-types\n   ```\n\n4. Setup pre-commit and pre-push hooks\n\n   ```shell\n   $ uv run pre-commit install -t pre-commit\n   $ uv run pre-commit install -t pre-push\n   ```\n\n## Useful Commands\n\n### Run Python Module\n\n```shell\n$ uv run python -m python_boilerplate\n```\n\n### Run Python Script\n\n**Append your project's root directory to** `PYTHONPATH` — In any environment you wish to run your Python application such as Docker, vagrant or your virtual environment i.e. in bin/activate, run the below command:\n\n\u003e [How to Fix ModuleNotFoundError and ImportError](https://towardsdatascience.com/how-to-fix-modulenotfounderror-and-importerror-248ce5b69b1c)\n\nFor macOS or Linux,\n\n```shell\n# Ensure `pwd` is the root directory of the project\n$ PYTHONPATH=`pwd` uv run python3 python_boilerplate/demo/pandas_usage.py\n$ PYTHONPATH=`pwd` uv run python3 python_boilerplate/demo/multithread_and_thread_pool_usage.py\n\n# Run the main module\n$ PYTHONPATH=`pwd` uv run python3 python_boilerplate/__main__.py\n\n# Run a pytest script\n$ pytest --log-cli-level=DEBUG --capture=no tests/common/test_debounce_throttle.py\n\n# Run a pytest script with `-k` EXPRESSION\n$ pytest --log-cli-level=DEBUG --capture=no tests/common/test_debounce_throttle.py -k 'test_debounce'\n\n# For more details of pytest command\n$ uv run pytest --help\n```\n\nFor Windows Terminal,\n```powershell\n# Ensure `$PWD.Path` is the root directory of the project\n$ $env:PYTHONPATH=$PWD.Path; uv run python .\\python_boilerplate\\demo\\pandas_usage.py\n$ $env:PYTHONPATH=$PWD.Path; uv run python .\\python_boilerplate\\demo\\multithread_and_thread_pool_usage.py\n\n# Run the main module\n$ $env:PYTHONPATH=$PWD.Path; uv run python .\\python_boilerplate\\__main__.py\n```\n\n### Package with [PyInstaller](https://pyinstaller.org/en/latest/usage.html?highlight=pythonpath#using-pyinstaller)\n\n\u003e **⚠️ WANRING**\n\u003e\n\u003e Need to call `freeze_support()` immediately when startup in `python_boilerplate/__init__.py`\n\u003e\n\u003e ```python\n\u003e from multiprocessing import freeze_support\n\u003e\n\u003e freeze_support()\n\u003e ```\n\u003e\n\u003e - [Pyinstaller multiprocessing name of process is always \"MainProcess\" #3957](https://github.com/pyinstaller/pyinstaller/issues/3957#issuecomment-674579877)\n\u003e - [pyinstaller linux binary is getting restarted again and again #4190](https://github.com/pyinstaller/pyinstaller/issues/4190)\n\nBuild artifact with macOS or Linux,\n```shell\n$ uv run pyinstaller --console \\\n--add-data \"pyproject.toml:.\" \\\n--add-data \"src/python_boilerplate/resources/*:python_boilerplate/resources\" \\\n--name pandas_usage \\\n--clean --noconfirm src/python_boilerplate/demo/pandas_usage.py\n```\n\nOn Windows,\n```powershell\n$ uv run pyinstaller --console `\n--add-data \"pyproject.toml;.\" `\n--add-data \"src/python_boilerplate/resources/*;python_boilerplate/resources\" `\n--name multithread_and_thread_pool_usage `\n--clean --noconfirm src/python_boilerplate/demo/multithread_and_thread_pool_usage.py\n```\n\n### Run Unit Tests\n\nRun with pytest, analyze code coverage, generate HTML code coverage reports, fail the test if coverage percentage is under 90%,\n\n```shell\n$ uv run pytest --cov --cov-report html --cov-fail-under=85 --capture=no --log-cli-level=INFO\n```\n\nBenchmark with pytest,\n\n```shell\n$ uv run pytest --capture=no --log-cli-level=ERROR -n 0 --benchmark-only\n```\n\n### Conventional Changelog CLI\n\n1. Install global dependencies (optional if installed):\n\n   ```shell\n   $ npm install -g conventional-changelog-cli\n   ```\n\n2. This will *not* overwrite any previous changelogs. The above generates a changelog based on commits since the last semver tag that matches the pattern of \"Feature\", \"Fix\", \"Performance Improvement\" or \"Breaking Changes\".\n\n   ```shell\n   $ conventional-changelog -p angular -i CHANGELOG.md -s\n   ```\n\n3. If this is your first time using this tool and you want to generate all previous changelogs, you could do:\n\n   ```shell\n   $ conventional-changelog -p angular -i CHANGELOG.md -s -r 0\n   ```\n\n### Check Versions of Python Packages\n\n```shell\n$ uv pip list --outdated\n```\n\nOutput be like,\n\n```\nPackage          Version   Latest     Type\n---------------- --------- ---------- -----\nblack            23.10.1   23.11.0    wheel\ncertifi          2023.7.22 2023.11.17 wheel\nFaker            19.12.0   20.1.0     wheel\nidentify         2.5.31    2.5.32     wheel\nidna             3.4       3.6        wheel\nmatplotlib       3.8.0     3.8.2      wheel\nmypy             1.6.1     1.7.1      wheel\nnumpy            1.26.1    1.26.2     wheel\npandas           2.1.2     2.1.3      wheel\npip              23.1.2    23.3.1     wheel\nplatformdirs     3.11.0    4.0.0      wheel\npydantic         2.4.2     2.5.2      wheel\npydantic_core    2.10.1    2.14.5     wheel\npyinstaller      6.1.0     6.2.0      wheel\npyinstrument     4.6.0     4.6.1      wheel\npytest-html      4.0.2     4.1.1      wheel\npytest-xdist     3.3.1     3.5.0      wheel\nsetuptools       68.2.2    69.0.2     wheel\ntypes-setuptools 68.2.0.0  69.0.0.0   wheel\nurllib3          2.0.7     2.1.0      wheel\nvirtualenv       20.24.6   20.24.7    wheel\nwheel            0.41.3    0.42.0     wheel\n```\n\n## CI (Continuous Integration)\n\n- GitHub Actions are for building projects and running tests.\n- ~~[Travis CI](https://travis-ci.com/github/johnnymillergh/) is for publishing Docker Hub images of SNAPSHOT and RELEASE.~~\n\n## FAQ\n\n1. [ExecutableNotFoundError: Executable `/bin/bash` not found when using pre-commit](https://stackoverflow.com/questions/72321412/bin-bash-not-found-when-using-pre-commit)\n\n   **Solution**: delete `.git/hooks/pre-commit.legacy` and then reinstall, also deleted `.git/hooks/pre-commit` just to be sure before installing again.\n\n2. Installing all stub type packages,\n\n   ```shell\n   $ mypy --install-types\n   ```\n\n## Maintainers\n\n[@johnnymillergh](https://github.com/johnnymillergh).\n\n## Contributing\n\nFeel free to dive in! [Open an issue](https://github.com/johnnymillergh/python_boilerplate/issues/new).\n\n### Contributors\n\nThis project exists thanks to all the people who contribute.\n\n- Johnny Miller [[@johnnymillergh](https://github.com/johnnymillergh)]\n- …\n\n\n### Sponsors\n\nSupport this project by becoming a sponsor. Your logo will show up here with a link to your website. [[Become a sponsor](https://become-a-sponsor.org)]\n\n## Credits\n\nThis package was created with Cookiecutter and the [sourcery-ai/python-best-practices-cookiecutter](https://github.com/sourcery-ai/python-best-practices-cookiecutter) project template.\n\nInspired by [How to set up a perfect Python project](https://sourcery.ai/blog/python-best-practices/).\n\n## License\n\n[Apache License](https://github.com/johnnymillergh/python_boilerplate/blob/main/LICENSE) © Johnny Miller\n\n2021—Present\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnnymillergh%2Fpython-boilerplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjohnnymillergh%2Fpython-boilerplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnnymillergh%2Fpython-boilerplate/lists"}