1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
|
# Developing guidelines
If you already cloned the repository and you know that you need to deep dive in the code,
here are some guidelines to set up your environment.
## Development environment setup
### Python versions
To manage multiple Python versions on my system, I use [`pyenv`].
See the `pyenv` documentation on how to install and configure the tool.
Install the supported python versions and enable them for this project:
```shell
$ for v in 3.6 3.7 3.8 3.9 3.10; do pyenv install "${v}:latest"; done
$ pyenv versions --bare | xargs pyenv local
```
### Dependencies
This project uses [`poetry`] to manage dependencies and virtual environments.
See `poetry`'s [installation instructions] on how to install `poetry` on your system.
I have opted to use [`pipx`] to install and manage `poerty` itself.
I also use `pipx` to manage other python executables that I want readily available on my system.
Once `poetry` is available on your system, install the development dependencies:
```shell
$ poetry install --with dev,test,coverage,docs --sync
```
A virtual environment will be created automatically by `poetry`.
To enter a shell with the virtual environment loaded use the `shell` command:
```shell
$ poetry shell
```
Note that `poetry` doesn't need you to load the virtual environment.
It will automatically load the virtual environment as you interact with the `poetry` commands.
## Running Tests
The tests are written with the [`pytest`] test framework.
To run the tests invoke `pytest` through `poetry`:
```shell
$ poetry run pytest
```
However, the above will only run the tests for the latest python version.
To test all python versions invoke the test runner [`tox`]:
```shell
$ poetry run tox
```
This works because different python versions were made available through `pyenv`.
## Coding Rules
Coding style is encoded through the configurations of [`black`] and [`isort`].
To enforce the rules run:
```shell
$ poetry run black src/ tests/ example/
$ poetry run isort src/ tests/ example/
```
Additional rules and suggestions are generated by [`flake8`].
Check your code with:
```shell
$ poetry run flake8 src/
```
## Commit Message Guidelines
(TODO)
## Writing Documentation
(TODO)
[`poetry`]: https://python-poetry.org/
[installation instructions]: https://python-poetry.org/docs/#installation
[`pipx`]: https://pypa.github.io/pipx/
[`pyenv`]: https://github.com/pyenv/pyenv
[`pytest`]: https://docs.pytest.org/
[`tox`]: https://tox.wiki/
[`black`]: https://black.readthedocs.io/
[`isort`]: https://pycqa.github.io/isort/
[`flake8`]: https://flake8.pycqa.org/
|
