add special processing of `multigraph_input` upon graph init (#4823)

* add special processing of `multigraph_input` upon graph init

Fixes: #4720

Adding a keyword argument `multigraph_input=True`
to a graph construction call should treat any incoming input data for
the graph as a dict-of-dict-of-dict multigraph data structure.

Previously the multigraph_input argument would be added to the graph
attribute dict and ignored when processing the input data.

* Change default and add tests

* make default try mgi=True, and if fails try mgi=False

* copy parameter docstring to main class

1 files changed, 11 insertions, 6 deletions

diff --git a/networkx/convert.py b/networkx/convert.py
index 3cc80e3c..1db67976 100644
--- a/networkx/convert.py
+++ b/networkx/convert.py
@@ -103,7 +103,11 @@ def to_networkx_graph(data, create_using=None, multigraph_input=False):
             return from_dict_of_dicts(
                 data, create_using=create_using, multigraph_input=multigraph_input
             )
-        except:
+        except Exception as e:
+            if multigraph_input is True:
+                raise nx.NetworkXError(
+                    f"converting multigraph_input raised:\n{type(e)}: {e}"
+                )
             try:
                 return from_dict_of_lists(data, create_using=create_using)
             except Exception as e:
@@ -370,9 +374,11 @@ def from_dict_of_dicts(d, create_using=None, multigraph_input=False):
         Graph type to create. If graph instance, then cleared before populated.
 
     multigraph_input : bool (default False)
-       When True, the values of the inner dict are assumed
-       to be containers of edge data for multiple edges.
-       Otherwise this routine assumes the edge data are singletons.
+       When True, the dict `d` is assumed
+       to be a dict-of-dict-of-dict-of-dict structure keyed by
+       node to neighbor to edge keys to edge data for multi-edges.
+       Otherwise this routine assumes dict-of-dict-of-dict keyed by
+       node to neighbor to edge data.
 
     Examples
     --------
@@ -386,9 +392,8 @@ def from_dict_of_dicts(d, create_using=None, multigraph_input=False):
     """
     G = nx.empty_graph(0, create_using)
     G.add_nodes_from(d)
-    # is dict a MultiGraph or MultiDiGraph?
+    # does dict d represent a MultiGraph or MultiDiGraph?
     if multigraph_input:
-        # make a copy of the list of edge data (but not the edge data)
         if G.is_directed():
             if G.is_multigraph():
                 G.add_edges_from(