pygeoapi-yaml 0.1.0__py3-none-any.whl

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.
@@ -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'
@@ -0,0 +1,729 @@
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
+ import base64
31
+ from copy import deepcopy
32
+ from datetime import date, datetime, time, timezone
33
+ import logging
34
+ import os
35
+ import threading
36
+
37
+ from dateutil.parser import isoparse
38
+ from shapely.geometry import box, shape
39
+ import yaml
40
+
41
+ from pygeoapi.crs import crs_transform
42
+ from pygeoapi.provider.base import (BaseProvider, ProviderInvalidDataError,
43
+ ProviderInvalidQueryError,
44
+ ProviderItemNotFoundError)
45
+
46
+ LOGGER = logging.getLogger(__name__)
47
+
48
+ # pygeoapi creates a provider object for each request: parsed files are
49
+ # kept here, shared by all of them, and parsed again only when the
50
+ # file's modification time or size has changed
51
+ _CACHE = {}
52
+ _CACHE_LOCK = threading.Lock()
53
+
54
+
55
+ class YAMLProvider(BaseProvider):
56
+ """Provider class backed by local YAML files
57
+
58
+ The file holds either:
59
+
60
+ * a list of records (mappings), at the top level of the document
61
+ or under the key named by `items_key`
62
+ * a GeoJSON FeatureCollection, written in YAML
63
+
64
+ For records, the geometry is optional: a point built from two
65
+ fields (`geometry.x_field`, `geometry.y_field`, as in the CSV
66
+ provider), a field holding a GeoJSON geometry (`geometry.field`),
67
+ or none (`geometry: null` in responses).
68
+
69
+ Read-only. The file is read again as soon as it changes, without
70
+ restarting pygeoapi. YAML is parsed with `yaml.safe_load`: no
71
+ Python objects are ever built from the file.
72
+
73
+ Values YAML parses natively and JSON lacks are converted in
74
+ responses: dates and timestamps to ISO 8601 strings, binary to
75
+ base64 strings.
76
+ """
77
+
78
+ def __init__(self, provider_def):
79
+ """
80
+ Initialize object
81
+
82
+ :param provider_def: provider definition
83
+
84
+ :returns: pygeoapi_yaml.provider.YAMLProvider
85
+ """
86
+
87
+ super().__init__(provider_def)
88
+
89
+ geometry = provider_def.get('geometry') or {}
90
+ self.geometry_x = geometry.get('x_field')
91
+ self.geometry_y = geometry.get('y_field')
92
+ self.geometry_field = geometry.get('field')
93
+ if bool(self.geometry_x) != bool(self.geometry_y):
94
+ msg = 'geometry needs both x_field and y_field'
95
+ LOGGER.error(msg)
96
+ raise RuntimeError(msg)
97
+ if self.geometry_field and self.geometry_x:
98
+ msg = 'geometry takes either field or x_field/y_field'
99
+ LOGGER.error(msg)
100
+ raise RuntimeError(msg)
101
+
102
+ self.items_key = provider_def.get('items_key')
103
+
104
+ self.get_fields()
105
+
106
+ def get_fields(self):
107
+ """
108
+ Get provider field information (names, types)
109
+
110
+ Types are read from all items: a field holding integers and
111
+ floats is a number; a field holding values of other, mixed
112
+ types is a string.
113
+
114
+ :returns: dict of fields
115
+ """
116
+
117
+ if not self._fields:
118
+ self._fields = deepcopy(self._read()['fields'])
119
+
120
+ return self._fields
121
+
122
+ def get_domains(self, properties=[], current=False):
123
+ """
124
+ Get domains from dataset
125
+
126
+ :param properties: `list` of property names
127
+ :param current: `bool` of whether to provide list of live
128
+ values (default `False`)
129
+
130
+ :returns: `tuple` of domains and whether they are based on the
131
+ current/live dataset
132
+ """
133
+
134
+ domains = {}
135
+ keys = properties or self.fields.keys()
136
+
137
+ for key in keys:
138
+ values = set()
139
+ for feature in self._read()['features']:
140
+ value = feature['properties'].get(key)
141
+ if isinstance(value, (bool, int, float, str)):
142
+ values.add(value)
143
+ if values:
144
+ domains[key] = sorted(values, key=_sort_key)
145
+
146
+ return domains, True
147
+
148
+ def _read(self):
149
+ """
150
+ Read and parse the YAML file at self.data, or return the
151
+ copy parsed earlier if the file has not changed since
152
+
153
+ :returns: `dict` of features (JSON-ready) and fields
154
+ """
155
+
156
+ try:
157
+ stat = os.stat(self.data)
158
+ except FileNotFoundError:
159
+ LOGGER.warning(f'File {self.data} does not exist.')
160
+ return {'features': [], 'fields': {}}
161
+
162
+ key = (type(self), os.path.abspath(self.data), self.items_key,
163
+ self.id_field, self.geometry_x, self.geometry_y,
164
+ self.geometry_field)
165
+ stamp = (stat.st_mtime_ns, stat.st_size)
166
+
167
+ with _CACHE_LOCK:
168
+ cached = _CACHE.get(key)
169
+ if cached and cached[0] == stamp:
170
+ return cached[1]
171
+
172
+ LOGGER.debug(f'Parsing {self.data}')
173
+ try:
174
+ with open(self.data, encoding='utf-8') as fh:
175
+ document = yaml.safe_load(fh)
176
+ except (yaml.YAMLError, UnicodeDecodeError) as err:
177
+ msg = f'Invalid YAML file {self.data}'
178
+ LOGGER.error(f'{msg}: {err}')
179
+ raise ProviderInvalidDataError(msg)
180
+
181
+ parsed = self._parse(document)
182
+
183
+ with _CACHE_LOCK:
184
+ _CACHE[key] = (stamp, parsed)
185
+
186
+ return parsed
187
+
188
+ def _parse(self, document):
189
+ """
190
+ Turn a parsed YAML document into JSON-ready GeoJSON features,
191
+ and read the fields from them
192
+
193
+ :param document: the parsed YAML document
194
+
195
+ :returns: `dict` of features (JSON-ready) and fields
196
+ """
197
+
198
+ features = []
199
+ fields = {}
200
+ ids = set()
201
+
202
+ for index, feature in enumerate(self._features(document)):
203
+ identifier = feature.get('id')
204
+ if identifier is None:
205
+ LOGGER.warning(f'Item {index} has no id, using its position')
206
+ identifier = index
207
+ if str(identifier) in ids:
208
+ LOGGER.warning(f'Duplicate id {identifier}')
209
+ ids.add(str(identifier))
210
+
211
+ properties = feature.get('properties') or {}
212
+ for name, value in properties.items():
213
+ _add_field(fields, str(name), value)
214
+
215
+ features.append({
216
+ 'type': 'Feature',
217
+ 'id': _jsonable(identifier),
218
+ 'geometry': _jsonable(feature.get('geometry')),
219
+ 'properties': _jsonable(properties)
220
+ })
221
+
222
+ for field in fields.values():
223
+ field.pop('_unset', None)
224
+
225
+ return {'features': features, 'fields': fields}
226
+
227
+ def _features(self, document):
228
+ """
229
+ Find the items of a parsed YAML document, as GeoJSON features
230
+
231
+ Override this in a subclass to read another layout, or to
232
+ compute properties: values may still be YAML values (dates…),
233
+ and an id may be `None` (the item's position is then used).
234
+
235
+ :param document: the parsed YAML document
236
+
237
+ :returns: list of `dict` of GeoJSON features
238
+ """
239
+
240
+ if document is None:
241
+ return []
242
+
243
+ if isinstance(document, dict) and \
244
+ document.get('type') == 'FeatureCollection':
245
+ items = document.get('features') or []
246
+ is_collection = True
247
+ else:
248
+ is_collection = False
249
+ if self.items_key:
250
+ if not isinstance(document, dict):
251
+ msg = f'{self.data}: items_key set, but not a mapping'
252
+ LOGGER.error(msg)
253
+ raise ProviderInvalidDataError(msg)
254
+ items = document.get(self.items_key) or []
255
+ else:
256
+ items = document
257
+
258
+ if not isinstance(items, list):
259
+ msg = f'{self.data}: no list of items found (set items_key?)'
260
+ LOGGER.error(msg)
261
+ raise ProviderInvalidDataError(msg)
262
+
263
+ features = []
264
+
265
+ for index, item in enumerate(items):
266
+ if not isinstance(item, dict):
267
+ LOGGER.warning(f'Item {index} is not a mapping, skipping')
268
+ continue
269
+
270
+ if is_collection:
271
+ properties = dict(item.get('properties') or {})
272
+ geometry = item.get('geometry')
273
+ identifier = item.get('id')
274
+ if identifier is None and self.id_field:
275
+ identifier = properties.get(self.id_field)
276
+ else:
277
+ properties = dict(item)
278
+ geometry = self._geometry(properties, index)
279
+ identifier = properties.get(self.id_field) \
280
+ if self.id_field else None
281
+
282
+ features.append({
283
+ 'type': 'Feature',
284
+ 'id': identifier,
285
+ 'geometry': geometry,
286
+ 'properties': properties
287
+ })
288
+
289
+ return features
290
+
291
+ def _geometry(self, properties, index):
292
+ """
293
+ Take the geometry out of a record
294
+
295
+ :param properties: `dict` of the record (geometry fields are
296
+ removed from it)
297
+ :param index: position of the record, for log messages
298
+
299
+ :returns: `dict` of GeoJSON geometry, or `None`
300
+ """
301
+
302
+ if self.geometry_field:
303
+ geometry = properties.pop(self.geometry_field, None)
304
+ if geometry is not None and not _is_geometry(geometry):
305
+ LOGGER.warning(f'Item {index}: invalid geometry, ignored')
306
+ geometry = None
307
+ return geometry
308
+
309
+ if self.geometry_x:
310
+ x = properties.pop(self.geometry_x, None)
311
+ y = properties.pop(self.geometry_y, None)
312
+ if x is None and y is None:
313
+ return None
314
+ try:
315
+ return {
316
+ 'type': 'Point',
317
+ 'coordinates': [float(x), float(y)]
318
+ }
319
+ except (TypeError, ValueError):
320
+ LOGGER.warning(f'Item {index}: invalid coordinates, ignored')
321
+ return None
322
+
323
+ return None
324
+
325
+ def _load(self, bbox=[], datetime_=None, properties=[], sortby=[],
326
+ q=None):
327
+ """
328
+ Select and sort the features of the YAML file
329
+
330
+ :param bbox: bounding box [minx,miny,maxx,maxy]
331
+ :param datetime_: temporal (datestamp or extent)
332
+ :param properties: list of tuples (name, value)
333
+ :param sortby: list of dicts (property, order)
334
+ :param q: full-text search term(s)
335
+
336
+ :returns: list of GeoJSON features (shared: do not modify)
337
+ """
338
+
339
+ features = self._read()['features']
340
+
341
+ if properties:
342
+ LOGGER.debug('processing properties parameter')
343
+ for name, _ in properties:
344
+ if name not in self.fields:
345
+ msg = 'Invalid query: invalid property name'
346
+ LOGGER.error(msg)
347
+ raise ProviderInvalidQueryError(msg)
348
+ features = [f for f in features if all(
349
+ _equals(f['properties'].get(name), value)
350
+ for name, value in properties)]
351
+
352
+ if datetime_ is not None:
353
+ if self.time_field is None:
354
+ LOGGER.debug('time_field not set, ignoring datetime')
355
+ else:
356
+ LOGGER.debug('processing datetime parameter')
357
+ features = self._filter_datetime(features, datetime_)
358
+
359
+ if q:
360
+ LOGGER.debug('processing q parameter')
361
+ features = [f for f in features if _search(f['properties'], q)]
362
+
363
+ if bbox:
364
+ LOGGER.debug('processing bbox parameter')
365
+ if len(bbox) > 4:
366
+ LOGGER.debug('bbox reduced to 4 elements')
367
+ bbox = bbox[:4]
368
+ area = box(*bbox)
369
+ features = [f for f in features
370
+ if self._intersects(f['geometry'], area)]
371
+
372
+ if sortby:
373
+ LOGGER.debug('processing sortby parameter')
374
+ features = list(features)
375
+ for sort in reversed(sortby):
376
+ name = sort['property']
377
+ if name not in self.fields:
378
+ msg = 'Invalid query: invalid sortby property'
379
+ LOGGER.error(msg)
380
+ raise ProviderInvalidQueryError(msg)
381
+ reverse = sort.get('order') == '-'
382
+ present = [f for f in features
383
+ if f['properties'].get(name) is not None]
384
+ missing = [f for f in features
385
+ if f['properties'].get(name) is None]
386
+ present.sort(
387
+ key=lambda f: _sort_key(f['properties'][name]),
388
+ reverse=reverse)
389
+ # items without the property come last, in either order
390
+ features = present + missing
391
+
392
+ return features
393
+
394
+ def _filter_datetime(self, features, datetime_):
395
+ """
396
+ Keep the features whose time_field matches datetime_
397
+
398
+ :param features: list of GeoJSON features
399
+ :param datetime_: `str` of instant, or interval with `/`
400
+ (`..` for an open end)
401
+
402
+ :returns: list of GeoJSON features
403
+ """
404
+
405
+ try:
406
+ if '/' in datetime_:
407
+ begin, end = datetime_.split('/')
408
+ begin = None if begin in ('', '..') else _instant(begin)
409
+ end = None if end in ('', '..') else _instant(end)
410
+ else:
411
+ begin = end = _instant(datetime_)
412
+ except ValueError:
413
+ msg = 'Invalid query: invalid datetime'
414
+ LOGGER.error(msg)
415
+ raise ProviderInvalidQueryError(msg)
416
+
417
+ selected = []
418
+ for feature in features:
419
+ try:
420
+ value = _instant(feature['properties'].get(self.time_field))
421
+ except (TypeError, ValueError):
422
+ continue
423
+ if begin is not None and value < begin:
424
+ continue
425
+ if end is not None and value > end:
426
+ continue
427
+ selected.append(feature)
428
+
429
+ return selected
430
+
431
+ def _intersects(self, geometry, area):
432
+ """
433
+ Helper function to evaluate feature geometry intersection with a bbox
434
+
435
+ :param geometry: `dict` of GeoJSON geometry
436
+ :param area: shapely box of the bbox
437
+
438
+ :returns: `bool` of whether geometry intersects with bbox
439
+ (`False` for a feature without geometry)
440
+ """
441
+
442
+ if geometry is None:
443
+ return False
444
+
445
+ try:
446
+ return shape(geometry).intersects(area)
447
+ except Exception as err:
448
+ LOGGER.warning(f'Invalid geometry: {err}')
449
+ return False
450
+
451
+ def _shape(self, feature, skip_geometry=False, select_properties=[]):
452
+ """
453
+ Copy a feature for a response, with only the requested parts
454
+
455
+ :param feature: `dict` of GeoJSON feature
456
+ :param skip_geometry: bool of whether to skip geometry
457
+ :param select_properties: list of property names
458
+
459
+ :returns: `dict` of GeoJSON feature
460
+ """
461
+
462
+ feature = deepcopy(feature)
463
+
464
+ if skip_geometry:
465
+ feature['geometry'] = None
466
+
467
+ if self.properties or select_properties:
468
+ keep = set(self.properties) | set(select_properties)
469
+ feature['properties'] = {
470
+ k: v for k, v in feature['properties'].items() if k in keep}
471
+
472
+ return feature
473
+
474
+ @crs_transform
475
+ def query(self, offset=0, limit=10, resulttype='results',
476
+ bbox=[], datetime_=None, properties=[], sortby=[],
477
+ select_properties=[], skip_geometry=False, q=None, **kwargs):
478
+ """
479
+ query the provider
480
+
481
+ :param offset: starting record to return (default 0)
482
+ :param limit: number of records to return (default 10)
483
+ :param resulttype: return results or hit limit (default results)
484
+ :param bbox: bounding box [minx,miny,maxx,maxy]
485
+ :param datetime_: temporal (datestamp or extent)
486
+ :param properties: list of tuples (name, value)
487
+ :param sortby: list of dicts (property, order)
488
+ :param select_properties: list of property names
489
+ :param skip_geometry: bool of whether to skip geometry (default False)
490
+ :param q: full-text search term(s)
491
+
492
+ :returns: FeatureCollection dict of 0..n GeoJSON features
493
+ """
494
+
495
+ features = self._load(bbox=bbox, datetime_=datetime_,
496
+ properties=properties, sortby=sortby, q=q)
497
+
498
+ feature_collection = {
499
+ 'type': 'FeatureCollection',
500
+ 'features': []
501
+ }
502
+
503
+ if self.count or resulttype == 'hits':
504
+ feature_collection['numberMatched'] = len(features)
505
+
506
+ if resulttype == 'hits':
507
+ return feature_collection
508
+
509
+ feature_collection['features'] = [
510
+ self._shape(f, skip_geometry, select_properties)
511
+ for f in features[offset:offset + limit]]
512
+ feature_collection['numberReturned'] = len(
513
+ feature_collection['features'])
514
+
515
+ return feature_collection
516
+
517
+ @crs_transform
518
+ def get(self, identifier, **kwargs):
519
+ """
520
+ query the provider by id
521
+
522
+ :param identifier: feature id
523
+
524
+ :returns: dict of single GeoJSON feature
525
+ """
526
+
527
+ for feature in self._read()['features']:
528
+ if str(feature['id']) == str(identifier):
529
+ return self._shape(feature)
530
+
531
+ err = f'item {identifier} not found'
532
+ LOGGER.error(err)
533
+ raise ProviderItemNotFoundError(err)
534
+
535
+ def __repr__(self):
536
+ return f'<YAMLProvider> {self.data}'
537
+
538
+
539
+ def _jsonable(value):
540
+ """
541
+ Convert what YAML parses and JSON lacks
542
+
543
+ :param value: a value parsed from YAML
544
+
545
+ :returns: the value, with dates as ISO 8601 strings and binary
546
+ as base64 strings
547
+ """
548
+
549
+ if isinstance(value, dict):
550
+ return {str(k): _jsonable(v) for k, v in value.items()}
551
+ if isinstance(value, (list, tuple, set)):
552
+ return [_jsonable(v) for v in value]
553
+ if isinstance(value, (date, datetime)):
554
+ return value.isoformat()
555
+ if isinstance(value, bytes):
556
+ return base64.b64encode(value).decode('ascii')
557
+ return value
558
+
559
+
560
+ def _field_type(value):
561
+ """
562
+ JSON Schema type (and format) of a value parsed from YAML
563
+
564
+ :param value: a value parsed from YAML
565
+
566
+ :returns: `dict` of type and optional format
567
+ """
568
+
569
+ if isinstance(value, bool):
570
+ return {'type': 'boolean'}
571
+ if isinstance(value, int):
572
+ return {'type': 'integer'}
573
+ if isinstance(value, float):
574
+ return {'type': 'number'}
575
+ if isinstance(value, datetime):
576
+ return {'type': 'string', 'format': 'date-time'}
577
+ if isinstance(value, date):
578
+ return {'type': 'string', 'format': 'date'}
579
+ if isinstance(value, (list, tuple, set)):
580
+ return {'type': 'array'}
581
+ if isinstance(value, dict):
582
+ return {'type': 'object'}
583
+ return {'type': 'string'}
584
+
585
+
586
+ def _add_field(fields, name, value):
587
+ """
588
+ Add what a value says about its field to fields
589
+
590
+ :param fields: `dict` of fields, updated in place
591
+ :param name: `str` of field name
592
+ :param value: a value of that field
593
+
594
+ :returns: `None`
595
+ """
596
+
597
+ if value is None:
598
+ fields.setdefault(name, {'type': 'string'})
599
+ fields[name].setdefault('_unset', True)
600
+ return
601
+
602
+ type_ = _field_type(value)
603
+ current = fields.get(name)
604
+
605
+ if current is None or current.get('_unset'):
606
+ fields[name] = type_
607
+ elif current != type_:
608
+ numbers = {'integer', 'number'}
609
+ if {current['type'], type_['type']} <= numbers:
610
+ fields[name] = {'type': 'number'}
611
+ else:
612
+ fields[name] = {'type': 'string'}
613
+
614
+
615
+ def _is_geometry(value):
616
+ """
617
+ Whether a value looks like a GeoJSON geometry
618
+
619
+ :param value: a value parsed from YAML
620
+
621
+ :returns: `bool`
622
+ """
623
+
624
+ return isinstance(value, dict) and isinstance(value.get('type'), str) \
625
+ and ('coordinates' in value or 'geometries' in value)
626
+
627
+
628
+ def _equals(value, expected):
629
+ """
630
+ Whether a property value matches a query value (always a string
631
+ in a URL); a list matches if one of its values does
632
+
633
+ :param value: the property value
634
+ :param expected: the query value
635
+
636
+ :returns: `bool`
637
+ """
638
+
639
+ if isinstance(value, list):
640
+ return any(_equals(v, expected) for v in value)
641
+ if isinstance(value, bool):
642
+ return str(value).lower() == str(expected).lower()
643
+ if isinstance(value, (int, float)):
644
+ try:
645
+ return float(expected) == value
646
+ except (TypeError, ValueError):
647
+ return False
648
+ return value is not None and str(value) == str(expected)
649
+
650
+
651
+ def _search(properties, q):
652
+ """
653
+ Full-text search, as in OGC API - Records: terms separated by
654
+ commas are alternatives, words separated by spaces must all be
655
+ found; case-insensitive, in all text values (nested included)
656
+
657
+ :param properties: `dict` of feature properties
658
+ :param q: `str` of q parameter value
659
+
660
+ :returns: `bool`
661
+ """
662
+
663
+ text = ' '.join(_texts(properties)).lower()
664
+
665
+ for term in q.split(','):
666
+ words = term.lower().split()
667
+ if words and all(word in text for word in words):
668
+ return True
669
+
670
+ return False
671
+
672
+
673
+ def _texts(value):
674
+ """
675
+ All text values found in a value
676
+
677
+ :param value: a JSON-ready value
678
+
679
+ :returns: generator of `str`
680
+ """
681
+
682
+ if isinstance(value, str):
683
+ yield value
684
+ elif isinstance(value, dict):
685
+ for v in value.values():
686
+ yield from _texts(v)
687
+ elif isinstance(value, list):
688
+ for v in value:
689
+ yield from _texts(v)
690
+
691
+
692
+ def _instant(value):
693
+ """
694
+ A comparable, timezone-aware datetime from an ISO 8601 value
695
+
696
+ :param value: `str`, `date` or `datetime`
697
+
698
+ :returns: `datetime` (UTC when no timezone is given)
699
+ """
700
+
701
+ if isinstance(value, str):
702
+ value = isoparse(value)
703
+ if isinstance(value, datetime):
704
+ pass
705
+ elif isinstance(value, date):
706
+ value = datetime.combine(value, time())
707
+ else:
708
+ raise TypeError(f'not a date: {value!r}')
709
+
710
+ if value.tzinfo is None:
711
+ value = value.replace(tzinfo=timezone.utc)
712
+
713
+ return value
714
+
715
+
716
+ def _sort_key(value):
717
+ """
718
+ Sort key mixing types without failing: numbers, then text
719
+
720
+ :param value: a property value
721
+
722
+ :returns: `tuple`
723
+ """
724
+
725
+ if isinstance(value, bool):
726
+ return (0, int(value), '')
727
+ if isinstance(value, (int, float)):
728
+ return (0, value, '')
729
+ return (1, 0, str(value))
@@ -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,7 @@
1
+ pygeoapi_yaml/__init__.py,sha256=cZfQItvsjUL4wBgs4zeXroTEGwJfx_CX7c3fC2S1Pwk,1323
2
+ pygeoapi_yaml/provider.py,sha256=Lx2_z81AmkJzkVtncQrjVWVytKwMwMUJLOKmwWfdug8,23551
3
+ pygeoapi_yaml-0.1.0.dist-info/licenses/LICENSE,sha256=Q-yr4mviJEk1P9QAH38mYitAwOhWN3ljmj1Hy___5bE,1083
4
+ pygeoapi_yaml-0.1.0.dist-info/METADATA,sha256=EZkJt53X985NOi1o9uZhjVdPHT6kDov75akA3APPWeY,9574
5
+ pygeoapi_yaml-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
6
+ pygeoapi_yaml-0.1.0.dist-info/top_level.txt,sha256=mhh-xuBjEIPWsOB_CcwvwFBW8ieUrBuV_U31oQ7qwn4,14
7
+ pygeoapi_yaml-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -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 @@
1
+ pygeoapi_yaml