| 
1 |  | -# bootstrap-python-package  | 
2 |  | -  | 
3 |  | -[](https://pypi.org/project/bootstrap-python-package/)  | 
4 |  | -[](https://github.com/mkenney/software-guides/blob/master/STABILITY-BADGES.md#beta)  | 
5 |  | - | 
6 |  | -[](https://github.com/febus982/bootstrap-python-package/actions/workflows/python-tests.yml)  | 
7 |  | -[](https://codeclimate.com/github/febus982/bootstrap-python-package/maintainability)  | 
8 |  | -[](https://codeclimate.com/github/febus982/bootstrap-python-package/test_coverage)  | 
9 |  | - | 
10 |  | -[](https://mypy-lang.org/)  | 
11 |  | -[](https://github.com/charliermarsh/ruff)  | 
12 |  | -[](https://github.com/psf/black)  | 
13 |  | -[](https://github.com/PyCQA/bandit)  | 
14 |  | - | 
15 |  | -This template repository provides the boilerplate to create a python package.  | 
16 |  | -It is configured with all the following features:  | 
17 |  | - | 
18 |  | -* Test suite using [tox](https://tox.wiki/en/latest/index.html) and [pytest](https://docs.pytest.org/en/7.4.x/)  | 
19 |  | -* Typing using [mypy](https://mypy.readthedocs.io/en/stable/)  | 
20 |  | -* Linting, security and code format using [ruff](https://github.com/astral-sh/ruff) (using [black](https://pypi.org/project/black/)  | 
21 |  | -  code style and [bandit](https://github.com/PyCQA/bandit) security rules)  | 
22 |  | -* Integration with CodeClimate for code quality and coverage checks  | 
23 |  | -* CI pipeline supporting:  | 
24 |  | -    * testing against multiple python versions  | 
25 |  | -    * releases on [PyPI](https://pypi.org)  | 
26 |  | -    * GitHub pages documentation using [mkdocs](https://www.mkdocs.org)  | 
27 |  | -* PyCharm profile basic configuration  | 
28 |  | - | 
29 |  | -## How to use this repository template to create a new package  | 
30 |  | - | 
31 |  | -* Create your github repository using this template. (The big green `Use this template` button)  | 
32 |  | -* Rename the `bootstrap_python_package` directory  | 
33 |  | -* Search and replace all the occurrences of `bootstrap-python-package` and `bootstrap_python_package`  | 
34 |  | -* Configure a pending trusted publisher on [pypi](https://pypi.org/manage/account/publishing) using the following values:  | 
35 |  | -    * PyPI Project Name: The github repository name (in this case `bootstrap-python-package`)  | 
36 |  | -    * Owner: The github repository owner (in this case `febus982`)  | 
37 |  | -    * Repository name: The github repository name (in this case `bootstrap-python-package`)  | 
38 |  | -    * Workflow name: `release.yml`  | 
39 |  | -* Create a GitHub Actions secret named `CODECLIMATE_REPORTER_ID` (at URL `https://github.com/GITHUB_NAME_OR_ORGANIZATION/GITHUB_REPOSITORY/settings/secrets/actions`)  | 
40 |  | -  containing the codeclimate reporter id (you can find it at `https://codeclimate.com/repos/YOUR_REPO_ID/settings/test_reporter`).  | 
41 |  | -  If you don't want to use CodeClimate just delete `workflows/python-quality.yml`.  | 
42 |  | -* Update the badges in `README.md`! (check [shields.io](https://shields.io/) for extra badges)  | 
43 |  | -* Update the PyCharm Copyright profile in the IDE settings: Editor | Copyright | Copyright Profiles (if you want to use it)  | 
44 |  | -* Setup local development:  | 
45 |  | -    * Clone the repository  | 
46 |  | -    * Install poetry `pip install poetry`  | 
47 |  | -    * Install dev dependencies with `make dev-dependencies`  | 
48 |  | -    * (optional) It is strongly recommended to install [pre-commit](https://pre-commit.com/#installation)  | 
49 |  | -      and run `pre-commit install` so that formatting and linting are automatically executed during `git commit`.  | 
50 |  | -* Setup GitHub pages (this need local development setup):  | 
51 |  | -    * Initialise documentation branch `poetry run mike deploy dev latest --update-aliases --push`  | 
52 |  | -    * Configure GitHub Pages to deploy from the `gh-pages` branch (at URL `https://github.com/GITHUB_NAME_OR_ORGANIZATION/GITHUB_REPOSITORY/settings/pages`)  | 
53 |  | -    * Add the `main` branch and the `v*.*.*` tag rules to the "deployment branches and tags" list in the `gh-pages` environment (at URL `https://github.com/GITHUB_NAME_OR_ORGANIZATION/GITHUB_REPOSITORY/settings/environments`)  | 
54 |  | - | 
55 |  | -**IMPORTANT:** The repository is configured to deploy on the [test PyPI repository](https://test.pypi.org/).  | 
56 |  | -It's strongly recommended to create the project in the [test PyPI repository](https://test.pypi.org/) and test  | 
57 |  | -the deployment pipeline. When you're happy with the result, create the project on the official [PyPI repository](https://pypi.org/)  | 
58 |  | -and remove the marked lines in `workflows/release.yml`.  | 
59 |  | - | 
60 |  | -## Package release  | 
61 |  | - | 
62 |  | -This setup uses [poetry-dynamic-versioning](https://github.com/mtkennerly/poetry-dynamic-versioning).  | 
63 |  | -This means it's not necessary to commit the version in the code but the CI pipeline  | 
64 |  | -will infer it from the git tag.  | 
65 |  | - | 
66 |  | -To release a new version, just create a new release and tag in the GitHub repository, to:  | 
67 |  | - | 
68 |  | -* Build and deploy the python package to PyPI  | 
69 |  | -* Build and deploy a new version of the documentation to GitHub pages  | 
70 |  | - | 
71 |  | -**IMPORTANT:** The default configuration requires the release name and the tag to follow  | 
72 |  | -the convention `vX.X.X` (semantic versioning preceded by lowercase `v`). It will publish  | 
73 |  | -the correct version on Pypi, omitting the `v` (ie. `v1.0.0` will publish `1.0.0`).  | 
74 |  | - | 
75 |  | -This format can be customized, refer to [poetry-dynamic-versioning docs](https://github.com/mtkennerly/poetry-dynamic-versioning)  | 
76 |  | - | 
77 |  | -## Commands for development  | 
78 |  | - | 
79 |  | -All the common commands used during development can be run using make targets:  | 
80 |  | - | 
81 |  | -* `make dev-dependencies`: Install dev requirements  | 
82 |  | -* `make update-dependencies`: Update dev requirements  | 
83 |  | -* `make fix`: Run code style and lint automatic fixes (where possible)  | 
84 |  | -* `make test`: Run test suite against system python version  | 
85 |  | -* `make check`: Run tests against all available python versions, code style and lint checks  | 
86 |  | -* `make type`, `make format`, `make lint`, `make bandit`: Run the relevant check  | 
87 |  | -* `make docs`: Render the mkdocs website locally  | 
 | 1 | +--8<-- "./README.md"  | 
0 commit comments