{"id":5821,"library":"types-shapely","title":"Typing Stubs for Shapely","description":"types-shapely provides PEP 561-compliant typing stubs for the Shapely library, enabling static type checking tools like MyPy and Pyright to analyze code that uses Shapely. It is part of the broader typeshed project and aims to provide accurate annotations for Shapely versions matching `2.1.*`. The package is actively maintained within the typeshed ecosystem, with new releases reflecting updates to the upstream Shapely library's API or improvements in type fidelity.","status":"active","version":"2.1.0.20260408","language":"en","source_language":"en","source_url":"https://github.com/python/typeshed/tree/main/stubs/shapely","tags":["types","typing","stubs","shapely","geometry","type-checking","geospatial"],"install":[{"cmd":"pip install types-shapely","lang":"bash","label":"Install types-shapely"},{"cmd":"pip install \"shapely==2.1.*\" types-shapely","lang":"bash","label":"Install compatible Shapely and stubs"}],"dependencies":[{"reason":"Provides type annotations for this library; typically, types-shapely should match the major/minor version of shapely (e.g., 2.1.*).","package":"shapely","optional":false}],"imports":[{"note":"Typing stubs are automatically picked up by type checkers; you import from the original library (`shapely`), not `types_shapely`.","symbol":"Point","correct":"from shapely.geometry import Point"},{"note":"Typing stubs are automatically picked up by type checkers; you import from the original library (`shapely`), not `types_shapely`.","symbol":"Polygon","correct":"from shapely.geometry import Polygon"}],"quickstart":{"code":"import sys\nimport os\n\n# Ensure shapely and types-shapely are installed\n# For demonstration, we use a mock shell command\n# In a real scenario, these would be in requirements.txt or pre-installed\nif os.environ.get('SKIP_INSTALL', 'false').lower() != 'true':\n    # This part is for demonstration only to show expected installs.\n    # In a real environment, you'd just install via pip before running mypy.\n    # Example of how you'd install (not executed directly here for safety):\n    # print(\"Installing shapely and types-shapely (mock)...\\n\")\n    # os.system(f'{sys.executable} -m pip install shapely types-shapely mypy')\n    pass\n\nfrom shapely.geometry import Point, Polygon\nfrom typing import List, Tuple\n\ndef create_and_buffer_point(x: float, y: float, radius: float) -> Polygon:\n    \"\"\"Creates a point and buffers it.\"\"\"\n    point: Point = Point(x, y)\n    buffered_polygon: Polygon = point.buffer(radius)\n    return buffered_polygon\n\ndef get_polygon_area(poly: Polygon) -> float:\n    \"\"\"Returns the area of a polygon.\"\"\"\n    return poly.area\n\n# Example usage\nmy_point = Point(0.0, 0.0)\nmy_polygon = create_and_buffer_point(0.0, 0.0, 10.0)\narea = get_polygon_area(my_polygon)\nprint(f\"Original point: {my_point}\")\nprint(f\"Buffered polygon: {my_polygon}\")\nprint(f\"Polygon area: {area}\")\n\n# To run type checking using mypy:\n# 1. Save the above code as `main.py`\n# 2. Ensure `shapely`, `types-shapely`, and `mypy` are installed:\n#    `pip install shapely types-shapely mypy`\n# 3. Run mypy from your terminal:\n#    `mypy main.py`\n# Expected output (if no type errors):\n#    `Success: No issues found in 1 source file`\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions of `types-shapely` (in relation to `shapely`)"},{"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.","message":"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.","severity":"breaking","affected_versions":"Shapely >= 2.0 (and types-shapely for these versions)"},{"fix":"Replace all instances of `geometry.type` with `geometry.geom_type`.","message":"The `.type` attribute on Shapely geometry objects is deprecated and will be removed. Use `.geom_type` instead.","severity":"deprecated","affected_versions":"Shapely >= 2.0.0 (and types-shapely for these versions)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions of `types-shapely` (in relation to `shapely`)"},{"fix":"Do not rely on empty geometries being `GeometryCollection`. Use the `.is_empty` attribute for robustly checking if a geometry object is empty.","message":"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.","severity":"breaking","affected_versions":"Shapely >= 2.0.0 (and types-shapely for these versions)"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}