Skip to content

Commit 4e37f61

Browse files
vincentsaragovincentsarago
committed
add docs
1 parent b89a926 commit 4e37f61

File tree

8 files changed

+297
-174
lines changed

8 files changed

+297
-174
lines changed

‎.github/workflows/deploy_mkdocs.yml

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
name: Publish docs via GitHub Pages
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
paths:
8+
# Only rebuild website when docs have changed
9+
- 'README.md'
10+
- 'CHANGELOG.md'
11+
- 'CONTRIBUTING.md'
12+
- 'docs/**'
13+
14+
jobs:
15+
build:
16+
name: Deploy docs
17+
runs-on: ubuntu-latest
18+
steps:
19+
- name: Checkout main
20+
uses: actions/checkout@v2
21+
22+
- name: Set up Python 3.8
23+
uses: actions/setup-python@v2
24+
with:
25+
python-version: 3.8
26+
27+
- name: Install dependencies
28+
run: |
29+
python -m pip install --upgrade pip
30+
python -m pip install numpy
31+
python -m pip install .["docs"]
32+
33+
- name: Deploy docs
34+
run: mkdocs gh-deploy --force -f docs/mkdocs.yml

‎README.md

Lines changed: 10 additions & 174 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# geojson-pydantic
22

33
<p align="center">
4-
<em> <a href="https://pydantic-docs.helpmanual.io" target="_blank">Pydantic</a> models for GeoJSON.</em>
4+
<em> <a href="https://docs.pydantic.dev/latest/" target="_blank">Pydantic</a> models for GeoJSON.</em>
55
</p>
66
<p align="center">
77
<a href="https://github.com/developmentseed/geojson-pydantic/actions?query=workflow%3ACI" target="_blank">
@@ -24,6 +24,14 @@
2424
</a>
2525
</p>
2626

27+
---
28+
29+
**Documentation**: <a href="https://developmentseed.org/geojson-pydantic/" target="_blank">https://developmentseed.org/geojson-pydantic/</a>
30+
31+
**Source Code**: <a href="https://github.com/developmentseed/geojson-pydantic" target="_blank">https://github.com/developmentseed/geojson-pydantic</a>
32+
33+
---
34+
2735
## Description
2836

