API: Add `show` kwarg to view_pygraphviz. (#4155)

* API: Add  kwarg to view_pygraphviz.

Adds a new keyword argument to view_pygraphviz to toggle whether or not the
drawn graph will actually be displayed.

Currently, there are tests in test_agraph the result in graphs being displayed
via 3rd party viewers (platform dependent) but that don't actually test
whether the rendered graphs are correct.

* draw -> show

* TST: suppress showing of pygraphviz in test suite.

* API: add show kwarg to display pygraphviz

* DEP: deprecate display_pygraphviz

Deprecates display_pygraphviz function and replaces its functionality in
view_pygraphviz.

Adds test to ensure a deprecation warning is raised if
display_pygraphviz is called.

3 files changed, 41 insertions, 11 deletions

diff --git a/doc/developer/deprecations.rst b/doc/developer/deprecations.rst
index a19cc238..f9d29da0 100644
--- a/doc/developer/deprecations.rst
+++ b/doc/developer/deprecations.rst
@@ -49,3 +49,4 @@ Version 3.0
 * In ``networkx/utils/misc.py`` remove ``is_string_like`` and related tests.
 * In ``networkx/utils/misc.py`` remove ``make_str`` and related tests.
 * Remove ``networkx/utils/contextmanagers.py`` and related tests.
+* In ``networkx/drawing/nx_agraph.py`` remove ``display_pygraphviz`` and related tests.
diff --git a/networkx/drawing/nx_agraph.py b/networkx/drawing/nx_agraph.py
index 4589b0d5..71c9491a 100644
--- a/networkx/drawing/nx_agraph.py
+++ b/networkx/drawing/nx_agraph.py
@@ -296,7 +296,9 @@ def pygraphviz_layout(G, prog="neato", root=None, args=""):
 
 
 @nx.utils.open_file(5, "w+b")
-def view_pygraphviz(G, edgelabel=None, prog="dot", args="", suffix="", path=None):
+def view_pygraphviz(
+    G, edgelabel=None, prog="dot", args="", suffix="", path=None, show=True
+):
     """Views the graph G using the specified layout algorithm.
 
     Parameters
@@ -319,6 +321,10 @@ def view_pygraphviz(G, edgelabel=None, prog="dot", args="", suffix="", path=None
     path : str, None
         The filename used to save the image.  If None, save to a temporary
         file.  File formats are the same as those from pygraphviz.agraph.draw.
+    show : bool, default = True
+        Whether to display the graph with `networkx.utils.default_opener`,
+        default is `True`. If `False`, the rendered graph is still available
+        at `path`.
 
     Returns
     -------
@@ -420,7 +426,13 @@ def view_pygraphviz(G, edgelabel=None, prog="dot", args="", suffix="", path=None
         # Assume the decorator worked and it is a file-object.
         pass
 
-    display_pygraphviz(A, path=path, prog=prog, args=args)
+    # Write graph to file
+    A.draw(path=path, format=None, prog=prog, args=args)
+    path.close()
+
+    # Show graph in a new window (depends on platform configuration)
+    if show:
+        nx.utils.default_opener(path.name)
 
     return path.name, A
 
@@ -449,6 +461,14 @@ def display_pygraphviz(graph, path, format=None, prog=None, args=""):
     calls if you experience problems.
 
     """
+    import warnings
+
+    warnings.warn(
+        "display_pygraphviz is deprecated and will be removed in NetworkX 3.0. "
+        "To view a graph G using pygraphviz, use nx.nx_agraph.view_pygraphviz(G). "
+        "To view a graph from file, consider nx.utils.default_opener(filename).",
+        DeprecationWarning,
+    )
     if format is None:
         filename = path.name
         format = os.path.splitext(filename)[1].lower()[1:]
diff --git a/networkx/drawing/tests/test_agraph.py b/networkx/drawing/tests/test_agraph.py
index 8f1cae3e..669160e6 100644
--- a/networkx/drawing/tests/test_agraph.py
+++ b/networkx/drawing/tests/test_agraph.py
@@ -101,7 +101,7 @@ class TestAGraph:
     def test_view_pygraphviz_path(self, tmp_path):
         G = nx.complete_graph(3)
         input_path = str(tmp_path / "graph.png")
-        out_path, A = nx.nx_agraph.view_pygraphviz(G, path=input_path)
+        out_path, A = nx.nx_agraph.view_pygraphviz(G, path=input_path, show=False)
         assert out_path == input_path
         # Ensure file is not empty
         with open(input_path, "rb") as fh:
@@ -110,20 +110,20 @@ class TestAGraph:
 
     def test_view_pygraphviz_file_suffix(self, tmp_path):
         G = nx.complete_graph(3)
-        path, A = nx.nx_agraph.view_pygraphviz(G, suffix=1)
+        path, A = nx.nx_agraph.view_pygraphviz(G, suffix=1, show=False)
         assert path[-6:] == "_1.png"
 
     def test_view_pygraphviz(self):
         G = nx.Graph()  # "An empty graph cannot be drawn."
         pytest.raises(nx.NetworkXException, nx.nx_agraph.view_pygraphviz, G)
         G = nx.barbell_graph(4, 6)
-        nx.nx_agraph.view_pygraphviz(G)
+        nx.nx_agraph.view_pygraphviz(G, show=False)
 
     def test_view_pygraphviz_edgelabel(self):
         G = nx.Graph()
         G.add_edge(1, 2, weight=7)
         G.add_edge(2, 3, weight=8)
-        path, A = nx.nx_agraph.view_pygraphviz(G, edgelabel="weight")
+        path, A = nx.nx_agraph.view_pygraphviz(G, edgelabel="weight", show=False)
         for edge in A.edges():
             assert edge.attr["weight"] in ("7", "8")
 
@@ -133,7 +133,7 @@ class TestAGraph:
         def foo_label(data):
             return "foo"
 
-        path, A = nx.nx_agraph.view_pygraphviz(G, edgelabel=foo_label)
+        path, A = nx.nx_agraph.view_pygraphviz(G, edgelabel=foo_label, show=False)
         for edge in A.edges():
             assert edge.attr["label"] == "foo"
 
@@ -141,7 +141,7 @@ class TestAGraph:
         G = nx.MultiGraph()
         G.add_edge(0, 1, key=0, name="left_fork")
         G.add_edge(0, 1, key=1, name="right_fork")
-        path, A = nx.nx_agraph.view_pygraphviz(G, edgelabel="name")
+        path, A = nx.nx_agraph.view_pygraphviz(G, edgelabel="name", show=False)
         edges = A.edges()
         assert len(edges) == 2
         for edge in edges:
@@ -160,7 +160,7 @@ class TestAGraph:
 
     def test_view_pygraphviz_no_added_attrs_to_input(self):
         G = nx.complete_graph(2)
-        path, A = nx.nx_agraph.view_pygraphviz(G)
+        path, A = nx.nx_agraph.view_pygraphviz(G, show=False)
         assert G.graph == {}
 
     @pytest.mark.xfail(reason="known bug in clean_attrs")
@@ -169,7 +169,7 @@ class TestAGraph:
         # Add entries to graph dict that to_agraph handles specially
         G.graph["node"] = {"width": "0.80"}
         G.graph["edge"] = {"fontsize": "14"}
-        path, A = nx.nx_agraph.view_pygraphviz(G)
+        path, A = nx.nx_agraph.view_pygraphviz(G, show=False)
         assert G.graph == {"node": {"width": "0.80"}, "edge": {"fontsize": "14"}}
 
     def test_graph_with_AGraph_attrs(self):
@@ -177,7 +177,7 @@ class TestAGraph:
         # Add entries to graph dict that to_agraph handles specially
         G.graph["node"] = {"width": "0.80"}
         G.graph["edge"] = {"fontsize": "14"}
-        path, A = nx.nx_agraph.view_pygraphviz(G)
+        path, A = nx.nx_agraph.view_pygraphviz(G, show=False)
         # Ensure user-specified values are not lost
         assert dict(A.node_attr)["width"] == "0.80"
         assert dict(A.edge_attr)["fontsize"] == "14"
@@ -238,3 +238,12 @@ class TestAGraph:
         pos = list(pos.values())
         assert len(pos) == 5
         assert len(pos[0]) == 3
+
+    def test_display_pygraphviz_deprecation_warning(self):
+        G = nx.complete_graph(2)
+        path_name, A = nx.nx_agraph.view_pygraphviz(G, show=False)
+        # Monkeypatch default_opener to prevent window opening
+        nx.utils.default_opener = lambda x: None
+        with pytest.warns(DeprecationWarning, match="display_pygraphviz is deprecated"):
+            with open(path_name, "wb") as fh:
+                nx.nx_agraph.display_pygraphviz(A, fh, prog="dot")