README.md 7.38 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
pygeoapi-plugin-cookiecutter
============================

Cookiecutter project for creating new pygeoapi-plugins.

Prerequisites
-------------

-   This project obviously requires
    [Cookiecutter](https://github.com/audreyr/cookiecutter) to be
    installed in order to be used.
-   The project that is created requires the use of
13
    [Conda](https://www.anaconda.com), and will expect that tool to be
14
    available.
15
16
-   The project that is created also needs to have conda-build set up and running in order
    to build the project and deploy it to conda.
17
18
19
20
21
-   The project that is created also uses [poetry](https://python-poetry.org) for dependency management.
    To install poetry, use the following:
    ``` {.sourceCode .console}
    $ curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python -
    ```
22
23
-   Other than the use of [conda](https://www.anaconda.com), this follows the patterns
    defined in [Hypermodern
24
25
26
27
28
29
    Python](https://medium.com/@cjolowicz/hypermodern-python-d44485d9d769).

Usage
-----

``` {.sourceCode .console}
30
$ cookiecutter https://code.usgs.gov/wma/nhgf/pygeoapi-plugin-cookiecutter.git
31
32
33
34
35
```

Setup
-----

36
Initial setup for the development environment is:
37
38

``` {.sourceCode .console}
39
40
41
$ conda env create -f environment.yml
$ conda activate {{cookiecutter.project_name}}
$ poetry install
42
43
```

44
45
46
47
48
49
50
51
52
If this is a new git repository that needs to be initialized:

``` {.sourceCode .console}
$ git init
```

### Git hook configuration

It is important to get [pre-commit](https://pre-commit.com/) enabled on
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
the project, to ensure that certain standards are always met on a git
commit. With several of these, it might fail if files are changed, but
it will change them, and trying the commit a second time will actually
work.

``` {.sourceCode .console}
$ pre-commit install --install-hooks
```

### Testing

[Nox](https://nox.thea.codes/) is used for testing everything, with
several sessions built-in. To run the full suite of tests, simply use:

``` {.sourceCode .console}
$ nox
```

The different sessions are:

-   `pre-commit` -- validates that the
74
    [pre-commit](https://pre-commit.com/) checks all come back clean.
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
103
104
105
106
107
108
109
-   `safety` -- validates the [Safety](https://github.com/pyupio/safety)
    of all production dependencies.
-   `mypy` -- validates the type-hints for the application using
    [mypy](http://mypy-lang.org/).
-   `tests` -- runs all [pytest](https://docs.pytest.org/en/latest/)
    tests.
-   `typeguard` -- runs all [pytest](https://docs.pytest.org/en/latest/)
    tests, validates with
    [Typeguard](https://github.com/agronholm/typeguard).
-   `xdoctest` -- runs any and all documentation examples with
    [xdoctest](https://github.com/Erotemic/xdoctest).
-   `docs-build` -- builds the full set of generated API docs with
    [Sphinx](http://www.sphinx-doc.org/).

These can be run individually with the following command:

``` {.sourceCode .console}
$ nox -s <session>
```

Replace `<session>` with the name of the session give above, i.e.:

``` {.sourceCode .console}
$ nox -s mypy
```

You can also simply run [pytest](https://docs.pytest.org/en/latest/)
tests, by using the command:

``` {.sourceCode .console}
$ pytest tests
```

### Dependencies

110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
[Poetry](https://python-poetry.org) is used for all dependency management,
and is the single source of truth for python dependencies. Adding a new
dependency is as simple as:

``` {.sourceCode .console}
$ poetry add <dependency>
```

where you replace `<dependency>` with the name of the library to add.
[Poetry](https://python-poetry.org) also has a concept of "development
dependencies", which are added to a development environment, but are not
to be included when the project is built and released. Adding a development
dependency is as simple as:

``` {.sourceCode .console}
$ poetry add --dev <dependency>
```

The [Conda](https://www.anaconda.com) environment for the project can then
be updated with the latest dependencies (not needed for development dependencies)
by simply running the following command in the root project directory:

``` {.sourceCode .console}
$ poetry2conda pypproject.toml environment.yaml
```
135
136
137
138
139
140

### Version Management

Warning:
:   Do not set the initial version to `0.0.0`. This will break, due to
    an unknown bug in
141
    [Advbumpversion](https://github.com/andrivet/advbumpversion) at this
142
143
144
    time.

The projects made by this cookiecutter use
145
[Advbumpversion](https://github.com/andrivet/advbumpversion) for version
146
147
148
management. The default version that the project starts with is `0.0.1`.
In github, this should be auto-incremented on each commit to the next
dev build number. To manage the version changes yourself, you can use the
149
[Advbumpversion](https://github.com/andrivet/advbumpversion) command:
150
151

``` {.sourceCode .console}
152
$ bumpversion <part>
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
```

Where `<part>` is one of:

-   `major`
-   `minor`
-   `patch`
-   `build`

Note:
:   This makes a `dev` version, which does not write a tag into git. It
    is just useful for development purposes and not the version that is
    recommended for a release version. The version string will be
    formatted as: `<major>.<minor>.<patch>-dev<build>`

To do a production release, use the command:

``` {.sourceCode .console}
171
$ bumpversion --tag release
172
173
174
175
176
177
178
179
180
181
182
```

This will add a tag in the git repository noting the version.

Note:
:   The version string for this will be: `<major>.<minor>.<patch>`

Features
--------

-   Packaging and dependency management with
183
184
    [poetry](https://python-poetry.org)
-   Environment configuration with [conda](https://www.anaconda.com)
185
-   Test automation with [Nox](https://nox.thea.codes/)
186
-   Linting with [pre-commit](https://pre-commit.com/) and
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
    [Flake8](http://flake8.pycqa.org)
-   Continuous integration with [GitHub
    Actions](https://github.com/features/actions) or
    [Travis-CI](https://travis-ci.com)
-   Documentation with [Sphinx](http://www.sphinx-doc.org/) and [Read
    the Docs](https://readthedocs.org/)
-   Automated uploads to [PyPI](https://pypi.org/) and
    [TestPyPI](https://test.pypi.org/)
-   Automated release notes with [Release
    Drafter](https://github.com/release-drafter/release-drafter)
-   Automated dependency updates with
    [Dependabot](https://dependabot.com/)
-   Code formatting with [Black](https://github.com/psf/black) and
    [Prettier](https://prettier.io/)
-   Testing with [pytest](https://docs.pytest.org/en/latest/)
-   Code coverage with [Coverageppy](https://coverage.readthedocs.io/)
-   Coverage reporting with [Codecov](https://codecov.io/)
-   Command-line interface with
    [Click](https://click.palletsprojects.com/)
-   Static type-checking with [mypy](http://mypy-lang.org/)
-   Runtime type-checking with
    [Typeguard](https://github.com/agronholm/typeguard)
-   Security audit with [Bandit](https://github.com/PyCQA/bandit) and
    [Safety](https://github.com/pyupio/safety)
-   Check documentation examples with
    [xdoctest](https://github.com/Erotemic/xdoctest)
-   Generate API documentation with
    [autodoc](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html)
    and
    [napoleon](https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html)
-   Generate command-line reference with
    [sphinxcclick](https://sphinx-click.readthedocs.io/)
-   Manage project labels with [GitHub
    Labeler](https://github.com/marketplace/actions/github-labeler)
-   Manage project versions with
222
    [Advbumpversion](https://github.com/c4urself/advbumpversion)
223

224
The template supports Python 3.9.