2937
`geojson_pydantic` provides a suite of Pydantic models matching the GeoJSON specification [rfc7946](https://datatracker.ietf.org/doc/html/rfc7946). Those models can be used for creating or validating geojson data.
@@ -48,181 +56,9 @@ Install with conda from [`conda-forge`](https://anaconda.org/conda-forge/geojson
4856
$ conda install -c conda-forge geojson-pydantic
4957
```
5058

51-
## Usage
52-
53-
```python
54-
from geojson_pydantic import Feature, FeatureCollection, Point
55-
56-
geojson_feature = {
57-
"type": "Feature",
58-
"geometry": {
59-
"type": "Point",
60-
"coordinates": [13.38272, 52.46385],
61-
},
62-
"properties": {
63-
"name": "jeff",
64-
},
65-
}
66-
67-
68-
feat = Feature(**geojson_feature)
69-
assert feat.type == "Feature"
70-
assert type(feat.geometry) == Point
71-
assert feat.properties["name"] == "jeff"
72-
73-
fc = FeatureCollection(type="FeatureCollection", features=[geojson_feature, geojson_feature])
74-
assert fc.type == "FeatureCollection"
75-
assert len(fc) == 2
76-
assert type(fc.features[0].geometry) == Point
77-
assert fc.features[0].properties["name"] == "jeff"
78-
```
79-
80-
### Advanced usage
81-
82-
In `geojson_pydantic` we've implemented pydantic's [Generic Models](https://pydantic-docs.helpmanual.io/usage/models/#generic-models) which allow the creation of more advanced models to validate either the geometry type or the properties.
83-
84-
In order to make use of this generic typing, there are two steps: first create a new model, then use that model to validate your data. To create a model using a `Generic` type, you **HAVE TO** pass `Type definitions` to the `Feature` model in form of `Feature[Geometry Type, Properties Type]`. Then pass your data to this constructor.
85-
86-
By default `Feature` and `FeatureCollections` are defined using `geojson_pydantic.geometries.Geometry` for the geometry and `typing.Dict` for the properties.
87-
88-
Here's an example where we want to validate that GeoJSON features have Polygon types, but don't do any specific property validation.
89-
90-
```python
91-
from typing import Dict
92-
93-
from geojson_pydantic import Feature, Polygon
94-
from pydantic import BaseModel
95-
96-
geojson_feature = {
97-
"type": "Feature",
98-
"geometry": {
99-
"type": "Point",
100-
"coordinates": [13.38272, 52.46385],
101-
},
102-
"properties": {
103-
"name": "jeff",
104-
},
105-
}
106-
107-
# Define a Feature model with Geometry as `Polygon` and Properties as `Dict`
108-
MyPolygonFeatureModel = Feature[Polygon, Dict]
109-
110-
feat = MyPolygonFeatureModel(**geojson_feature) # should raise Validation Error because `geojson_feature` is a point
111-
>>> ValidationError: 3 validation errors for Feature[Polygon, Dict]
112-
...
113-
geometry -> type
114-
unexpected value; permitted: 'Polygon' (type=value_error.const; given=Point; permitted=['Polygon'])
115-
116-
117-
geojson_feature = {
118-
"type": "Feature",
119-
"geometry": {
120-
"type": "Polygon",
121-
"coordinates": [
122-
[
123-
[13.38272, 52.46385],
124-
[13.42786, 52.46385],
125-
[13.42786, 52.48445],
126-
[13.38272, 52.48445],
127-
[13.38272, 52.46385],
128-
]
129-
],
130-
},
131-
"properties": {
132-
"name": "jeff",
133-
},
134-
}
135-
136-
feat = MyPolygonFeatureModel(**geojson_feature)
137-
assert type(feature.geometry) == Polygon
138-
```
139-
140-
Or with optional geometry
141-
142-
```python
143-
from geojson_pydantic import Feature, Point
144-
from typing import Optional
145-
146-
MyPointFeatureModel = Feature[Optional[Point], Dict]
147-
148-
assert MyPointFeatureModel(type="Feature", geometry=None, properties={}).geometry is None
149-
assert MyPointFeatureModel(type="Feature", geometry=Point(type="Point", coordinates=(0,0)), properties={}).geometry is not None
150-
```
151-
152-
And now with constrained properties
153-
154-
```python
155-
from geojson_pydantic import Feature, Point
156-
from pydantic import BaseModel, constr
157-
158-
# Define a Feature model with Geometry as `Point` and Properties as a constrained Model
159-
class MyProps(BaseModel):
160-
name: constr(pattern=r'^(drew|vincent)$')
161-
162-
MyPointFeatureModel = Feature[Point, MyProps]
163-
164-
geojson_feature = {
165-
"type": "Feature",
166-
"geometry": {
167-
"type": "Point",
168-
"coordinates": [13.38272, 52.46385],
169-
},
170-
"properties": {
171-
"name": "jeff",
172-
},
173-
}
174-
175-
feat = MyPointFeatureModel(**geojson_feature)
176-
>>> ValidationError: 1 validation error for Feature[Point, MyProps]
177-
properties -> name
178-
string does not match regex "^(drew|vincent)$" (type=value_error.str.regex; pattern=^(drew|vincent)$)
179-
180-
geojson_feature["properties"]["name"] = "drew"
181-
feat = MyPointFeatureModel(**geojson_feature)
182-
assert feat.properties.name == "drew"
183-
```
184-
185-
## Enforced Keys
186-
187-
Starting with version `0.6.0`, geojson-pydantic's classes will not define default keys such has `type`, `geometry` or `properties`.
188-
This is to make sure the library does well its first goal, which is `validating` GeoJSON object based on the [specification](https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.1)
189-
190-
o A GeoJSON object has a member with the name "type". The value of
191-
the member MUST be one of the GeoJSON types.
192-
193-
o A Feature object HAS a "type" member with the value "Feature".
194-
195-
o A Feature object HAS a member with the name "geometry". The value
196-
of the geometry member SHALL be either a Geometry object as
197-
defined above or, in the case that the Feature is unlocated, a
198-
JSON null value.
199-
200-
o A Feature object HAS a member with the name "properties". The
201-
value of the properties member is an object (any JSON object or a
202-
JSON null value).
203-
204-
205-
```python
206-
from geojson_pydantic import Point
207-
208-
## Before 0.6
209-
Point(coordinates=(0,0))
210-
>> Point(type='Point', coordinates=(0.0, 0.0), bbox=None)
211-
212-
## After 0.6
213-
Point(coordinates=(0,0))
214-
>> ValidationError: 1 validation error for Point
215-
type
216-
field required (type=value_error.missing)
217-
218-
Point(type="Point", coordinates=(0,0))
219-
>> Point(type='Point', coordinates=(0.0, 0.0), bbox=None)
220-
```
221-
222-
22359
## Contributing
22460

225-
See [CONTRIBUTING.md](CONTRIBUTING.md).
61+
See [CONTRIBUTING.md](https://github.com/developmentseed/geojson-pydantic/blob/main/CONTRIBUTING.md).
22662

22763
## Changes
22864

‎docs/mkdocs.yml

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Project Information
2+
site_name: 'geojson-pydantic'
3+
site_description: 'Pydantic models for GeoJSON'
4+
5+
docs_dir: 'src'
6+
site_dir: 'build'
7+
8+
# Repository
9+
repo_name: 'developmentseed/geojson-pydantic'
10+
repo_url: 'https://github.com/developmentseed/geojson-pydantic'
11+
edit_uri: 'blob/main/src/'
12+
site_url: 'https://developmentseed.org/geojson-pydantic/'
13+
14+
# Social links
15+
extra:
16+
social:
17+
- icon: 'fontawesome/brands/github'
18+
link: 'https://github.com/developmentseed'
19+
- icon: 'fontawesome/brands/twitter'
20+
link: 'https://twitter.com/developmentseed'
21+
22+
# Layout
23+
nav:
24+
- Home: 'index.md'
25+
- Usage: 'usage.md'
26+
- Development - Contributing: 'contributing.md'
27+
- Release: 'release-notes.md'
28+
29+
# Theme
30+
theme:
31+
icon:
32+
logo: 'material/home'
33+
repo: 'fontawesome/brands/github'
34+
name: 'material'
35+
language: 'en'
36+
palette:
37+
primary: 'pink'
38+
accent: 'light pink'
39+
font:
40+
text: 'Nunito Sans'
41+
code: 'Fira Code'
42+
43+
plugins:
44+
- search
45+
46+
# These extensions are chosen to be a superset of Pandoc's Markdown.
47+
# This way, I can write in Pandoc's Markdown and have it be supported here.
48+
# https://pandoc.org/MANUAL.html
49+
markdown_extensions:
50+
- admonition
51+
- attr_list
52+
- codehilite:
53+
guess_lang: false
54+
- def_list
55+
- footnotes
56+
- pymdownx.arithmatex
57+
- pymdownx.betterem
58+
- pymdownx.caret:
59+
insert: false
60+
- pymdownx.details
61+
- pymdownx.emoji
62+
- pymdownx.escapeall:
63+
hardbreak: true
64+
nbsp: true
65+
- pymdownx.magiclink:
66+
hide_protocol: true
67+
repo_url_shortener: true
68+
- pymdownx.smartsymbols
69+
- pymdownx.superfences
70+
- pymdownx.tasklist:
71+
custom_checkbox: true
72+
- pymdownx.tilde
73+
- toc:
74+
permalink: true

‎docs/src/contributing.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../CONTRIBUTING.md

‎docs/src/index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../README.md

‎docs/src/release-notes.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../CHANGELOG.md

0 commit comments

Comments
 (0)