Use new @deprecated decorator

The `@deprecated` decorator has been proposed in PEP 702 and is part of Python 3.13.
The huge benefit of the decorator is that it moves deprecations into the type system, allowing type checkers to catch calls to these methods. Runtime `DeprecationWarnings` are raised automatically and only once on first use.
As usual, the `@deprecated` decorator is backported to older versions of Python in `typing_extensions`. We can use the native implementation `warnings.deprecated` once Python 3.13+ is the minimum version.

pyproject.toml

@@ -33,6 +33,7 @@ dependencies=[
     "requests",
     "scipy",
     "trimesh",
+    "typing_extensions",
     "spharapy",
 ]
 

toponetx/classes/cell_complex.py

@@ -10,7 +10,6 @@
 from collections.abc import Hashable, Iterable, Iterator
 from itertools import zip_longest
 from typing import Any
-from warnings import warn
 
 import networkx as nx
 import numpy as np
@@ -19,6 +18,7 @@
 from networkx import Graph
 from networkx.classes.reportviews import EdgeView, NodeView
 from networkx.utils import pairwise
+from typing_extensions import deprecated
 
 from toponetx.classes.cell import Cell
 from toponetx.classes.combinatorial_complex import (
@@ -199,6 +199,9 @@ def nodes(self) -> NodeView:
         return self._G.nodes
 
     @property
+    @deprecated(
+        "`CellComplex.maxdim` is deprecated and will be removed in the future, use `CellComplex.dim` instead."
+    )
     def maxdim(self) -> int:
         """Return maximum dimension.
 
@@ -207,11 +210,6 @@ def maxdim(self) -> int:
         int
             The maximum dimension for Cell Complex.
         """
-        warn(
-            "`CellComplex.maxdim` is deprecated and will be removed in the future, use `CellComplex.dim` instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
         return self.dim
 
     @property

toponetx/classes/simplex.py

@@ -5,6 +5,8 @@
 from itertools import combinations
 from typing import Any
 
+from typing_extensions import deprecated
+
 from toponetx.classes.complex import Atom
 
 __all__ = ["Simplex"]
@@ -89,6 +91,7 @@ def __contains__(self, item: Any) -> bool:
         return super().__contains__(item)
 
     @staticmethod
+    @deprecated("`Simplex.construct_simplex_tree` is deprecated.")
     def construct_simplex_tree(elements: Collection) -> frozenset["Simplex"]:
         """Return set of Simplex objects representing the faces.
 
@@ -102,11 +105,6 @@ def construct_simplex_tree(elements: Collection) -> frozenset["Simplex"]:
         frozenset[Simplex]
             The set of faces of the simplex.
         """
-        warnings.warn(
-            "`Simplex.construct_simplex_tree` is deprecated.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
 
         faceset = set()
         for r in range(len(elements), 0, -1):
@@ -117,6 +115,9 @@ def construct_simplex_tree(elements: Collection) -> frozenset["Simplex"]:
         return frozenset(faceset)
 
     @property
+    @deprecated(
+        "`Simplex.boundary` is deprecated, use `SimplicialComplex.get_boundaries()` on the simplicial complex that contains this simplex instead."
+    )
     def boundary(self) -> frozenset["Simplex"]:
         """Return the set of the set of all n-1 faces in of the input n-simplex.
 
@@ -130,12 +131,6 @@ def boundary(self) -> frozenset["Simplex"]:
         For a n-simplex [1,2,3], the boundary is all the n-1 subsets of [1,2,3] :
             (1,2), (2,3), (3,1).
         """
-        warnings.warn(
-            "`Simplex.boundary` is deprecated, use `SimplicialComplex.get_boundaries()` on the simplicial complex that contains this simplex instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-
         return frozenset(
             Simplex(elements, construct_tree=False)
             for elements in combinations(self.elements, len(self) - 1)
@@ -152,6 +147,9 @@ def sign(self, face) -> int:
         raise NotImplementedError()
 
     @property
+    @deprecated(
+        "`Simplex.faces` is deprecated, use `SimplicialComplex.get_boundaries()` on the simplicial complex that contains this simplex instead."
+    )
     def faces(self):
         """Get the set of faces of the simplex.
 
@@ -163,12 +161,6 @@ def faces(self):
         frozenset[Simplex]
             The set of faces of the simplex.
         """
-        warnings.warn(
-            "`Simplex.faces` is deprecated, use `SimplicialComplex.get_boundaries()` on the simplicial complex that contains this simplex instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-
         return Simplex.construct_simplex_tree(self.elements)
 
     def __repr__(self) -> str:

toponetx/classes/simplicial_complex.py

@@ -6,12 +6,12 @@
 from collections.abc import Collection, Hashable, Iterable, Iterator
 from itertools import chain, combinations
 from typing import Any
-from warnings import warn
 
 import networkx as nx
 import numpy as np
 from gudhi import SimplexTree
 from scipy.sparse import csr_matrix, dok_matrix
+from typing_extensions import deprecated
 
 from toponetx.classes.complex import Complex
 from toponetx.classes.reportviews import NodeView, SimplexView
@@ -156,6 +156,9 @@ def dim(self) -> int:
         return self._simplex_set.max_dim
 
     @property
+    @deprecated(
+        "`SimplicialComplex.maxdim` is deprecated and will be removed in the future, use `SimplicialComplex.max_dim` instead."
+    )
     def maxdim(self) -> int:
         """
         Maximum dimension of the simplicial complex.
@@ -167,11 +170,6 @@ def maxdim(self) -> int:
         int
             The maximum dimension of the simplicial complex.
         """
-        warn(
-            "`SimplicialComplex.maxdim` is deprecated and will be removed in the future, use `SimplicialComplex.max_dim` instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
         return self._simplex_set.max_dim
 
     @property

toponetx/transform/graph_to_simplicial_complex.py

@@ -1,8 +1,9 @@
 """Methods to lift a graph to a simplicial complex."""
+
 from itertools import combinations, takewhile
-from warnings import warn
 
 import networkx as nx
+from typing_extensions import deprecated
 
 from toponetx.classes.simplicial_complex import SimplicialComplex
 
@@ -72,6 +73,9 @@ def graph_to_clique_complex(
     return SC
 
 
+@deprecated(
+    "`graph_2_neighbor_complex` is deprecated and will be removed in a future version, use `graph_to_neighbor_complex` instead."
+)
 def graph_2_neighbor_complex(G) -> SimplicialComplex:
     """Get the neighbor complex of a graph.
 
@@ -90,14 +94,12 @@ def graph_2_neighbor_complex(G) -> SimplicialComplex:
     This type of simplicial complexes can have very large dimension (max degree of the
     graph) and it is a function of the distribution of the valency of the graph.
     """
-    warn(
-        "`graph_2_neighbor_complex` is deprecated and will be removed in a future version, use `graph_to_neighbor_complex` instead.",
-        DeprecationWarning,
-        stacklevel=2,
-    )
     return graph_to_neighbor_complex(G)
 
 
+@deprecated(
+    "`graph_2_clique_complex` is deprecated and will be removed in a future version, use `graph_to_clique_complex` instead."
+)
 def graph_2_clique_complex(
     G: nx.Graph, max_dim: int | None = None
 ) -> SimplicialComplex:
@@ -115,11 +117,6 @@ def graph_2_clique_complex(
     SimplicialComplex
         The clique simplicial complex of dimension dim of the graph G.
     """
-    warn(
-        "`graph_2_clique_complex` is deprecated and will be removed in a future version, use `graph_to_clique_complex` instead.",
-        DeprecationWarning,
-        stacklevel=2,
-    )
     return graph_to_clique_complex(G, max_dim)