Typing Stubs for Shapely

Warnings

• gotcha Ensure the version of `types-shapely` is compatible with your installed `shapely` version. `types-shapely` is typically tied to major/minor versions (e.g., `2.1.*`) of the `shapely` library it types. Using mismatched versions can lead to incorrect type checking results.
  Fix: Always install `types-shapely` alongside a compatible `shapely` version, e.g., `pip install 'shapely==2.1.*' types-shapely`. Check the `types-shapely` PyPI page for the specific `shapely` version it aims to annotate.
• breaking Shapely 2.0 introduced significant changes, making geometries immutable and hashable. Code that mutates geometry objects in-place or relies on them being sequences (e.g., iterating over `MultiPolygon` directly) will break. `types-shapely` reflects these API changes.
  Fix: Review Shapely's migration guide for versions 1.8 to 2.0. Instead of in-place mutation, create new geometry objects. For multi-part geometries, use the `.geoms` property for iteration.
• deprecated The `.type` attribute on Shapely geometry objects is deprecated and will be removed. Use `.geom_type` instead.
  Fix: Replace all instances of `geometry.type` with `geometry.geom_type`.
• gotcha When accessing coordinates (e.g., `polygon.exterior.coords`), type checkers might infer generic `Tuple[float, ...]` which could be `Tuple[float, float]` or `Tuple[float, float, float]` depending on the presence of Z-coordinates. If your code assumes a 2D tuple but Z-coordinates are possible, type errors might occur.
  Fix: If you are certain about the dimensionality, use `typing.cast` for explicit type assertion (e.g., `cast(List[Tuple[float, float]], polygon.exterior.coords)`). Alternatively, handle 2D and 3D coordinates explicitly in your logic.
• breaking In Shapely 2.0+, the creation of empty geometries is consistent, returning an empty geometry of the specified type (e.g., `Polygon()`) rather than an empty `GeometryCollection`. Code that relies on empty geometries always being `GeometryCollection` will be incorrect.
  Fix: Do not rely on empty geometries being `GeometryCollection`. Use the `.is_empty` attribute for robustly checking if a geometry object is empty.

Install

• pip install types-shapely Install types-shapely
• pip install "shapely==2.1.*" types-shapely Install compatible Shapely and stubs

Imports

• Point

  from shapely.geometry import Point

  Typing stubs are automatically picked up by type checkers; you import from the original library (`shapely`), not `types_shapely`.
• Polygon

  from shapely.geometry import Polygon

  Typing stubs are automatically picked up by type checkers; you import from the original library (`shapely`), not `types_shapely`.

Quickstart

This quickstart demonstrates how to use `types-shapely` to enable static type checking for `shapely` code. After installing `shapely` and `types-shapely`, you can write your Python code with type annotations for Shapely objects. A type checker like MyPy will then use the provided stubs to validate your code.

import sys
import os

# Ensure shapely and types-shapely are installed
# For demonstration, we use a mock shell command
# In a real scenario, these would be in requirements.txt or pre-installed
if os.environ.get('SKIP_INSTALL', 'false').lower() != 'true':
    # This part is for demonstration only to show expected installs.
    # In a real environment, you'd just install via pip before running mypy.
    # Example of how you'd install (not executed directly here for safety):
    # print("Installing shapely and types-shapely (mock)...\n")
    # os.system(f'{sys.executable} -m pip install shapely types-shapely mypy')
    pass

from shapely.geometry import Point, Polygon
from typing import List, Tuple

def create_and_buffer_point(x: float, y: float, radius: float) -> Polygon:
    """Creates a point and buffers it."""
    point: Point = Point(x, y)
    buffered_polygon: Polygon = point.buffer(radius)
    return buffered_polygon

def get_polygon_area(poly: Polygon) -> float:
    """Returns the area of a polygon."""
    return poly.area

# Example usage
my_point = Point(0.0, 0.0)
my_polygon = create_and_buffer_point(0.0, 0.0, 10.0)
area = get_polygon_area(my_polygon)
print(f"Original point: {my_point}")
print(f"Buffered polygon: {my_polygon}")
print(f"Polygon area: {area}")

# To run type checking using mypy:
# 1. Save the above code as `main.py`
# 2. Ensure `shapely`, `types-shapely`, and `mypy` are installed:
#    `pip install shapely types-shapely mypy`
# 3. Run mypy from your terminal:
#    `mypy main.py`
# Expected output (if no type errors):
#    `Success: No issues found in 1 source file`