API: allow silencing of FutureWarnings from legacy API

docs/legacy_api.rst

@@ -8,6 +8,13 @@ Legacy API reference
 
 .. warning::
     The functionality listed below is part of the legacy API and has been deprecated.
+    Each class emits ``FutureWarning`` with a deprecation note. If you'd like to
+    silence all of these warnigns, set an environment variable ``ALLOW_LEGACY_MOMEPY``
+    to ``"True"``::
+
+      import os
+
+      os.environ["ALLOW_LEGACY_MOMEPY"] = "True"
 
 elements
 --------

momepy/tests/test_utils.py

@@ -1,3 +1,6 @@
+import os
+import warnings
+
 import geopandas as gpd
 import networkx
 import numpy as np
@@ -215,3 +218,47 @@ def test_limit_range(self):
             mm.limit_range(np.array([np.nan, np.nan, np.nan]), rng=(25, 75)),
             np.array([np.nan, np.nan, np.nan]),
         )
+
+    def test_deprecated_decorators(self):
+        with pytest.warns(
+            FutureWarning,
+            match=(
+                "Class based API like `momepy.LongestAxisLength` is deprecated. "
+                "Replace it with `momepy.longest_axis_length`"
+            ),
+        ):
+            mm.LongestAxisLength(self.df_buildings)
+        os.environ["ALLOW_LEGACY_MOMEPY"] = "True"
+
+        with warnings.catch_warnings():
+            warnings.simplefilter("error")
+            mm.LongestAxisLength(self.df_buildings)
+
+        os.environ["ALLOW_LEGACY_MOMEPY"] = "False"
+        with pytest.warns(
+            FutureWarning,
+            match=(
+                "Class based API like `momepy.LongestAxisLength` is deprecated. "
+                "Replace it with `momepy.longest_axis_length`"
+            ),
+        ):
+            mm.LongestAxisLength(self.df_buildings)
+
+    def test_removed_decorators(self):
+        with pytest.warns(
+            FutureWarning,
+            match=("`momepy.Area` is deprecated"),
+        ):
+            mm.Area(self.df_buildings)
+        os.environ["ALLOW_LEGACY_MOMEPY"] = "True"
+
+        with warnings.catch_warnings():
+            warnings.simplefilter("error")
+            mm.Area(self.df_buildings)
+
+        os.environ["ALLOW_LEGACY_MOMEPY"] = "False"
+        with pytest.warns(
+            FutureWarning,
+            match=("`momepy.Area` is deprecated"),
+        ):
+            mm.Area(self.df_buildings)

momepy/utils.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python
-
 import math
+import os
 import warnings
 
 import geopandas as gpd
@@ -28,15 +28,21 @@ def decorator(func1):
 
         @functools.wraps(func1)
         def new_func1(*args, **kwargs):
-            warnings.warn(
-                f"Class based API like `momepy.{func1.__name__}` is deprecated. "
-                f"Replace it with `momepy.{new_way}` to use functional API instead "
-                "or pin momepy version <1.0. Class-based API will be removed in 1.0. "
-                # "See details at https://docs.momepy.org/en/stable/migration.html",
-                "",
-                FutureWarning,
-                stacklevel=2,
-            )
+            if os.getenv("ALLOW_LEGACY_MOMEPY", "False").lower() not in (
+                "true",
+                "1",
+                "yes",
+            ):
+                warnings.warn(
+                    f"Class based API like `momepy.{func1.__name__}` is deprecated. "
+                    f"Replace it with `momepy.{new_way}` to use functional API instead "
+                    "or pin momepy version <1.0. Class-based API will be removed in "
+                    "1.0. "
+                    # "See details at https://docs.momepy.org/en/stable/migration.html",
+                    "",
+                    FutureWarning,
+                    stacklevel=2,
+                )
             return func1(*args, **kwargs)
 
         return new_func1
@@ -54,14 +60,20 @@ def decorator(func1):
 
         @functools.wraps(func1)
         def new_func1(*args, **kwargs):
-            warnings.warn(
-                f"`momepy.{func1.__name__}` is deprecated. Replace it with {new_way} "
-                "or pin momepy version <1.0. This class will be removed in 1.0. "
-                # "See details at https://docs.momepy.org/en/stable/migration.html"
-                "",
-                FutureWarning,
-                stacklevel=2,
-            )
+            if os.getenv("ALLOW_LEGACY_MOMEPY", "False").lower() not in (
+                "true",
+                "1",
+                "yes",
+            ):
+                warnings.warn(
+                    f"`momepy.{func1.__name__}` is deprecated. Replace it with "
+                    f"{new_way} "
+                    "or pin momepy version <1.0. This class will be removed in 1.0. "
+                    # "See details at https://docs.momepy.org/en/stable/migration.html"
+                    "",
+                    FutureWarning,
+                    stacklevel=2,
+                )
             return func1(*args, **kwargs)
 
         return new_func1