split out deprecation. remove all changes to neighbor_degree (#4937)

fix k_nearest_neighbors defaults signature in deprecation

4 files changed, 25 insertions, 15 deletions

diff --git a/doc/developer/deprecations.rst b/doc/developer/deprecations.rst
index c222f620..b4c27e96 100644
--- a/doc/developer/deprecations.rst
+++ b/doc/developer/deprecations.rst
@@ -89,3 +89,4 @@ Version 3.0
 * In ``linalg/graphmatrix.py`` remove ``adj_matrix``.
 * In ``algorithms/similarity.py`` replace ``simrank_similarity`` with ``simrank_similarity_numpy``.
 * In ``algorithms/assortativity/mixing.py`` remove ``numeric_mixing_matrix``.
+* In ``algorithms/assortativity/connectivity.py`` remove ``k_nearest_neighbors``.
diff --git a/doc/release/release_dev.rst b/doc/release/release_dev.rst
index 46a5c08e..f1d8e3fd 100644
--- a/doc/release/release_dev.rst
+++ b/doc/release/release_dev.rst
@@ -258,6 +258,8 @@ Deprecations
   Deprecate ``simrank_similarity_numpy``.
 - [`#4923 <https://github.com/networkx/networkx/pull/4923>`_]
   Deprecate ``numeric_mixing_matrix``.
+- [`#4931 <https://github.com/networkx/networkx/pull/4931>`_]
+  Deprecate ``k_nearest_neighbors``.
 
 Contributors
 ------------
diff --git a/networkx/algorithms/assortativity/connectivity.py b/networkx/algorithms/assortativity/connectivity.py
index a00a2314..a23c7ffc 100644
--- a/networkx/algorithms/assortativity/connectivity.py
+++ b/networkx/algorithms/assortativity/connectivity.py
@@ -54,20 +54,15 @@ def average_degree_connectivity(
     --------
     >>> G = nx.path_graph(4)
     >>> G.edges[1, 2]["weight"] = 3
-    >>> nx.k_nearest_neighbors(G)
+    >>> nx.average_degree_connectivity(G)
     {1: 2.0, 2: 1.5}
-    >>> nx.k_nearest_neighbors(G, weight="weight")
+    >>> nx.average_degree_connectivity(G, weight="weight")
     {1: 2.0, 2: 1.75}
 
     See Also
     --------
     average_neighbor_degree
 
-    Notes
-    -----
-    This algorithm is sometimes called "k nearest neighbors" and is also
-    available as `k_nearest_neighbors`.
-
     References
     ----------
     .. [1] A. Barrat, M. Barthélemy, R. Pastor-Satorras, and A. Vespignani,
@@ -116,13 +111,22 @@ def average_degree_connectivity(
         dsum[k] += s
 
     # normalize
-    dc = {}
-    for k, avg in dsum.items():
-        dc[k] = avg
-        norm = dnorm[k]
-        if avg > 0 and norm > 0:
-            dc[k] /= norm
-    return dc
+    return {k: avg if dnorm[k] == 0 else avg / dnorm[k] for k, avg in dsum.items()}
+
 
+def k_nearest_neighbors(G, source="in+out", target="in+out", nodes=None, weight=None):
+    """Compute the average degree connectivity of graph.
 
-k_nearest_neighbors = average_degree_connectivity
+    .. deprecated 2.6
+
+      k_nearest_neighbors function is deprecated and will be removed in v3.0.
+      Use `average_degree_connectivity` instead.
+    """
+    import warnings
+
+    msg = (
+        "k_nearest_neighbors function is deprecated and will be removed in v3.0.\n"
+        "Use `average_degree_connectivity` instead."
+    )
+    warnings.warn(msg, DeprecationWarning, stacklevel=2)
+    return average_degree_connectivity(G, source, target, nodes, weight)
diff --git a/networkx/conftest.py b/networkx/conftest.py
index 4f80d6bb..f9ca81e8 100644
--- a/networkx/conftest.py
+++ b/networkx/conftest.py
@@ -41,6 +41,9 @@ def pytest_collection_modifyitems(config, items):
 @pytest.fixture(autouse=True)
 def set_warnings():
     warnings.filterwarnings(
+        "ignore", category=DeprecationWarning, message="k_nearest_neighbors"
+    )
+    warnings.filterwarnings(
         "ignore", category=DeprecationWarning, message="numeric_mixing_matrix"
     )
     warnings.filterwarnings(