Skip to content

Commit a81e00d

Browse files
committed
update docs
1 parent 4e37f61 commit a81e00d

File tree

4 files changed

+129
-5
lines changed

4 files changed

+129
-5
lines changed

README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@
3434

3535
## Description
3636

37-
`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.
37+
`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.
3838

3939
## Install
4040

docs/mkdocs.yml

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,9 @@ extra:
2222
# Layout
2323
nav:
2424
- Home: 'index.md'
25-
- Usage: 'usage.md'
25+
- Intro: 'intro.md'
26+
- Migration guides:
27+
- v0.6 -> v1.0: migrations/v1.0_migration.md
2628
- Development - Contributing: 'contributing.md'
2729
- Release: 'release-notes.md'
2830

docs/src/usage.md renamed to docs/src/intro.md

Lines changed: 22 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,25 @@ assert type(fc.features[0].geometry) == Point
2828
assert fc.features[0].properties["name"] == "jeff"
2929
```
3030

31-
### Advanced usage
31+
## Geometry Model methods and properties
32+
33+
- `__geo_interface__`: GeoJSON-like protocol for geo-spatial (GIS) vector data ([spec](https://gist.github.com/sgillies/2217756#__geo_interface)).
34+
- `has_z`: returns true if any coordinate has a Z value.
35+
- `wkt`: returns the Well Known Text representation of the geometry.
36+
37+
##### For Polygon geometry
38+
39+
- `exterior`: returns the exterior Linear Ring of the polygon.
40+
- `interiors`: returns the interiors (Holes) of the polygon.
41+
- `Polygon.from_bounds(xmin, ymin, xmax, ymax)`: creates a Polygon geometry from a bounding box.
42+
43+
##### For GeometryCollection and FeatureCollection
44+
45+
- `__iter__`: iterates over geometries or features
46+
- `__len__`: returns geometries or features count
47+
- `__getitem__(index)`: gets geometry or feature at a given index
48+
49+
## Advanced usage
3250

3351
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.
3452

@@ -103,12 +121,13 @@ assert MyPointFeatureModel(type="Feature", geometry=Point(type="Point", coordina
103121
And now with constrained properties
104122

105123
```python
124+
from typing import Annotated
106125
from geojson_pydantic import Feature, Point
107-
from pydantic import BaseModel, constr
126+
from pydantic import BaseModel
108127

109128
# Define a Feature model with Geometry as `Point` and Properties as a constrained Model
110129
class MyProps(BaseModel):
111-
name: constr(pattern=r'^(drew|vincent)$')
130+
name: Annotated[str, Field(pattern=r"^(drew|vincent)$")]
112131

113132
MyPointFeatureModel = Feature[Point, MyProps]
114133

docs/src/migrations/v1.0_migration.md

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
`geojson-pydantic` version 1.0 introduced [many breaking changes](../release-notes.md). This
2+
document aims to help with migrating your code to use `geojson-pydantic` 1.0.
3+
4+
5+
## Pydantic 2.0
6+
7+
The biggest update introduced in **1.0** is the new pydantic *major* version requirement [**~2.0**](https://docs.pydantic.dev/2.0/migration/).
8+
9+
In addition to being faster, this new major version has plenty of new API which we used in `geojson-pydantic` (like the new `model_serializer` method).
10+
11+
```python
12+
13+
from geojson_pydantic import Point
14+
15+
# Before
16+
Point.dict() # serialize to dict object
17+
Point.json() # serialize to json string
18+
19+
with open("point.geojson") as f:
20+
Point.parse_file(f) # parse file content to model
21+
22+
p = {}
23+
Point.parse_obj(obj) # parse dict object
24+
25+
##################
26+
# Now (geojson-pydantic ~= 1.0)
27+
28+
Point.model_dump()
29+
Point.model_dump_json()
30+
31+
with open("point.geojson") as f:
32+
Point.model_validate_json(f.read())
33+
34+
p = {}
35+
Point.model_validate(obj)
36+
```
37+
38+
ref: https://github.com/developmentseed/geojson-pydantic/pull/130
39+
40+
## FeatureCollection Generic model
41+
42+
In **1.0** we updated the generic FeatureCollection model to depends only on a generic Feature model.
43+
44+
```python
45+
# Before
46+
FeatureCollection[Geometry, Properties]
47+
48+
# Now (geojson-pydantic ~= 1.0)
49+
FeatureCollection[Feature[Geometry, Properties]]
50+
```
51+
52+
e.g
53+
54+
```python
55+
from pydantic import BaseModel
56+
from geojson_pydantic import Feature, FeatureCollection, Polygon
57+
58+
class CustomProperties(BaseModel):
59+
id: str
60+
description: str
61+
size: int
62+
63+
# Create a new FeatureCollection Model which should only
64+
# Accept Features with Polygon geometry type and matching the properties
65+
MyFc = FeatureCollection[Feature[Polygon, CustomProperties]]
66+
```
67+
68+
ref: https://github.com/developmentseed/geojson-pydantic/issues/134
69+
70+
## Exclude `bbox` and `id` if null
71+
72+
Using the new pydantic `model_serializer` method, we are now able to `customize` JSON output for the models to better match the GeoJSON spec
73+
74+
```python
75+
# Before
76+
Point(type="Point", coordinates=[0, 0]).json()
77+
>> '{"type":"Point","coordinates":[0.0,0.0],"bbox":null}'
78+
79+
# Now (geojson-pydantic ~= 1.0)
80+
Point(type="Point", coordinates=[0, 0]).model_dump_json()
81+
>> '{"type":"Point","coordinates":[0.0,0.0]}'
82+
```
83+
84+
ref: https://github.com/developmentseed/geojson-pydantic/issues/125
85+
86+
87+
## Change in WKT output for Multi* geometries
88+
89+
```python
90+
from geojson_pydantic import MultiPoint
91+
92+
geom = MultiPoint(type='MultiPoint', coordinates=[(1.0, 2.0, 3.0)])
93+
94+
# Before
95+
print(geom.wkt)
96+
>> MULTIPOINT Z (1 2 3)
97+
98+
# Now (geojson-pydantic ~= 1.0)
99+
print(geom.wkt)
100+
>> MULTIPOINT Z ((1 2 3))
101+
```
102+
103+
ref: https://github.com/developmentseed/geojson-pydantic/issues/139

0 commit comments

Comments
 (0)