pygeoapi-yaml 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- pygeoapi_yaml-0.1.0/CONTRIBUTING.md +45 -0
- pygeoapi_yaml-0.1.0/LICENSE +21 -0
- pygeoapi_yaml-0.1.0/MANIFEST.in +3 -0
- pygeoapi_yaml-0.1.0/PKG-INFO +263 -0
- pygeoapi_yaml-0.1.0/README.md +233 -0
- pygeoapi_yaml-0.1.0/pygeoapi_yaml/__init__.py +30 -0
- pygeoapi_yaml-0.1.0/pygeoapi_yaml/provider.py +729 -0
- pygeoapi_yaml-0.1.0/pygeoapi_yaml.egg-info/PKG-INFO +263 -0
- pygeoapi_yaml-0.1.0/pygeoapi_yaml.egg-info/SOURCES.txt +18 -0
- pygeoapi_yaml-0.1.0/pygeoapi_yaml.egg-info/dependency_links.txt +1 -0
- pygeoapi_yaml-0.1.0/pygeoapi_yaml.egg-info/requires.txt +8 -0
- pygeoapi_yaml-0.1.0/pygeoapi_yaml.egg-info/top_level.txt +1 -0
- pygeoapi_yaml-0.1.0/pyproject.toml +47 -0
- pygeoapi_yaml-0.1.0/setup.cfg +4 -0
- pygeoapi_yaml-0.1.0/tests/__init__.py +28 -0
- pygeoapi_yaml-0.1.0/tests/data/empty.yaml +1 -0
- pygeoapi_yaml-0.1.0/tests/data/observations.yaml +22 -0
- pygeoapi_yaml-0.1.0/tests/data/pygeoapi-test-config.yml +89 -0
- pygeoapi_yaml-0.1.0/tests/test_api.py +183 -0
- pygeoapi_yaml-0.1.0/tests/test_yaml_provider.py +549 -0
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
# Contributing to pygeoapi-yaml
|
|
2
|
+
|
|
3
|
+
Thank you for your interest. Issues and pull requests are welcome.
|
|
4
|
+
|
|
5
|
+
## Before a pull request
|
|
6
|
+
|
|
7
|
+
For anything beyond a small fix, please open an issue first, so that we can agree
|
|
8
|
+
on the change before you write it.
|
|
9
|
+
|
|
10
|
+
## What a change needs
|
|
11
|
+
|
|
12
|
+
- **A test for each behaviour.** A test should fail when the behaviour it covers
|
|
13
|
+
is removed. Please check this: break the code on purpose, and see the test
|
|
14
|
+
fail. Tests that go through pygeoapi itself (`tests/test_api.py`) are welcome
|
|
15
|
+
when a change touches what pygeoapi sees.
|
|
16
|
+
- **pygeoapi's style.** The provider follows `pygeoapi/provider/geojson.py` and
|
|
17
|
+
`csv_.py`: the same structure, `:param:`/`:returns:` docstrings, the MIT file
|
|
18
|
+
header, the exceptions of `pygeoapi.provider.base`. flake8 must pass.
|
|
19
|
+
- **Passing checks.** Run them before you push:
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
.venv/bin/pytest
|
|
23
|
+
.venv/bin/flake8 pygeoapi_yaml tests
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
- **One coherent change per commit**, with a message that says why.
|
|
27
|
+
|
|
28
|
+
## AI-assisted contributions
|
|
29
|
+
|
|
30
|
+
They are welcome. This project is itself written mostly by an AI (see
|
|
31
|
+
[Authorship](README.md#authorship)). Two things are asked:
|
|
32
|
+
|
|
33
|
+
- **Say so.** Add a `Co-Authored-By:` trailer to the commit, or a line in the
|
|
34
|
+
pull request.
|
|
35
|
+
- **Stand behind it.** You have run the tests yourself, and you can explain what
|
|
36
|
+
the change does and why. The bar is the same as for any other change.
|
|
37
|
+
|
|
38
|
+
Note that pygeoapi itself has its own policy
|
|
39
|
+
(["By Humans, For Humans"](https://github.com/geopython/pygeoapi/blob/master/CONTRIBUTING.md)).
|
|
40
|
+
It applies to contributions to pygeoapi, not to this plugin.
|
|
41
|
+
|
|
42
|
+
## License
|
|
43
|
+
|
|
44
|
+
By contributing, you agree that your contributions are licensed under the
|
|
45
|
+
[MIT license](LICENSE), like the rest of the project.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
The MIT License (MIT)
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Alexandre Leroux
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,263 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: pygeoapi-yaml
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: A pygeoapi provider for YAML files
|
|
5
|
+
Author-email: Alexandre Leroux <alexandreleroux@icloud.com>
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/alexandreleroux/pygeoapi-yaml
|
|
8
|
+
Project-URL: Issues, https://github.com/alexandreleroux/pygeoapi-yaml/issues
|
|
9
|
+
Keywords: pygeoapi,provider,plugin,yaml,OGC API
|
|
10
|
+
Classifier: Development Status :: 3 - Alpha
|
|
11
|
+
Classifier: Environment :: Plugins
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Intended Audience :: Science/Research
|
|
14
|
+
Classifier: Operating System :: OS Independent
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
18
|
+
Classifier: Topic :: Scientific/Engineering :: GIS
|
|
19
|
+
Requires-Python: >=3.12
|
|
20
|
+
Description-Content-Type: text/markdown
|
|
21
|
+
License-File: LICENSE
|
|
22
|
+
Requires-Dist: pygeoapi>=0.24
|
|
23
|
+
Requires-Dist: PyYAML
|
|
24
|
+
Requires-Dist: python-dateutil
|
|
25
|
+
Requires-Dist: shapely
|
|
26
|
+
Provides-Extra: dev
|
|
27
|
+
Requires-Dist: flake8; extra == "dev"
|
|
28
|
+
Requires-Dist: pytest; extra == "dev"
|
|
29
|
+
Dynamic: license-file
|
|
30
|
+
|
|
31
|
+
# pygeoapi-yaml
|
|
32
|
+
|
|
33
|
+
A [pygeoapi](https://pygeoapi.io) provider for YAML files. pygeoapi reads the YAML
|
|
34
|
+
file directly, so you don't need to convert it to GeoJSON first.
|
|
35
|
+
|
|
36
|
+
YAML and JSON map almost one to one, so GeoJSON can be written in YAML as it is:
|
|
37
|
+
a FeatureCollection in a YAML file is served unchanged. YAML adds what is pleasant
|
|
38
|
+
when you keep data by hand: comments, long texts that stay readable, and clean
|
|
39
|
+
diffs in git. Data kept by hand is often a plain list of records, as in a CSV
|
|
40
|
+
file, so the provider reads that too: you say where the id and the geometry are.
|
|
41
|
+
|
|
42
|
+
This provider publishes such a file as an OGC API - Features collection. The YAML
|
|
43
|
+
file stays the source of truth. pygeoapi answers in GeoJSON, as it does for every
|
|
44
|
+
other provider.
|
|
45
|
+
|
|
46
|
+
**Status: alpha, read-only.** See [Status and roadmap](#status-and-roadmap).
|
|
47
|
+
|
|
48
|
+
## Install
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
pip install pygeoapi-yaml
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
It needs pygeoapi 0.24 or later, in the same Python environment.
|
|
55
|
+
|
|
56
|
+
## Configure
|
|
57
|
+
|
|
58
|
+
Declare the provider in your pygeoapi configuration by its Python path. A file
|
|
59
|
+
can be written in one of three ways.
|
|
60
|
+
|
|
61
|
+
### A list of records, with coordinates in two fields
|
|
62
|
+
|
|
63
|
+
```yaml
|
|
64
|
+
# observations.yaml
|
|
65
|
+
- id: obs-1
|
|
66
|
+
name: Mont Royal
|
|
67
|
+
lat: 45.5
|
|
68
|
+
lon: -73.6
|
|
69
|
+
seen: 2026-05-01
|
|
70
|
+
tags: [birds, park]
|
|
71
|
+
- id: obs-2
|
|
72
|
+
name: Somewhere unknown # no coordinates: geometry is null
|
|
73
|
+
seen: 2026-07-20
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
```yaml
|
|
77
|
+
providers:
|
|
78
|
+
- type: feature
|
|
79
|
+
name: pygeoapi_yaml.provider.YAMLProvider
|
|
80
|
+
data: /data/observations.yaml
|
|
81
|
+
id_field: id
|
|
82
|
+
title_field: name
|
|
83
|
+
time_field: seen # optional, enables ?datetime=
|
|
84
|
+
geometry: # optional, as in the CSV provider
|
|
85
|
+
x_field: lon
|
|
86
|
+
y_field: lat
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
### Records under a key, with a GeoJSON geometry in a field
|
|
90
|
+
|
|
91
|
+
```yaml
|
|
92
|
+
# trails.yaml
|
|
93
|
+
title: Trails
|
|
94
|
+
trails:
|
|
95
|
+
- code: T1
|
|
96
|
+
name: Lakeshore
|
|
97
|
+
path:
|
|
98
|
+
type: LineString
|
|
99
|
+
coordinates: [[-73.60, 45.50], [-73.58, 45.51]]
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
```yaml
|
|
103
|
+
providers:
|
|
104
|
+
- type: feature
|
|
105
|
+
name: pygeoapi_yaml.provider.YAMLProvider
|
|
106
|
+
data: /data/trails.yaml
|
|
107
|
+
items_key: trails # where the list is
|
|
108
|
+
id_field: code
|
|
109
|
+
geometry:
|
|
110
|
+
field: path # a GeoJSON geometry
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
With no `geometry` setting at all, every item is served with `geometry: null`.
|
|
114
|
+
This is fine for data that isn't spatial.
|
|
115
|
+
|
|
116
|
+
### A GeoJSON FeatureCollection, written in YAML
|
|
117
|
+
|
|
118
|
+
```yaml
|
|
119
|
+
type: FeatureCollection
|
|
120
|
+
features:
|
|
121
|
+
- type: Feature
|
|
122
|
+
id: 123-456
|
|
123
|
+
geometry: {type: Point, coordinates: [125.6, 10.1]}
|
|
124
|
+
properties: {name: Dinagat Islands}
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
This needs no setting beyond `data`. `id_field` is used only for features
|
|
128
|
+
without an `id`.
|
|
129
|
+
|
|
130
|
+
## Behaviour
|
|
131
|
+
|
|
132
|
+
- **Queries.** All of these are supported:
|
|
133
|
+
- `limit` and `offset`;
|
|
134
|
+
- `resulttype=hits`;
|
|
135
|
+
- property filters (`?name=...`);
|
|
136
|
+
- `bbox`;
|
|
137
|
+
- `datetime` (an instant or an interval, open with `..`, on `time_field`);
|
|
138
|
+
- `sortby` (several properties allowed);
|
|
139
|
+
- `q`;
|
|
140
|
+
- `properties` (select properties);
|
|
141
|
+
- `skipGeometry`;
|
|
142
|
+
- `count: false`.
|
|
143
|
+
- **Field types** are read from all items. Integers and floats in the same field
|
|
144
|
+
give `number`. Other mixed types give `string`. YAML dates give
|
|
145
|
+
`string` with format `date` or `date-time`, so the queryables are right.
|
|
146
|
+
- **YAML values JSON lacks** are converted in responses:
|
|
147
|
+
- dates and timestamps become ISO 8601 strings;
|
|
148
|
+
- `!!binary` becomes base64.
|
|
149
|
+
- **Property filters** compare typed values: `?count=10` matches `10` and `10.0`,
|
|
150
|
+
and `?checked=true` matches a YAML `true`. If the field holds a list, the filter
|
|
151
|
+
matches when the list contains the value (`?tags=park`).
|
|
152
|
+
- **`q`** follows OGC API - Records:
|
|
153
|
+
- commas separate alternatives;
|
|
154
|
+
- spaces separate words that must all be found.
|
|
155
|
+
|
|
156
|
+
The search ignores case and looks in every text value, including values in
|
|
157
|
+
lists and nested mappings.
|
|
158
|
+
- **`bbox`** never matches an item without geometry. The OGC API - Features
|
|
159
|
+
specification asks for this. pygeoapi's GeoJSON and CSV providers include such
|
|
160
|
+
items instead.
|
|
161
|
+
- **Sorting** puts items without the property last, whether the order is
|
|
162
|
+
ascending or descending.
|
|
163
|
+
- **Ids** come from `id_field`. An item without one gets its position in the list
|
|
164
|
+
as its id, and a warning is logged, as are duplicate ids.
|
|
165
|
+
- **Changes are seen at once.** Each file is parsed once, then kept in memory
|
|
166
|
+
until its modification time or size changes. No restart is needed. pygeoapi
|
|
167
|
+
creates a provider for each request, so the parsed copy is shared between them.
|
|
168
|
+
- **Empty files** (empty, only comments, or `[]`) and **missing files** give an
|
|
169
|
+
empty collection, not an error.
|
|
170
|
+
- **Safe parsing.** The provider uses `yaml.safe_load`, so a YAML file can never
|
|
171
|
+
build Python objects or run code. An invalid file gives an error response, with
|
|
172
|
+
the details in the log.
|
|
173
|
+
- **Read-only.** OGC API - Features - Part 4 (create, replace, update, delete) is
|
|
174
|
+
not implemented yet. See the roadmap.
|
|
175
|
+
|
|
176
|
+
## Extending
|
|
177
|
+
|
|
178
|
+
To read another layout, or to compute properties, subclass `YAMLProvider` and
|
|
179
|
+
override `_features(document)`. It receives the parsed YAML document and returns
|
|
180
|
+
GeoJSON features. In the features it returns:
|
|
181
|
+
- values can still be YAML values, such as dates;
|
|
182
|
+
- an `id` can be `None`.
|
|
183
|
+
|
|
184
|
+
The provider still takes care of the rest: ids, field types, conversion to JSON,
|
|
185
|
+
queries and caching. Each subclass keeps its own parsed copy of a file.
|
|
186
|
+
|
|
187
|
+
```python
|
|
188
|
+
from pygeoapi_yaml.provider import YAMLProvider
|
|
189
|
+
|
|
190
|
+
|
|
191
|
+
class MyProvider(YAMLProvider):
|
|
192
|
+
def _features(self, document):
|
|
193
|
+
features = super()._features(document)
|
|
194
|
+
for feature in features:
|
|
195
|
+
feature['properties']['label'] = feature['properties']['name'].upper()
|
|
196
|
+
return features
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
## Development
|
|
200
|
+
|
|
201
|
+
```bash
|
|
202
|
+
python3 -m venv .venv
|
|
203
|
+
.venv/bin/pip install -e '.[dev]'
|
|
204
|
+
.venv/bin/pytest
|
|
205
|
+
.venv/bin/flake8 pygeoapi_yaml tests
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
There are two kinds of tests:
|
|
209
|
+
- `tests/test_yaml_provider.py` tests the provider on its own, in the style of
|
|
210
|
+
pygeoapi's provider tests.
|
|
211
|
+
- `tests/test_api.py` goes through pygeoapi itself:
|
|
212
|
+
- the configuration is validated against pygeoapi's schema;
|
|
213
|
+
- the OpenAPI document is generated;
|
|
214
|
+
- `/collections`, `/items`, `/items/{id}`, the queryables and an empty
|
|
215
|
+
collection are checked.
|
|
216
|
+
|
|
217
|
+
See [CONTRIBUTING.md](https://github.com/alexandreleroux/pygeoapi-yaml/blob/main/CONTRIBUTING.md) before opening a pull request.
|
|
218
|
+
|
|
219
|
+
## Status and roadmap
|
|
220
|
+
|
|
221
|
+
Done (0.1.0, on PyPI):
|
|
222
|
+
|
|
223
|
+
- [x] Read-only provider: `get_fields`, `query`, `get` and `get_domains`.
|
|
224
|
+
- [x] Three file layouts: records, records under `items_key`, a FeatureCollection.
|
|
225
|
+
- [x] Geometry from `x_field`/`y_field`, from a GeoJSON field, or none.
|
|
226
|
+
- [x] Every query parameter pygeoapi passes to a feature provider.
|
|
227
|
+
- [x] The file is read again when it changes; its parsed copy is shared between
|
|
228
|
+
requests.
|
|
229
|
+
- [x] Subclassing: override `_features()` to read another layout.
|
|
230
|
+
- [x] Tests for the provider alone and through pygeoapi, checked by mutation
|
|
231
|
+
testing (each deliberate bug in the provider makes a test fail).
|
|
232
|
+
- [x] Continuous integration: pytest and flake8 on Python 3.12 and 3.13.
|
|
233
|
+
|
|
234
|
+
Next:
|
|
235
|
+
|
|
236
|
+
- [ ] CI on both the oldest supported pygeoapi and the latest. For now they are
|
|
237
|
+
the same: 0.24 is both the minimum and the latest release.
|
|
238
|
+
- [ ] Listing on the
|
|
239
|
+
[pygeoapi community plugins page](https://github.com/geopython/pygeoapi/wiki/CommunityPluginsThemes).
|
|
240
|
+
- [ ] A `cql2` filter (`filter=`), through pygeofilter, as other providers do.
|
|
241
|
+
- [ ] Writing (OGC API - Features - Part 4). This only comes with
|
|
242
|
+
[ruamel.yaml](https://yaml.dev/doc/ruamel.yaml/), so that comments and
|
|
243
|
+
formatting survive a write. Otherwise a write would erase them.
|
|
244
|
+
- [ ] A directory of YAML files, one item per file, as a single collection.
|
|
245
|
+
- [ ] Then, on top of it, a catalogue of
|
|
246
|
+
[pygeometa](https://geopython.github.io/pygeometa) MCF files (YAML metadata,
|
|
247
|
+
one record per file) served as OGC API - Records.
|
|
248
|
+
|
|
249
|
+
## Authorship
|
|
250
|
+
|
|
251
|
+
Most of the code, tests and documentation were written by Claude, an AI model
|
|
252
|
+
made by Anthropic, working in [Claude Code](https://claude.com/claude-code).
|
|
253
|
+
Alexandre Leroux started the project, set its goals and made its design
|
|
254
|
+
decisions, and directed the work. Commits written with Claude carry a
|
|
255
|
+
`Co-Authored-By: Claude` trailer.
|
|
256
|
+
|
|
257
|
+
Whoever types the code, it is held to the same checks: each behaviour has a
|
|
258
|
+
test, some tests go through pygeoapi itself, and mutation testing shows that the
|
|
259
|
+
tests catch deliberate bugs.
|
|
260
|
+
|
|
261
|
+
## License
|
|
262
|
+
|
|
263
|
+
MIT, like pygeoapi. See [LICENSE](https://github.com/alexandreleroux/pygeoapi-yaml/blob/main/LICENSE).
|
|
@@ -0,0 +1,233 @@
|
|
|
1
|
+
# pygeoapi-yaml
|
|
2
|
+
|
|
3
|
+
A [pygeoapi](https://pygeoapi.io) provider for YAML files. pygeoapi reads the YAML
|
|
4
|
+
file directly, so you don't need to convert it to GeoJSON first.
|
|
5
|
+
|
|
6
|
+
YAML and JSON map almost one to one, so GeoJSON can be written in YAML as it is:
|
|
7
|
+
a FeatureCollection in a YAML file is served unchanged. YAML adds what is pleasant
|
|
8
|
+
when you keep data by hand: comments, long texts that stay readable, and clean
|
|
9
|
+
diffs in git. Data kept by hand is often a plain list of records, as in a CSV
|
|
10
|
+
file, so the provider reads that too: you say where the id and the geometry are.
|
|
11
|
+
|
|
12
|
+
This provider publishes such a file as an OGC API - Features collection. The YAML
|
|
13
|
+
file stays the source of truth. pygeoapi answers in GeoJSON, as it does for every
|
|
14
|
+
other provider.
|
|
15
|
+
|
|
16
|
+
**Status: alpha, read-only.** See [Status and roadmap](#status-and-roadmap).
|
|
17
|
+
|
|
18
|
+
## Install
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
pip install pygeoapi-yaml
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
It needs pygeoapi 0.24 or later, in the same Python environment.
|
|
25
|
+
|
|
26
|
+
## Configure
|
|
27
|
+
|
|
28
|
+
Declare the provider in your pygeoapi configuration by its Python path. A file
|
|
29
|
+
can be written in one of three ways.
|
|
30
|
+
|
|
31
|
+
### A list of records, with coordinates in two fields
|
|
32
|
+
|
|
33
|
+
```yaml
|
|
34
|
+
# observations.yaml
|
|
35
|
+
- id: obs-1
|
|
36
|
+
name: Mont Royal
|
|
37
|
+
lat: 45.5
|
|
38
|
+
lon: -73.6
|
|
39
|
+
seen: 2026-05-01
|
|
40
|
+
tags: [birds, park]
|
|
41
|
+
- id: obs-2
|
|
42
|
+
name: Somewhere unknown # no coordinates: geometry is null
|
|
43
|
+
seen: 2026-07-20
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
```yaml
|
|
47
|
+
providers:
|
|
48
|
+
- type: feature
|
|
49
|
+
name: pygeoapi_yaml.provider.YAMLProvider
|
|
50
|
+
data: /data/observations.yaml
|
|
51
|
+
id_field: id
|
|
52
|
+
title_field: name
|
|
53
|
+
time_field: seen # optional, enables ?datetime=
|
|
54
|
+
geometry: # optional, as in the CSV provider
|
|
55
|
+
x_field: lon
|
|
56
|
+
y_field: lat
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
### Records under a key, with a GeoJSON geometry in a field
|
|
60
|
+
|
|
61
|
+
```yaml
|
|
62
|
+
# trails.yaml
|
|
63
|
+
title: Trails
|
|
64
|
+
trails:
|
|
65
|
+
- code: T1
|
|
66
|
+
name: Lakeshore
|
|
67
|
+
path:
|
|
68
|
+
type: LineString
|
|
69
|
+
coordinates: [[-73.60, 45.50], [-73.58, 45.51]]
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
```yaml
|
|
73
|
+
providers:
|
|
74
|
+
- type: feature
|
|
75
|
+
name: pygeoapi_yaml.provider.YAMLProvider
|
|
76
|
+
data: /data/trails.yaml
|
|
77
|
+
items_key: trails # where the list is
|
|
78
|
+
id_field: code
|
|
79
|
+
geometry:
|
|
80
|
+
field: path # a GeoJSON geometry
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
With no `geometry` setting at all, every item is served with `geometry: null`.
|
|
84
|
+
This is fine for data that isn't spatial.
|
|
85
|
+
|
|
86
|
+
### A GeoJSON FeatureCollection, written in YAML
|
|
87
|
+
|
|
88
|
+
```yaml
|
|
89
|
+
type: FeatureCollection
|
|
90
|
+
features:
|
|
91
|
+
- type: Feature
|
|
92
|
+
id: 123-456
|
|
93
|
+
geometry: {type: Point, coordinates: [125.6, 10.1]}
|
|
94
|
+
properties: {name: Dinagat Islands}
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
This needs no setting beyond `data`. `id_field` is used only for features
|
|
98
|
+
without an `id`.
|
|
99
|
+
|
|
100
|
+
## Behaviour
|
|
101
|
+
|
|
102
|
+
- **Queries.** All of these are supported:
|
|
103
|
+
- `limit` and `offset`;
|
|
104
|
+
- `resulttype=hits`;
|
|
105
|
+
- property filters (`?name=...`);
|
|
106
|
+
- `bbox`;
|
|
107
|
+
- `datetime` (an instant or an interval, open with `..`, on `time_field`);
|
|
108
|
+
- `sortby` (several properties allowed);
|
|
109
|
+
- `q`;
|
|
110
|
+
- `properties` (select properties);
|
|
111
|
+
- `skipGeometry`;
|
|
112
|
+
- `count: false`.
|
|
113
|
+
- **Field types** are read from all items. Integers and floats in the same field
|
|
114
|
+
give `number`. Other mixed types give `string`. YAML dates give
|
|
115
|
+
`string` with format `date` or `date-time`, so the queryables are right.
|
|
116
|
+
- **YAML values JSON lacks** are converted in responses:
|
|
117
|
+
- dates and timestamps become ISO 8601 strings;
|
|
118
|
+
- `!!binary` becomes base64.
|
|
119
|
+
- **Property filters** compare typed values: `?count=10` matches `10` and `10.0`,
|
|
120
|
+
and `?checked=true` matches a YAML `true`. If the field holds a list, the filter
|
|
121
|
+
matches when the list contains the value (`?tags=park`).
|
|
122
|
+
- **`q`** follows OGC API - Records:
|
|
123
|
+
- commas separate alternatives;
|
|
124
|
+
- spaces separate words that must all be found.
|
|
125
|
+
|
|
126
|
+
The search ignores case and looks in every text value, including values in
|
|
127
|
+
lists and nested mappings.
|
|
128
|
+
- **`bbox`** never matches an item without geometry. The OGC API - Features
|
|
129
|
+
specification asks for this. pygeoapi's GeoJSON and CSV providers include such
|
|
130
|
+
items instead.
|
|
131
|
+
- **Sorting** puts items without the property last, whether the order is
|
|
132
|
+
ascending or descending.
|
|
133
|
+
- **Ids** come from `id_field`. An item without one gets its position in the list
|
|
134
|
+
as its id, and a warning is logged, as are duplicate ids.
|
|
135
|
+
- **Changes are seen at once.** Each file is parsed once, then kept in memory
|
|
136
|
+
until its modification time or size changes. No restart is needed. pygeoapi
|
|
137
|
+
creates a provider for each request, so the parsed copy is shared between them.
|
|
138
|
+
- **Empty files** (empty, only comments, or `[]`) and **missing files** give an
|
|
139
|
+
empty collection, not an error.
|
|
140
|
+
- **Safe parsing.** The provider uses `yaml.safe_load`, so a YAML file can never
|
|
141
|
+
build Python objects or run code. An invalid file gives an error response, with
|
|
142
|
+
the details in the log.
|
|
143
|
+
- **Read-only.** OGC API - Features - Part 4 (create, replace, update, delete) is
|
|
144
|
+
not implemented yet. See the roadmap.
|
|
145
|
+
|
|
146
|
+
## Extending
|
|
147
|
+
|
|
148
|
+
To read another layout, or to compute properties, subclass `YAMLProvider` and
|
|
149
|
+
override `_features(document)`. It receives the parsed YAML document and returns
|
|
150
|
+
GeoJSON features. In the features it returns:
|
|
151
|
+
- values can still be YAML values, such as dates;
|
|
152
|
+
- an `id` can be `None`.
|
|
153
|
+
|
|
154
|
+
The provider still takes care of the rest: ids, field types, conversion to JSON,
|
|
155
|
+
queries and caching. Each subclass keeps its own parsed copy of a file.
|
|
156
|
+
|
|
157
|
+
```python
|
|
158
|
+
from pygeoapi_yaml.provider import YAMLProvider
|
|
159
|
+
|
|
160
|
+
|
|
161
|
+
class MyProvider(YAMLProvider):
|
|
162
|
+
def _features(self, document):
|
|
163
|
+
features = super()._features(document)
|
|
164
|
+
for feature in features:
|
|
165
|
+
feature['properties']['label'] = feature['properties']['name'].upper()
|
|
166
|
+
return features
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
## Development
|
|
170
|
+
|
|
171
|
+
```bash
|
|
172
|
+
python3 -m venv .venv
|
|
173
|
+
.venv/bin/pip install -e '.[dev]'
|
|
174
|
+
.venv/bin/pytest
|
|
175
|
+
.venv/bin/flake8 pygeoapi_yaml tests
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
There are two kinds of tests:
|
|
179
|
+
- `tests/test_yaml_provider.py` tests the provider on its own, in the style of
|
|
180
|
+
pygeoapi's provider tests.
|
|
181
|
+
- `tests/test_api.py` goes through pygeoapi itself:
|
|
182
|
+
- the configuration is validated against pygeoapi's schema;
|
|
183
|
+
- the OpenAPI document is generated;
|
|
184
|
+
- `/collections`, `/items`, `/items/{id}`, the queryables and an empty
|
|
185
|
+
collection are checked.
|
|
186
|
+
|
|
187
|
+
See [CONTRIBUTING.md](https://github.com/alexandreleroux/pygeoapi-yaml/blob/main/CONTRIBUTING.md) before opening a pull request.
|
|
188
|
+
|
|
189
|
+
## Status and roadmap
|
|
190
|
+
|
|
191
|
+
Done (0.1.0, on PyPI):
|
|
192
|
+
|
|
193
|
+
- [x] Read-only provider: `get_fields`, `query`, `get` and `get_domains`.
|
|
194
|
+
- [x] Three file layouts: records, records under `items_key`, a FeatureCollection.
|
|
195
|
+
- [x] Geometry from `x_field`/`y_field`, from a GeoJSON field, or none.
|
|
196
|
+
- [x] Every query parameter pygeoapi passes to a feature provider.
|
|
197
|
+
- [x] The file is read again when it changes; its parsed copy is shared between
|
|
198
|
+
requests.
|
|
199
|
+
- [x] Subclassing: override `_features()` to read another layout.
|
|
200
|
+
- [x] Tests for the provider alone and through pygeoapi, checked by mutation
|
|
201
|
+
testing (each deliberate bug in the provider makes a test fail).
|
|
202
|
+
- [x] Continuous integration: pytest and flake8 on Python 3.12 and 3.13.
|
|
203
|
+
|
|
204
|
+
Next:
|
|
205
|
+
|
|
206
|
+
- [ ] CI on both the oldest supported pygeoapi and the latest. For now they are
|
|
207
|
+
the same: 0.24 is both the minimum and the latest release.
|
|
208
|
+
- [ ] Listing on the
|
|
209
|
+
[pygeoapi community plugins page](https://github.com/geopython/pygeoapi/wiki/CommunityPluginsThemes).
|
|
210
|
+
- [ ] A `cql2` filter (`filter=`), through pygeofilter, as other providers do.
|
|
211
|
+
- [ ] Writing (OGC API - Features - Part 4). This only comes with
|
|
212
|
+
[ruamel.yaml](https://yaml.dev/doc/ruamel.yaml/), so that comments and
|
|
213
|
+
formatting survive a write. Otherwise a write would erase them.
|
|
214
|
+
- [ ] A directory of YAML files, one item per file, as a single collection.
|
|
215
|
+
- [ ] Then, on top of it, a catalogue of
|
|
216
|
+
[pygeometa](https://geopython.github.io/pygeometa) MCF files (YAML metadata,
|
|
217
|
+
one record per file) served as OGC API - Records.
|
|
218
|
+
|
|
219
|
+
## Authorship
|
|
220
|
+
|
|
221
|
+
Most of the code, tests and documentation were written by Claude, an AI model
|
|
222
|
+
made by Anthropic, working in [Claude Code](https://claude.com/claude-code).
|
|
223
|
+
Alexandre Leroux started the project, set its goals and made its design
|
|
224
|
+
decisions, and directed the work. Commits written with Claude carry a
|
|
225
|
+
`Co-Authored-By: Claude` trailer.
|
|
226
|
+
|
|
227
|
+
Whoever types the code, it is held to the same checks: each behaviour has a
|
|
228
|
+
test, some tests go through pygeoapi itself, and mutation testing shows that the
|
|
229
|
+
tests catch deliberate bugs.
|
|
230
|
+
|
|
231
|
+
## License
|
|
232
|
+
|
|
233
|
+
MIT, like pygeoapi. See [LICENSE](https://github.com/alexandreleroux/pygeoapi-yaml/blob/main/LICENSE).
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# =================================================================
|
|
2
|
+
#
|
|
3
|
+
# Authors: Alexandre Leroux <alexandreleroux@icloud.com>
|
|
4
|
+
#
|
|
5
|
+
# Copyright (c) 2026 Alexandre Leroux
|
|
6
|
+
#
|
|
7
|
+
# Permission is hereby granted, free of charge, to any person
|
|
8
|
+
# obtaining a copy of this software and associated documentation
|
|
9
|
+
# files (the "Software"), to deal in the Software without
|
|
10
|
+
# restriction, including without limitation the rights to use,
|
|
11
|
+
# copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
12
|
+
# copies of the Software, and to permit persons to whom the
|
|
13
|
+
# Software is furnished to do so, subject to the following
|
|
14
|
+
# conditions:
|
|
15
|
+
#
|
|
16
|
+
# The above copyright notice and this permission notice shall be
|
|
17
|
+
# included in all copies or substantial portions of the Software.
|
|
18
|
+
#
|
|
19
|
+
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
|
20
|
+
# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
|
|
21
|
+
# OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
|
22
|
+
# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
|
|
23
|
+
# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
|
|
24
|
+
# WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
|
|
25
|
+
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
|
|
26
|
+
# OTHER DEALINGS IN THE SOFTWARE.
|
|
27
|
+
#
|
|
28
|
+
# =================================================================
|
|
29
|
+
|
|
30
|
+
__version__ = '0.1.0'
|