Migrating to Shapely 1.8 / 2.0#

Shapely 1.8.0 is a transitional version introducing several warnings in preparation of the upcoming changes in 2.0.0.

Shapely 2.0.0 will be a major release with a refactor of the internals with considerable performance improvements (based on the developments in the PyGEOS package), along with several breaking changes.

This guide gives an overview of the most important changes with details on what will change in 2.0.0, how we warn for this in 1.8.0, and how you can update your code to be future-proof.

For more background, see RFC 1: Roadmap for Shapely 2.0.

Geometry objects will become immutable#

Geometry objects will become immutable in version 2.0.0.

In Shapely 1.x, some of the geometry classes are mutable, meaning that you can change their coordinates in-place. Illustrative code:

>>> from shapely.geometry import LineString
>>> line = LineString([(0,0), (2, 2)])
>>> print(line)
LINESTRING (0 0, 2 2)

>>> line.coords = [(0, 0), (10, 0), (10, 10)]
>>> print(line)
LINESTRING (0 0, 10 0, 10 10)

In Shapely 1.8, this will start raising a warning:

>>> line.coords = [(0, 0), (10, 0), (10, 10)]
ShapelyDeprecationWarning: Setting the 'coords' to mutate a Geometry
in place is deprecated, and will not be possible any more in Shapely 2.0

and starting with version 2.0.0, all geometry objects will become immutable. As a consequence, they will also become hashable and therefore usable as, for example, dictionary keys.

How do I update my code? There is no direct alternative for mutating the coordinates of an existing geometry, except for creating a new geometry object with the new coordinates.

Setting custom attributes#

Another consequence of the geometry objects becoming immutable is that assigning custom attributes, which currently works, will no longer be possible.

Currently you can do:

>>> line.name = "my_geometry"
>>> line.name
'my_geometry'

In Shapely 1.8, this will start raising a warning, and will raise an AttributeError in Shapely 2.0.

How do I update my code? There is no direct alternative for adding custom attributes to geometry objects. You can use other Python data structures such as (GeoJSON-like) dictionaries or GeoPandas’ GeoDataFrames to store attributes alongside geometry features.

Multi-part geometries will no longer be “sequences” (length, iterable, indexable)#

In Shapely 1.x, multi-part geometries (MultiPoint, MultiLineString, MultiPolygon and GeometryCollection) implement a part of the “sequence” python interface (making them list-like). This means you can iterate through the object to get the parts, index into the object to get a specific part, and ask for the number of parts with the len() method.

Some examples of this with Shapely 1.x:

>>> from shapely.geometry import Point, MultiPoint
>>> mp = MultiPoint([(1, 1), (2, 2), (3, 3)])
>>> print(mp)
MULTIPOINT (1 1, 2 2, 3 3)
>>> for part in mp:
...     print(part)
POINT (1 1)
POINT (2 2)
POINT (3 3)
>>> print(mp[1])
POINT (2 2)
>>> len(mp)
3
>>> list(mp)
[<shapely.geometry.point.Point at 0x7f2e0912bf10>,
 <shapely.geometry.point.Point at 0x7f2e09fed820>,
 <shapely.geometry.point.Point at 0x7f2e09fed4c0>]

Starting with Shapely 1.8, all the examples above will start raising a deprecation warning. For example:

>>> for part in mp:
...     print(part)
ShapelyDeprecationWarning: Iteration over multi-part geometries is deprecated
and will be removed in Shapely 2.0. Use the `geoms` property to access the
constituent parts of a multi-part geometry.
POINT (1 1)
POINT (2 2)
POINT (3 3)

In Shapely 2.0, all those examples will raise an error.

How do I update my code? To access the geometry parts of a multi-part geometry, you can use the .geoms attribute, as the warning indicates.

The examples above can be updated to:

>>> for part in mp.geoms:
...     print(part)
POINT (1 1)
POINT (2 2)
POINT (3 3)
>>> print(mp.geoms[1])
POINT (2 2)
>>> len(mp.geoms)
3
>>> list(mp.geoms)
[<shapely.geometry.point.Point at 0x7f2e0912bf10>,
 <shapely.geometry.point.Point at 0x7f2e09fed820>,
 <shapely.geometry.point.Point at 0x7f2e09fed4c0>]

The single-part geometries (Point, LineString, Polygon) already didn’t support those features, and for those classes there is no change in behaviour for this aspect.

Interoperability with NumPy and the array interface#

Conversion of the coordinates to (NumPy) arrays#

Shapely provides an array interface to have easy access to the coordinates as, for example, NumPy arrays (manual section).

A small example:

>>> line = LineString([(0, 0), (1, 1), (2, 2)])
>>> import numpy as np
>>> np.asarray(line)
array([[0., 0.],
       [1., 1.],
       [2., 2.]])

In addition, there are also the explicit array_interface() method and ctypes attribute to get access to the coordinates as array data:

>>> line.ctypes
<shapely.geometry.linestring.c_double_Array_6 at 0x7f75261eb740>
>>> line.array_interface()
{'version': 3,
 'typestr': '<f8',
 'data': <shapely.geometry.linestring.c_double_Array_6 at 0x7f752664ae40>,
 'shape': (3, 2)}

This functionality is available for Point, LineString, LinearRing and MultiPoint.

For more robust interoperability with NumPy, this array interface will be removed from those geometry classes, and limited to the coords.

Starting with Shapely 1.8, converting a geometry object to a NumPy array directly will start raising a warning:

>>> np.asarray(line)
ShapelyDeprecationWarning: The array interface is deprecated and will no longer
work in Shapely 2.0. Convert the '.coords' to a NumPy array instead.
array([[0., 0.],
       [1., 1.],
       [2., 2.]])

