|
@@ -0,0 +1,73 @@
|
|
|
+# python3-boilerplate ![CI](https://github.com/BastiTee/python3-boilerplate/workflows/CI/badge.svg)
|
|
|
+
|
|
|
+> A best-practices template project for Python3 modules
|
|
|
+
|
|
|
+--------------------------------------------------------------------------------
|
|
|
+
|
|
|
+**Disclaimer**: If you see this on [pypi.org](https://pypi.org/project/python3-boilerplate/) please note that the project is only published here for testing purposes. Please visit [GitHub](https://github.com/BastiTee/python3-boilerplate) for the related template project.
|
|
|
+
|
|
|
+--------------------------------------------------------------------------------
|
|
|
+
|
|
|
+## Setup
|
|
|
+
|
|
|
+- Make sure that `python3` and `pip3` is installed and available on the path (on Ubuntu: `sudo apt-get install python3 python3-pip`)
|
|
|
+- On first checkout run `make venv` to initialize the project configuration
|
|
|
+- Refer to [the Makefile](Makefile) to learn about the various operations available
|
|
|
+- To rename the project you can use [the provided script](__rename__.sh)
|
|
|
+
|
|
|
+## Features
|
|
|
+
|
|
|
+- Basic project/module organization according to <https://packaging.python.org>
|
|
|
+- `Makefile` management script
|
|
|
+- [pipenv](https://github.com/pypa/pipenv) and virtual environments
|
|
|
+- [distutils](https://docs.python.org/3/library/distutils.html)-based installer script
|
|
|
+- Unit testing with [pytest](https://docs.pytest.org/en/latest/)
|
|
|
+- Multicore/-interpreter testing with [tox](https://tox.readthedocs.io/en/latest/)
|
|
|
+- Linting ([flake8](http://flake8.pycqa.org)) and code formatting ([autopep8](https://github.com/hhatto/autopep8)) support
|
|
|
+- [isort](https://pypi.org/project/isort/) support for automated import sorting
|
|
|
+- [mpyp](https://pypi.org/project/mypy/) support for type checking
|
|
|
+- Publishing to PyPi.org at <https://pypi.org/project/python3-boilerplate/>
|
|
|
+- [vscode](https://code.visualstudio.com/) editor configuration including plugin recommendations, debugging support, unit test discovery and on-save formatting
|
|
|
+- [Github actions](https://github.com/BastiTee/python3-boilerplate/actions) continuous integration
|
|
|
+
|
|
|
+## How to use in existing project
|
|
|
+
|
|
|
+To use it in an existing project you can merge the remote changes to your project.
|
|
|
+
|
|
|
+- Add remote to access the template project
|
|
|
+
|
|
|
+```shell
|
|
|
+git remote add py3template git@github.com:BastiTee/python3-boilerplate.git
|
|
|
+git pull py3template master --allow-unrelated-histories
|
|
|
+```
|
|
|
+
|
|
|
+- Solve all merge conflicts and commit. Most likely there will be a lot
|
|
|
+- Do whatever is necessary to remove the boilerplate you don't need, e.g.
|
|
|
+
|
|
|
+```shell
|
|
|
+rm -rf my_module tests/test_utils.py __rename__.sh
|
|
|
+```
|
|
|
+
|
|
|
+- Commit your changes and push to your project
|
|
|
+
|
|
|
+## Resources
|
|
|
+
|
|
|
+- <http://packaging.python.org/>
|
|
|
+- <https://packaging.python.org/en/latest/distributing.html>
|
|
|
+- <https://pypi.org/>
|
|
|
+- <https://github.com/pypa/sampleproject>
|
|
|
+- <https://www.python.org/dev/peps/>
|
|
|
+- <https://www.python.org/dev/peps/pep-0008/>
|
|
|
+- <https://www.kennethreitz.org/essays/why-you-should-use-vs-code-if-youre-a-python-developer>
|
|
|
+- <https://code.visualstudio.com/docs/python/python-tutorial>
|
|
|
+
|
|
|
+## Future ideas and todos
|
|
|
+
|
|
|
+- Optional static type hints ([PEP 484](https://www.python.org/dev/peps/pep-0484/)) with [mypy](https://github.com/python/mypy)
|
|
|
+- Make sure [tox](https://tox.readthedocs.io/) is working as expected for supported Python versions
|
|
|
+- Introduce [black](https://github.com/psf/black) in favour of other linters
|
|
|
+- Introduce [pyproject.toml](https://www.python.org/dev/peps/pep-0518/) along with bleeding edge build tools like [flit](https://flit.readthedocs.io/en/latest/rationale.html) or [poetry](https://python-poetry.org/)
|
|
|
+
|
|
|
+## Licensing
|
|
|
+
|
|
|
+This project is licensed under [Apache License 2.0](LICENSE.txt).
|