Deprecate shapefile reader (#872)

cuSpatial's C++-based shapefile reader is limited. It can only load polygons (not multipolygons). It was written before cuSpatial supported GeoArrow data format and before it could ingest data from GeoPandas directly. It is better to use GeoPandas or other libraries to load data into cuSpatial. Dropping `read_polygon_shapefile` and its C++ implementation allows dropping the libcuspatial dependency on GDAL, which may help with publishing PIP wheels, which is a priority. This PR simply adds deprecation warnings / decorators to the Python and C++ `read_polygon_shapefile` functions and documentation, and updates the Python user guide to mention deprecation. The plan is to remove these functions and tests that depend on them in 23.04. Authors: - Mark Harris (https://github.com/harrism) Approvers: - Paul Taylor (https://github.com/trxcllnt) - Michael Wang (https://github.com/isVoid) - H. Thomson Comer (https://github.com/thomcom) URL: #872
rapidsai · Jan 31, 2023 · f967893 · f967893
1 parent f4a4380
commit f967893
Show file tree

Hide file tree

Showing 4 changed files with 136 additions and 42 deletions.
diff --git a/cpp/include/cuspatial/shapefile_reader.hpp b/cpp/include/cuspatial/shapefile_reader.hpp
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2020-2022, NVIDIA CORPORATION.
+ * Copyright (c) 2020-2023, NVIDIA CORPORATION.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -47,7 +47,9 @@ typedef enum class winding_order : bool { CLOCKWISE, COUNTER_CLOCKWISE } winding
  * @note The number of polygons is equal to the length of the first column
  *
  **/
-std::vector<std::unique_ptr<cudf::column>> read_polygon_shapefile(
+[[deprecated(
+  "Use Python libraries or GDAL to load shapefiles.")]] std::vector<std::unique_ptr<cudf::column>>
+read_polygon_shapefile(
   std::string const& filename,
   const winding_order outer_ring_winding = winding_order::COUNTER_CLOCKWISE,
   rmm::mr::device_memory_resource* mr    = rmm::mr::get_current_device_resource());

diff --git a/docs/source/api_docs/io.rst b/docs/source/api_docs/io.rst
@@ -1,8 +1,10 @@
 IO
 --
 
-cuSpatial offers native GPU-accelerated shapefile reading. In addition, any host-side GeoPandas DataFrame can be copied into GPU memory for use with cuSpatial
-algorithms.
+cuSpatial offers limited shapefile reading (polygons only), but this is deprecated and will be
+removed in a future release.
+
+Any host-side GeoPandas DataFrame can be copied into GPU memory for use with cuSpatial algorithms.
 
 .. currentmodule:: cuspatial
 

diff --git a/docs/source/user_guide/cuspatial_api_examples.ipynb b/docs/source/user_guide/cuspatial_api_examples.ipynb
@@ -51,7 +51,11 @@
    "cell_type": "code",
    "execution_count": 1,
    "id": "7265f9d2-9203-4da2-bbb2-b35c7f933641",
-   "metadata": {},
+   "metadata": {
+    "vscode": {
+     "languageId": "python"
+    }
+   },
    "outputs": [],
    "source": [
     "# !conda create -n rapids-22.08 -c rapidsai -c conda-forge -c nvidia \\ \n",
@@ -96,14 +100,15 @@
    "source": [
     "## Input / Output\n",
     "\n",
-    "cuSpatial supports two modes of loading Feature coordinates. [cuspatial.read_polygon_shapefile](\n",
-    "https://docs.rapids.ai/api/cuspatial/stable/api_docs/io.html#cuspatial.read_polygon_shapefile)  \n",
-    "and [cuspatial.from_geopandas](\n",
+    "The primary method of loading features into cuSpatial is using [cuspatial.from_geopandas](\n",
     "https://docs.rapids.ai/api/cuspatial/stable/api_docs/io.html?highlight=from_geopandas#cuspatial.from_geopandas).\n",
     "\n",
     "One can also create feature geometries directly using any Python buffer that supports  \n",
     "`__array_interface__` for coordinates and their feature offsets.\n",
     "\n",
+    "Note: cuSpatial's built-in but limited shapefile loading support is now deprecated and will be\n",
+    "removed in a future release.\n",
+    "\n",
     "### [cuspatial.read_polygon_shapefile](https://docs.rapids.ai/api/cuspatial/stable/api_docs/io.html#cuspatial.read_polygon_shapefile)  \n",
     "\n",
     "`cuspatial.read_polygon_shapefile` loads a `Polygon`-only shapefile from disk. It uses GPU acceleration and  \n",
@@ -116,7 +121,11 @@
    "cell_type": "code",
    "execution_count": 2,
    "id": "88d05bb9-c924-4d0b-8736-cd5183602d76",
-   "metadata": {},
+   "metadata": {
+    "vscode": {
+     "languageId": "python"
+    }
+   },
    "outputs": [],
    "source": [
     "# Imports used throughout this notebook.\n",
@@ -131,7 +140,11 @@
    "cell_type": "code",
    "execution_count": 3,
    "id": "e8f38524-e89f-4d86-b58a-63057cab6b60",
-   "metadata": {},
+   "metadata": {
+    "vscode": {
+     "languageId": "python"
+    }
+   },
    "outputs": [
     {
      "name": "stdout",
@@ -188,7 +201,11 @@
    "cell_type": "code",
    "execution_count": 4,
    "id": "614d508f-0e6b-4f46-ae58-1877fa1c91d1",
-   "metadata": {},
+   "metadata": {
+    "vscode": {
+     "languageId": "python"
+    }
+   },
    "outputs": [
     {
      "data": {
@@ -226,7 +243,11 @@
    "cell_type": "code",
    "execution_count": 5,
    "id": "255fbfbe-8be1-498c-9a26-f4a3f31bdded",
-   "metadata": {},
+   "metadata": {
+    "vscode": {
+     "languageId": "python"
+    }
+   },
    "outputs": [
     {
      "name": "stdout",
@@ -284,7 +305,11 @@
    "cell_type": "code",
    "execution_count": 6,
    "id": "956451e2-a520-441d-a939-575ed179917b",
-   "metadata": {},
+   "metadata": {
+    "vscode": {
+     "languageId": "python"
+    }
+   },
    "outputs": [
     {
      "name": "stdout",
@@ -346,7 +371,11 @@
    "cell_type": "code",
    "execution_count": 7,
    "id": "cd8d1c39-b44f-4d06-9e11-04c2dca4cf15",
-   "metadata": {},
+   "metadata": {
+    "vscode": {
+     "languageId": "python"
+    }
+   },
    "outputs": [
     {
      "data": {
@@ -392,7 +421,11 @@
    "cell_type": "code",
    "execution_count": 8,
    "id": "cb5acdad-53aa-418f-9948-8445515bd2b2",
-   "metadata": {},
+   "metadata": {
+    "vscode": {
+     "languageId": "python"
+    }
+   },
    "outputs": [
     {
      "name": "stdout",
@@ -454,7 +487,11 @@
    "cell_type": "code",
    "execution_count": 9,
    "id": "03b75847-090d-40f8-8147-cb10b900d6ec",
-   "metadata": {},
+   "metadata": {
+    "vscode": {
+     "languageId": "python"
+    }
+   },
    "outputs": [
     {
      "name": "stdout",
@@ -518,7 +555,11 @@
    "cell_type": "code",
    "execution_count": 10,
    "id": "452f60cb-28cc-4ad8-8aa2-9d73e3d56ec6",
-   "metadata": {},
+   "metadata": {
+    "vscode": {
+     "languageId": "python"
+    }
+   },
    "outputs": [
     {
      "name": "stdout",
@@ -559,7 +600,11 @@
    "cell_type": "code",
    "execution_count": 11,
    "id": "9266aac4-f925-4fb7-b287-5f0b795d5756",
-   "metadata": {},
+   "metadata": {
+    "vscode": {
+     "languageId": "python"
+    }
+   },
    "outputs": [
     {
      "name": "stdout",
@@ -603,7 +648,11 @@
    "cell_type": "code",
    "execution_count": 12,
    "id": "15b5bb38-702f-4360-b48c-2e49ffd650d7",
-   "metadata": {},
+   "metadata": {
+    "vscode": {
+     "languageId": "python"
+    }
+   },
    "outputs": [
     {
      "name": "stdout",
@@ -648,7 +697,11 @@
    "cell_type": "code",
    "execution_count": 5,
    "id": "a7a870dd-c0ae-41c1-a66c-cff4bd2db0ec",
-   "metadata": {},
+   "metadata": {
+    "vscode": {
+     "languageId": "python"
+    }
+   },
    "outputs": [
     {
      "name": "stdout",
@@ -712,7 +765,11 @@
    "cell_type": "code",
    "execution_count": 14,
    "id": "e75b0352-0f80-404d-a113-f301601cd5a3",
-   "metadata": {},
+   "metadata": {
+    "vscode": {
+     "languageId": "python"
+    }
+   },
    "outputs": [
     {
      "name": "stdout",
@@ -775,7 +832,11 @@
    "cell_type": "code",
    "execution_count": 15,
    "id": "70f66319-c4d2-4a93-ab98-0debcce4a719",
-   "metadata": {},
+   "metadata": {
+    "vscode": {
+     "languageId": "python"
+    }
+   },
    "outputs": [
     {
      "data": {
@@ -845,7 +906,11 @@
    "cell_type": "code",
    "execution_count": 16,
    "id": "35dfb7c9-1914-488a-b22e-8d0067ea7a8b",
-   "metadata": {},
+   "metadata": {
+    "vscode": {
+     "languageId": "python"
+    }
+   },
    "outputs": [
     {
      "name": "stdout",
@@ -910,7 +975,11 @@
    "cell_type": "code",
    "execution_count": 17,
    "id": "40e9a41e-21af-47cc-a142-b19a67941f7f",
-   "metadata": {},
+   "metadata": {
+    "vscode": {
+     "languageId": "python"
+    }
+   },
    "outputs": [
     {
      "name": "stdout",
@@ -979,7 +1048,11 @@
    "cell_type": "code",
    "execution_count": 18,
    "id": "d1ade9da-c9e2-45c4-9685-dffeda3fd358",
-   "metadata": {},
+   "metadata": {
+    "vscode": {
+     "languageId": "python"
+    }
+   },
    "outputs": [
     {
      "name": "stdout",
@@ -1043,7 +1116,11 @@
    "cell_type": "code",
    "execution_count": 19,
    "id": "bf7b2256",
-   "metadata": {},
+   "metadata": {
+    "vscode": {
+     "languageId": "python"
+    }
+   },
    "outputs": [
     {
      "data": {
@@ -1145,7 +1222,11 @@
    "cell_type": "code",
    "execution_count": 20,
    "id": "e3a0a9a3-0bdd-4f05-bcb5-7db4b99a44a3",
-   "metadata": {},
+   "metadata": {
+    "vscode": {
+     "languageId": "python"
+    }
+   },
    "outputs": [
     {
      "name": "stdout",
@@ -1207,7 +1288,11 @@
    "cell_type": "code",
    "execution_count": 21,
    "id": "023bd25a-35be-435d-ab0b-ecbd7a47e147",
-   "metadata": {},
+   "metadata": {
+    "vscode": {
+     "languageId": "python"
+    }
+   },
    "outputs": [
     {
      "name": "stdout",
@@ -1276,7 +1361,11 @@
    "cell_type": "code",
    "execution_count": 22,
    "id": "5a2ca191-b1a4-49fe-8deb-9a4c133b1ac6",
-   "metadata": {},
+   "metadata": {
+    "vscode": {
+     "languageId": "python"
+    }
+   },
    "outputs": [
     {
      "name": "stdout",
@@ -1352,18 +1441,6 @@
    "language": "python",
    "name": "python3"
   },
-  "language_info": {
-   "codemirror_mode": {
-    "name": "ipython",
-    "version": 3
-   },
-   "file_extension": ".py",
-   "mimetype": "text/x-python",
-   "name": "python",
-   "nbconvert_exporter": "python",
-   "pygments_lexer": "ipython3",
-   "version": "3.9.15"
-  },
   "vscode": {
    "interpreter": {
     "hash": "095c3a7a10c98a819b882ee9fe096094f69a1e3586c68cd990c37b93fe693afd"

diff --git a/python/cuspatial/cuspatial/io/shapefile.py b/python/cuspatial/cuspatial/io/shapefile.py
@@ -1,4 +1,6 @@
-# Copyright (c) 2019, NVIDIA CORPORATION.
+# Copyright (c) 2019-2023, NVIDIA CORPORATION.
+
+import warnings
 
 from cudf import DataFrame, Series
 
@@ -34,7 +36,18 @@ def read_polygon_shapefile(
                 x-components of each polygon's points
             y : cudf.Series(dtype=np.float64)
                 y-components of each polygon's points
+
+    Notes
+    -----
+    This function is deprecated and will be removed in a future release.
     """
+    warning_msg = (
+        "read_polygon_shapefile is deprecated and will be removed in a "
+        "future release. Polygon data can be loaded using other libraries "
+        "such as GeoPandas or PyShp."
+    )
+    warnings.warn(warning_msg, DeprecationWarning)
+
     result = cpp_read_polygon_shapefile(filename, outer_ring_order)
     f_pos = Series(result[0], name="f_pos")
     r_pos = Series(result[1], name="r_pos")