.. |CI-status-badge| image:: https://img.shields.io/github/actions/workflow/status/Peter-van-Tol/pydantic-shapely/pytest.yml?branch=main&logo=github&label=CI
:target: https://github.com/Peter-van-Tol/pydantic-shapely/actions
.. |version-badge| image:: https://img.shields.io/pypi/v/pydantic-shapely.svg
:target: https://pypi.org/project/pydantic-shapely/
.. |downloads-badge| image:: https://static.pepy.tech/badge/pydantic-shapely/month
:target: https://pepy.tech/project/pydantic-shapely
.. |pyversions-badge| image:: https://img.shields.io/pypi/pyversions/pydantic-shapely.svg
:target: https://github.com/Peter-van-Tol/pydantic-shapely
.. |license-badge| image:: https://img.shields.io/github/license/Peter-van-Tol/pydantic-shapely.svg
:target: https://github.com/Peter-van-Tol/pydantic-shapely/blob/main/LICENSE
|CI-status-badge| |version-badge| |downloads-badge| |pyversions-badge| |license-badge|
================
pydantic-shapely
================
Letting two great packages work together!
``pydantic-shapely`` is a Python package that allows you to use Shapely geometries as Pydantic
fields. This package is useful when you want to validate and serialize Shapely geometries using
Pydantic models. As an added bonus, you can also use the package to validate and serialize the
geometries in GeoJSON format, without the need of any additional code. The GeoJSON serialization
is based on the `GeoJSON specification <https://tools.ietf.org/html/rfc7946>`_.
Installation
------------
You can install the package using pip:
.. code-block:: shell
pip install pydantic-shapely
Ofcourse, you can also install the package using `poetry <https://python-poetry.org/>`_ as
package manager:
.. code-block:: shell
poetry add pydantic-shapely
Basic usage
-----------
Normally, when you want to use Shapely geometries in Pydantic models, you would have
to set ``arbitrary_types_allowed`` to ``True`` in the Pydantic model. This is because
the Shapely geometries are not natively supported by Pydantic.
With ``pydantic-shapely`` you can use Shapely geometries as Pydantic fields without
having to set ``arbitrary_types_allowed`` to ``True``. You only have to add the
``GeometryField`` as _additional_ annotation to the field in the Pydantic model.
.. code-block:: python
import typing
from pydantic import BaseModel
from pydantic_shapely import GeometryField
from shapely.geometry import Point
class MyModel(BaseModel):
point: typing.Annotation[Point, GeometryField(), Field(...)]
model = MyModel(point=Point(0, 0))
print(model.point) # POINT (0 0)
With the ``GeometryField`` allows also to set the following parameters whether the geometry
should be 2- or 3-dimensional with the parameter ``z_values``. The following values are
allowed:
- ``forbidden``: the geometry must be strictly 2-dimensional. A ValueError will
raised when a shape with z-values is provided.
- ``strip``: the geometry may have z-values. These values will be stripped from
then geometry in the validation process. The resulting shape will be
2-dimensional in all cases.
- ``allow`` (default): both 2- and 3-dimensional values are allowed. During the
validation process the data is not altered. This is the default behavior.
- ``required``: the geometry must be strictly 2-dimensional. A ValueError will
raised when a shape without z-values is provided.
GeoJSON serialization
---------------------
With ``pydantic-shapely`` you can also serialize the a Pydantic model with a Shapely geometry
to GeoJSON format.
GeoJSON features
~~~~~~~~~~~~~~~~
In order to add this functionality to your model, you have to inherit from the ``FeatureBaseModel``
class. This class is a subclass of the Pydantic ``BaseModel`` class and adds the following methods
and attributes to the model:
- ``GeoJsonDataModel``: an attribute that contains the Pydantic GeoJSON model based on the
original model. This model is created when the subclass is created.
- ``to_geojson_model``: a method that returns the GeoJSON model of the model instance. To convert
the GeoJSON model back to the original model, you can use the ``to_feature_model`` method on
the GeoJSON model.
- ``model_dump_geojson``: a method that serializes the model to GeoJSON format.
Example usage of the GeoJSON serialization:
.. code-block:: python
import typing
from pydantic import BaseModel
from pydantic_shapely import GeometryField, FeatureBaseModel
from shapely.geometry import Point
class MyModel(FeatureBaseModel, geometry_field="point"):
point: typing.Annotation[Point, GeometryField(), Field(...)]
a: int = 42
b: str = "Hello, World!"
model = MyModel(point=Point(0, 0))
print(model.model_dump_geojson())
# {
# "type": "Feature",
# "geometry": {
# "type": "Point",
# "coordinates": [0.0, 0.0]
# },
# "properties": {
# "a": 42,
# "b": "Hello, World!"}
# }
The GeoJSON serialization can also be used with FastApi. The following example shows how to
create a simple annotated API that returns a GeoJSON representation of a Shapely geometry:
.. code-block:: python
import typing
from fastapi import FastAPI
from pydantic import Field
from pydantic_shapely import FeatureBaseModel, GeometryField
from shapely.geometry import Point
app = FastAPI()
class MyModel(FeatureBaseModel, geometry_field="point"):
point: typing.Annotated[Point, GeometryField(), Field(...)]
@app.get("/point")
def get_point() -> MyModel.GeoJsonDataModel:
# Return a GeoJSON representation of a Shapely geometry.
return MyModel(point=Point(0, 0)).to_geojson_model()
@app.post("/point")
def post_point(model: MyModel.GeoJsonDataModel) -> MyModel:
# Convert the GeoJSON model back to the original model instance with the
# `to_feature_model` method. The Shapely geometry will be returned as a
# WKT-string in this case.
return model.to_feature_model()
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=8000)
GeoJSON feature collections
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Based on the ``GeoJsonDataModel``, a feature collection can be easily created by using the
``FeatureCollectionBaseModel`` class. This class is a subclass of the Pydantic ``BaseModel``
class and adds the following methods and attributes to the model:
- ``from_feature_models``: a class method that creates a feature collection from a list of features.
The list of features is validated before the feature collection is created. The validation
ensures that all features are of the correct type.
- ``to_feature_models``: a method that returns a list of feature models from the feature collection.
Example usage of the feature collection:
.. code-block:: python
import typing
from shapely import Point
from pydantic_shapely import FeatureBaseModel, GeometryField
from pydantic_shapely.geojson import GeoJsonFeatureCollectionBaseModel
class TestModel(FeatureBaseModel):
"""Test class for a feature which supports GeoJSON serialization."""
geometry: typing.Annotated[Point, GeometryField()]
name: str = "Hello World"
answer: int = 42
TestFeatureCollection = GeoJsonFeatureCollectionBaseModel[TestModel.GeoJsonDataModel]
# Method 1: Create a feature collection from a list of features.
test = TestFeatureCollection(
features=[
TestModel(geometry=Point(0, 0)).to_geojson_model(),
TestModel(geometry=Point(1, 1)).to_geojson_model(),
]
)
# Method 2: Create a feature collection from a list features using the `from_feature_models`
# class method.
test = TestFeatureCollection.from_feature_models(
[
TestModel(geometry=Point(0, 0)),
TestModel(geometry=Point(1, 1)),
]
)
# Print the resluting GeoJSON feature collection.
print(test.model_dump_json(indent=2))
# RESULT:
# {
# "type": "FeatureCollection",
# "features": [
# {
# "type": "Feature",
# "geometry": {
# "type": "Point",
# "coordinates": [
# 0.0,
# 0.0
# ]
# },
# "properties": {
# "name": "Hello World",
# "answer": 42
# }
# },
# {
# "type": "Feature",
# "geometry": {
# "type": "Point",
# "coordinates": [
# 1.0,
# 1.0
# ]
# },
# "properties": {
# "name": "Hello World",
# "answer": 42
# }
# }
# ]
# }
The GeoJSON serialization can also be used with FastApi. The following example shows how to
create a simple annotated API that returns a GeoJSON Feature Collection:
.. code-block:: python
import typing
from fastapi import FastAPI
from pydantic import Field
from pydantic_shapely import FeatureBaseModel, GeometryField
from pydantic_shapely.geojson import GeoJsonFeatureCollectionBaseModel
from shapely.geometry import Point
app = FastAPI()
class MyModel(FeatureBaseModel, geometry_field="point"):
point: typing.Annotated[Point, GeometryField(), Field(...)]
name: str = "Hello World"
answer: int = 42
# NOTE: Sub-classing the GeoJsonFeatureCollectionBaseModel gives a cleaner description
# in the API documentation.
class MyModelFeatureCollection(GeoJsonFeatureCollectionBaseModel[MyModel.GeoJsonDataModel]):
...
@app.get("/points")
def get_points() -> MyModelFeatureCollection:
# Return a GeoJSON representation of a Shapely geometry.
return MyModelFeatureCollection.from_feature_models(
[
MyModel(point=Point(0, 0)).to_geojson_model(),
MyModel(point=Point(1, 1)).to_geojson_model(),
]
)
@app.post("/points")
def post_points(model: MyModelFeatureCollection) -> typing.List[MyModel]:
# Convert the GeoJSON model back to the original model instance with the
# `to_feature_model` method. The Shapely geometry will be returned as a
# WKT-string in this case.
return model.to_feature_models()
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=8000)
Work in progress
----------------
This package is still in development. The following features are planned for the future:
- Adding more options for the ``GeometryField`` annotation. For example, the ability to
set a bounding box for the geometry.
- Adding the CRS to the both ``GeometryField`` and the GeoJSON serialization. This functionality
will automatically transform the geometries to the specified CRS.
Allthough the package is still in development, the current features are tested and ready
for use. The signature of the methods and classes will not change in the future. If you have
any suggestions or questions, feel free to open an issue on the
`GitHub repository <https://github.com/Peter-van-Tol/pydantic-shapely>`_.
Raw data
{
"_id": null,
"home_page": "https://github.com/Peter-van-Tol/pydantic-shapely",
"name": "pydantic-shapely",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Peter van Tol",
"author_email": "peter.van.tol@witteveenbos.com",
"download_url": "https://files.pythonhosted.org/packages/99/7d/4b57c303d14bcb83736fd2e55a77b5504108740e1ff3eed51418c8ec06b7/pydantic_shapely-1.0.0a4.tar.gz",
"platform": null,
"description": ".. |CI-status-badge| image:: https://img.shields.io/github/actions/workflow/status/Peter-van-Tol/pydantic-shapely/pytest.yml?branch=main&logo=github&label=CI\n :target: https://github.com/Peter-van-Tol/pydantic-shapely/actions \n.. |version-badge| image:: https://img.shields.io/pypi/v/pydantic-shapely.svg\n :target: https://pypi.org/project/pydantic-shapely/\n.. |downloads-badge| image:: https://static.pepy.tech/badge/pydantic-shapely/month\n :target: https://pepy.tech/project/pydantic-shapely\n.. |pyversions-badge| image:: https://img.shields.io/pypi/pyversions/pydantic-shapely.svg\n :target: https://github.com/Peter-van-Tol/pydantic-shapely\n.. |license-badge| image:: https://img.shields.io/github/license/Peter-van-Tol/pydantic-shapely.svg\n :target: https://github.com/Peter-van-Tol/pydantic-shapely/blob/main/LICENSE\n\n|CI-status-badge| |version-badge| |downloads-badge| |pyversions-badge| |license-badge|\n\n================\npydantic-shapely\n================\n\n\n Letting two great packages work together!\n\n\n``pydantic-shapely`` is a Python package that allows you to use Shapely geometries as Pydantic\nfields. This package is useful when you want to validate and serialize Shapely geometries using\nPydantic models. As an added bonus, you can also use the package to validate and serialize the\ngeometries in GeoJSON format, without the need of any additional code. The GeoJSON serialization\nis based on the `GeoJSON specification <https://tools.ietf.org/html/rfc7946>`_.\n\nInstallation\n------------\n\nYou can install the package using pip:\n\n.. code-block:: shell\n\n pip install pydantic-shapely\n\nOfcourse, you can also install the package using `poetry <https://python-poetry.org/>`_ as \npackage manager:\n\n.. code-block:: shell\n\n poetry add pydantic-shapely\n\nBasic usage\n-----------\n\nNormally, when you want to use Shapely geometries in Pydantic models, you would have\nto set ``arbitrary_types_allowed`` to ``True`` in the Pydantic model. This is because\nthe Shapely geometries are not natively supported by Pydantic. \n\nWith ``pydantic-shapely`` you can use Shapely geometries as Pydantic fields without\nhaving to set ``arbitrary_types_allowed`` to ``True``. You only have to add the\n``GeometryField`` as _additional_ annotation to the field in the Pydantic model.\n\n.. code-block:: python\n\n import typing\n from pydantic import BaseModel\n from pydantic_shapely import GeometryField\n from shapely.geometry import Point\n\n class MyModel(BaseModel):\n point: typing.Annotation[Point, GeometryField(), Field(...)]\n\n model = MyModel(point=Point(0, 0))\n print(model.point) # POINT (0 0)\n\nWith the ``GeometryField`` allows also to set the following parameters whether the geometry\nshould be 2- or 3-dimensional with the parameter ``z_values``. The following values are\nallowed:\n\n- ``forbidden``: the geometry must be strictly 2-dimensional. A ValueError will\n raised when a shape with z-values is provided.\n- ``strip``: the geometry may have z-values. These values will be stripped from\n then geometry in the validation process. The resulting shape will be\n 2-dimensional in all cases.\n- ``allow`` (default): both 2- and 3-dimensional values are allowed. During the\n validation process the data is not altered. This is the default behavior.\n- ``required``: the geometry must be strictly 2-dimensional. A ValueError will\n raised when a shape without z-values is provided.\n\nGeoJSON serialization\n---------------------\nWith ``pydantic-shapely`` you can also serialize the a Pydantic model with a Shapely geometry\nto GeoJSON format. \n\nGeoJSON features\n~~~~~~~~~~~~~~~~\n\nIn order to add this functionality to your model, you have to inherit from the ``FeatureBaseModel``\nclass. This class is a subclass of the Pydantic ``BaseModel`` class and adds the following methods\nand attributes to the model:\n\n- ``GeoJsonDataModel``: an attribute that contains the Pydantic GeoJSON model based on the \n original model. This model is created when the subclass is created.\n- ``to_geojson_model``: a method that returns the GeoJSON model of the model instance. To convert\n the GeoJSON model back to the original model, you can use the ``to_feature_model`` method on\n the GeoJSON model.\n- ``model_dump_geojson``: a method that serializes the model to GeoJSON format.\n\nExample usage of the GeoJSON serialization:\n\n.. code-block:: python\n\n import typing\n from pydantic import BaseModel\n from pydantic_shapely import GeometryField, FeatureBaseModel\n from shapely.geometry import Point\n\n class MyModel(FeatureBaseModel, geometry_field=\"point\"):\n point: typing.Annotation[Point, GeometryField(), Field(...)]\n a: int = 42\n b: str = \"Hello, World!\"\n\n model = MyModel(point=Point(0, 0))\n print(model.model_dump_geojson())\n # {\n # \"type\": \"Feature\",\n # \"geometry\": {\n # \"type\": \"Point\",\n # \"coordinates\": [0.0, 0.0]\n # },\n # \"properties\": {\n # \"a\": 42,\n # \"b\": \"Hello, World!\"}\n # }\n\nThe GeoJSON serialization can also be used with FastApi. The following example shows how to\ncreate a simple annotated API that returns a GeoJSON representation of a Shapely geometry:\n\n.. code-block:: python\n\n import typing\n from fastapi import FastAPI\n from pydantic import Field\n from pydantic_shapely import FeatureBaseModel, GeometryField\n from shapely.geometry import Point\n\n app = FastAPI()\n\n class MyModel(FeatureBaseModel, geometry_field=\"point\"):\n point: typing.Annotated[Point, GeometryField(), Field(...)]\n\n @app.get(\"/point\")\n def get_point() -> MyModel.GeoJsonDataModel:\n # Return a GeoJSON representation of a Shapely geometry.\n return MyModel(point=Point(0, 0)).to_geojson_model()\n\n @app.post(\"/point\")\n def post_point(model: MyModel.GeoJsonDataModel) -> MyModel:\n # Convert the GeoJSON model back to the original model instance with the\n # `to_feature_model` method. The Shapely geometry will be returned as a\n # WKT-string in this case.\n return model.to_feature_model()\n\n if __name__ == \"__main__\":\n import uvicorn\n uvicorn.run(app, host=\"0.0.0.0\", port=8000)\n\n\nGeoJSON feature collections\n~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nBased on the ``GeoJsonDataModel``, a feature collection can be easily created by using the\n``FeatureCollectionBaseModel`` class. This class is a subclass of the Pydantic ``BaseModel``\nclass and adds the following methods and attributes to the model:\n\n- ``from_feature_models``: a class method that creates a feature collection from a list of features.\n The list of features is validated before the feature collection is created. The validation\n ensures that all features are of the correct type.\n- ``to_feature_models``: a method that returns a list of feature models from the feature collection.\n\nExample usage of the feature collection:\n\n.. code-block:: python\n\n import typing\n from shapely import Point\n\n from pydantic_shapely import FeatureBaseModel, GeometryField\n from pydantic_shapely.geojson import GeoJsonFeatureCollectionBaseModel\n\n\n class TestModel(FeatureBaseModel):\n \"\"\"Test class for a feature which supports GeoJSON serialization.\"\"\"\n\n geometry: typing.Annotated[Point, GeometryField()]\n name: str = \"Hello World\"\n answer: int = 42\n\n\n TestFeatureCollection = GeoJsonFeatureCollectionBaseModel[TestModel.GeoJsonDataModel]\n\n # Method 1: Create a feature collection from a list of features.\n test = TestFeatureCollection(\n features=[\n TestModel(geometry=Point(0, 0)).to_geojson_model(),\n TestModel(geometry=Point(1, 1)).to_geojson_model(),\n ]\n )\n # Method 2: Create a feature collection from a list features using the `from_feature_models`\n # class method.\n test = TestFeatureCollection.from_feature_models(\n [\n TestModel(geometry=Point(0, 0)),\n TestModel(geometry=Point(1, 1)),\n ]\n )\n\n # Print the resluting GeoJSON feature collection.\n print(test.model_dump_json(indent=2))\n # RESULT:\n # {\n # \"type\": \"FeatureCollection\",\n # \"features\": [\n # {\n # \"type\": \"Feature\",\n # \"geometry\": {\n # \"type\": \"Point\",\n # \"coordinates\": [\n # 0.0,\n # 0.0\n # ]\n # },\n # \"properties\": {\n # \"name\": \"Hello World\",\n # \"answer\": 42\n # }\n # },\n # {\n # \"type\": \"Feature\",\n # \"geometry\": {\n # \"type\": \"Point\",\n # \"coordinates\": [\n # 1.0,\n # 1.0\n # ]\n # },\n # \"properties\": {\n # \"name\": \"Hello World\",\n # \"answer\": 42\n # }\n # }\n # ]\n # }\n\nThe GeoJSON serialization can also be used with FastApi. The following example shows how to\ncreate a simple annotated API that returns a GeoJSON Feature Collection:\n\n.. code-block:: python\n\n import typing\n from fastapi import FastAPI\n from pydantic import Field\n from pydantic_shapely import FeatureBaseModel, GeometryField\n from pydantic_shapely.geojson import GeoJsonFeatureCollectionBaseModel\n from shapely.geometry import Point\n\n app = FastAPI()\n\n class MyModel(FeatureBaseModel, geometry_field=\"point\"):\n point: typing.Annotated[Point, GeometryField(), Field(...)]\n name: str = \"Hello World\"\n answer: int = 42\n\n \n # NOTE: Sub-classing the GeoJsonFeatureCollectionBaseModel gives a cleaner description\n # in the API documentation.\n class MyModelFeatureCollection(GeoJsonFeatureCollectionBaseModel[MyModel.GeoJsonDataModel]):\n ...\n\n \n @app.get(\"/points\")\n def get_points() -> MyModelFeatureCollection:\n # Return a GeoJSON representation of a Shapely geometry.\n return MyModelFeatureCollection.from_feature_models(\n [\n MyModel(point=Point(0, 0)).to_geojson_model(),\n MyModel(point=Point(1, 1)).to_geojson_model(),\n ]\n )\n\n @app.post(\"/points\")\n def post_points(model: MyModelFeatureCollection) -> typing.List[MyModel]:\n # Convert the GeoJSON model back to the original model instance with the\n # `to_feature_model` method. The Shapely geometry will be returned as a\n # WKT-string in this case.\n return model.to_feature_models()\n\n if __name__ == \"__main__\":\n import uvicorn\n uvicorn.run(app, host=\"0.0.0.0\", port=8000)\n\nWork in progress\n----------------\nThis package is still in development. The following features are planned for the future:\n\n- Adding more options for the ``GeometryField`` annotation. For example, the ability to\n set a bounding box for the geometry.\n- Adding the CRS to the both ``GeometryField`` and the GeoJSON serialization. This functionality\n will automatically transform the geometries to the specified CRS.\n\nAllthough the package is still in development, the current features are tested and ready\nfor use. The signature of the methods and classes will not change in the future. If you have\nany suggestions or questions, feel free to open an issue on the \n`GitHub repository <https://github.com/Peter-van-Tol/pydantic-shapely>`_.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Letting two great packages work together!",
"version": "1.0.0a4",
"project_urls": {
"Homepage": "https://github.com/Peter-van-Tol/pydantic-shapely",
"Repository": "https://github.com/Peter-van-Tol/pydantic-shapely"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2fc758f2ae64d1c84c7cb3214900ab31e33f167e5c942a579ed1aaf818d9f199",
"md5": "3a6974212d3e45631bb46a0e87e999d4",
"sha256": "95549da12e64c3e943c268cbc404c286f10ba1634424556ec208c10ba716fb02"
},
"downloads": -1,
"filename": "pydantic_shapely-1.0.0a4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3a6974212d3e45631bb46a0e87e999d4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 21658,
"upload_time": "2025-01-01T21:49:54",
"upload_time_iso_8601": "2025-01-01T21:49:54.905490Z",
"url": "https://files.pythonhosted.org/packages/2f/c7/58f2ae64d1c84c7cb3214900ab31e33f167e5c942a579ed1aaf818d9f199/pydantic_shapely-1.0.0a4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "997d4b57c303d14bcb83736fd2e55a77b5504108740e1ff3eed51418c8ec06b7",
"md5": "1d5e36d944ae7f628d771324d95d896e",
"sha256": "67d7b133dc92893812b0c20f99e909280f63639d4cd4703669f81971343065aa"
},
"downloads": -1,
"filename": "pydantic_shapely-1.0.0a4.tar.gz",
"has_sig": false,
"md5_digest": "1d5e36d944ae7f628d771324d95d896e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 17734,
"upload_time": "2025-01-01T21:49:59",
"upload_time_iso_8601": "2025-01-01T21:49:59.405221Z",
"url": "https://files.pythonhosted.org/packages/99/7d/4b57c303d14bcb83736fd2e55a77b5504108740e1ff3eed51418c8ec06b7/pydantic_shapely-1.0.0a4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-01 21:49:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Peter-van-Tol",
"github_project": "pydantic-shapely",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "pydantic-shapely"
}
JSON