How do I update my code? To convert a geometry to a NumPy array, you can convert the .coords attribute instead:

>>> line.coords
<shapely.coords.CoordinateSequence at 0x7f2e09e88d60>
>>> np.array(line.coords)
array([[0., 0.],
       [1., 1.],
       [2., 2.]])

The array_interface() method and ctypes attribute will be removed in Shapely 2.0, but since Shapely will start requiring NumPy as a dependency, you can use NumPy or its array interface directly. Check the NumPy docs on the ctypes attribute or the array interface for more details.

Creating NumPy arrays of geometry objects#

Shapely geometry objects can be stored in NumPy arrays using the object dtype. In general, one could create such an array from a list of geometries as follows:

>>> from shapely.geometry import Point
>>> arr = np.array([Point(0, 0), Point(1, 1), Point(2, 2)])
>>> arr
array([<shapely.geometry.point.Point object at 0x7fb798407cd0>,
       <shapely.geometry.point.Point object at 0x7fb7982831c0>,
       <shapely.geometry.point.Point object at 0x7fb798283b80>],
      dtype=object)

The above works for point geometries, but because in Shapely 1.x, some geometry types are sequence-like (see above), NumPy can try to “unpack” them when creating an array. Therefore, for more robust creation of a NumPy array from a list of geometries, it’s generally recommended to this in a two-step way (first creating an empty array and then filling it):

geoms = [Point(0, 0), Point(1, 1), Point(2, 2)]
arr = np.empty(len(geoms), dtype="object")
arr[:] = geoms

This code snippet results in the same array as the example above, and works for all geometry types and Shapely/NumPy versions.

However, starting with Shapely 1.8, the above code will show deprecation warnings that cannot be avoided (depending on the geometry type, NumPy tries to access the array interface of the objects or check if an object is iterable or has a length, and those operations are all deprecated now. The end result is still correct, but the warnings appear nonetheless). Specifically in this case, it is fine to ignore those warnings (and the only way to make them go away):

import warnings
from shapely.errors import ShapelyDeprecationWarning

geoms = [Point(0, 0), Point(1, 1), Point(2, 2)]
arr = np.empty(len(geoms), dtype="object")

with warnings.catch_warnings():
    warnings.filterwarnings("ignore", category=ShapelyDeprecationWarning)
    arr[:] = geoms

In Shapely 2.0, the geometry objects will no longer be sequence like and those deprecation warnings will be removed (and thus the filterwarnings will no longer be necessary), and creation of NumPy arrays will generally be more robust.

If you maintain code that depends on Shapely, and you want to have it work with multiple versions of Shapely, the above code snippet provides a context manager that can be copied into your project:

import contextlib
import shapely
import warnings
from packaging import version  # https://packaging.pypa.io/

SHAPELY_GE_20 = version.parse(shapely.__version__) >= version.parse("2.0a1")

try:
    from shapely.errors import ShapelyDeprecationWarning as shapely_warning
except ImportError:
    shapely_warning = None

if shapely_warning is not None and not SHAPELY_GE_20:
    @contextlib.contextmanager
    def ignore_shapely2_warnings():
        with warnings.catch_warnings():
            warnings.filterwarnings("ignore", category=shapely_warning)
            yield
else:
    @contextlib.contextmanager
    def ignore_shapely2_warnings():
        yield

This can then be used when creating NumPy arrays (be careful to only use it for this specific purpose, and not generally suppress those warnings):

geoms = [...]
arr = np.empty(len(geoms), dtype="object")
with ignore_shapely2_warnings():
    arr[:] = geoms

Consistent creation of empty geometries#

Shapely 1.x is inconsistent in creating empty geometries between various creation methods. A small example for an empty Polygon geometry:

# Using an empty constructor results in a GeometryCollection
>>> from shapely.geometry import Polygon
>>> g1 = Polygon()
>>> type(g1)
<class 'shapely.geometry.polygon.Polygon'>
>>> g1.wkt
GEOMETRYCOLLECTION EMPTY

# Converting from WKT gives a correct empty polygon
>>> from shapely import wkt
>>> g2 = wkt.loads("POLYGON EMPTY")
>>> type(g2)
<class 'shapely.geometry.polygon.Polygon'>
>>> g2.wkt
POLYGON EMPTY

Shapely 1.8 does not yet change this inconsistent behaviour, but starting with Shapely 2.0, the different methods will always consistently give an empty geometry object of the correct type, instead of using an empty GeometryCollection as “generic” empty geometry object.

How do I update my code? Those cases that will change don’t raise a warning, but you will need to update your code if you rely on the fact that empty geometry objects are of the GeometryCollection type. Use the .is_empty attribute for robustly checking if a geometry object is an empty geometry.

In addition, the WKB serialization methods will start supporting empty Points (using "POINT (NaN NaN)" to represent an empty point).

Other deprecated functionality#

There are some other various functions and methods deprecated in Shapely 1.8 as well:

  • The adapters to create geometry-like proxy objects with coordinates stored outside Shapely geometries are deprecated and will be removed in Shapely 2.0 (e.g. created using asShape()). They have little to no benefit compared to the normal geometry classes, as thus you can convert to your data to a normal geometry object instead. Use the shape() function instead to convert a GeoJSON-like dict to a Shapely geometry.

  • The empty() method on a geometry object is deprecated.

  • The shapely.ops.cascaded_union function is deprecated. Use shapely.ops.unary_union instead, which internally already uses a cascaded union operation for better performance.