Doc ordered graph classes (#2516)

* Add minimal docstrings * Add note about ordered graph variants * Mention ordered variant in `See Also` section * Comply with pep8 * Replace reference to LogGraph with PrintGraph LogGraph was a reference to a graph that logged each mutation. That's what PrintGraph does and is provided in the examples directory. * Do not claim OrderedGraphs maintain the order of adding edges * Remove OrderedGraph examples and minor cleanup for Sphinx
networkx · Jul 16, 2017 · 231c853 · 231c853
1 parent 0a947aa
commit 231c853
Show file tree

Hide file tree

Showing 25 changed files with 1,691 additions and 1,793 deletions.
diff --git a/doc/source/reference/api_1.10.rst b/doc/source/reference/api_1.10.rst
@@ -81,7 +81,7 @@ New functionalities
 
 * [`#1314 <https://github.com/networkx/networkx/pull/1314>`_]
   Allow overwriting of base class dict with dict-like:
-  OrderedGraph, ThinGraph, LogGraph, etc.
+  OrderedGraph, ThinGraph, PrintGraph, etc.
 
 * [`#1321 <https://github.com/networkx/networkx/pull/1321>`_]
   Added ``to_pandas_dataframe`` and ``from_pandas_dataframe``.

diff --git a/doc/source/reference/classes.digraph.rst b/doc/source/reference/classes.digraph.rst
@@ -1,7 +1,7 @@
 .. _digraph:
 
 =========================================
-DiGraph - Directed graphs with self loops
+DiGraph---Directed graphs with self loops
 =========================================
 
 Overview

diff --git a/doc/source/reference/classes.graph.rst b/doc/source/reference/classes.graph.rst
@@ -1,8 +1,8 @@
 .. _graph:
 
-==========================================
-Graph -- Undirected graphs with self loops
-==========================================
+=========================================
+Graph---Undirected graphs with self loops
+=========================================
 
 Overview
 ========

diff --git a/doc/source/reference/classes.multidigraph.rst b/doc/source/reference/classes.multidigraph.rst
@@ -2,7 +2,7 @@
 
 
 =================================================================
-MultiDiGraph - Directed graphs with self loops and parallel edges
+MultiDiGraph---Directed graphs with self loops and parallel edges
 =================================================================
 
 Overview

diff --git a/doc/source/reference/classes.multigraph.rst b/doc/source/reference/classes.multigraph.rst
@@ -1,7 +1,7 @@
 .. _multigraph:
 
 =================================================================
-MultiGraph - Undirected graphs with self loops and parallel edges
+MultiGraph---Undirected graphs with self loops and parallel edges
 =================================================================
 
 Overview

diff --git a/doc/source/reference/classes.ordered.rst b/doc/source/reference/classes.ordered.rst
@@ -0,0 +1,13 @@
+.. _ordered:
+
+============================================
+Ordered Graphs---Consistently ordered graphs
+============================================
+
+.. automodule:: networkx.classes.ordered
+
+.. currentmodule:: networkx
+.. autoclass:: OrderedGraph
+.. autoclass:: OrderedDiGraph
+.. autoclass:: OrderedMultiGraph
+.. autoclass:: OrderedMultiDiGraph
diff --git a/doc/source/reference/classes.rst b/doc/source/reference/classes.rst
@@ -6,7 +6,7 @@ Graph types
 
 NetworkX provides data structures and methods for storing graphs.
 
-All NetworkX graph classes allow (hashable) Python objects as nodes.
+All NetworkX graph classes allow (hashable) Python objects as nodes
 and any Python object can be assigned as an edge attribute. 
 
 The choice of graph class depends on the structure of the 
@@ -34,5 +34,13 @@ Basic graph types
    classes.digraph
    classes.multigraph
    classes.multidigraph
-
-
+   classes.ordered
+
+.. note:: NetworkX uses `dicts` to store the nodes and neighbors in a graph.
+   So the reporting of nodes and edges for the base graph classes will not
+   necessarily be consistent across versions and platforms.  If you need the
+   order of nodes and edges to be consistent (e.g., when writing automated
+   tests), please see :class:`~networkx.OrderedGraph`,
+   :class:`~networkx.OrderedDiGraph`, :class:`~networkx.OrderedMultiGraph`,
+   or :class:`~networkx.OrderedMultiDiGraph`, which behave like the base
+   graph classes but give a consistent order for reporting of nodes and edges.
diff --git a/networkx/classes/digraph.py b/networkx/classes/digraph.py
@@ -51,6 +51,7 @@ class DiGraph(Graph):
     Graph
     MultiGraph
     MultiDiGraph
+    OrderedDiGraph
 
     Examples
     --------
@@ -72,7 +73,7 @@ class DiGraph(Graph):
 
     >>> G.add_nodes_from([2, 3])
     >>> G.add_nodes_from(range(100, 110))
-    >>> H=nx.path_graph(10)
+    >>> H = nx.path_graph(10)
     >>> G.add_nodes_from(H)
 
     In addition to strings and integers any hashable Python object
@@ -210,33 +211,6 @@ class DiGraph(Graph):
 
     Examples
     --------
-    Create a graph subclass that tracks the order nodes are added.
-
-    >>> from collections import OrderedDict
-    >>> class OrderedNodeGraph(nx.Graph):
-    ...     node_dict_factory=OrderedDict
-    ...     adjlist_outer_dict_factory=OrderedDict
-    >>> G=OrderedNodeGraph()
-    >>> G.add_nodes_from((2, 1))
-    >>> list(G.nodes())
-    [2, 1]
-    >>> G.add_edges_from(((2, 2), (2, 1), (1, 1)))
-    >>> # Edge addition order is not preserved
-
-    Create a graph object that tracks the order nodes are added
-    and for each node track the order that neighbors are added.
-
-    >>> class OrderedGraph(nx.Graph):
-    ...     node_dict_factory = OrderedDict
-    ...     adjlist_outer_dict_factory=OrderedDict
-    ...     adjlist_inner_dict_factory = OrderedDict
-    >>> G = OrderedGraph()
-    >>> G.add_nodes_from((2, 1))
-    >>> list(G.nodes())
-    [2, 1]
-    >>> G.add_edges_from(((2, 2), (2, 1), (1, 1)))
-    >>> list(G.edges())
-    [(2, 2), (2, 1), (1, 1)]
 
     Create a low memory graph class that effectively disallows edge
     attributes by using a single attribute dict for all edges.
@@ -255,6 +229,10 @@ class DiGraph(Graph):
     >>> G[2][1] is G[2][2]
     True
 
+
+    Please see :mod:`~networkx.classes.ordered` for more examples of
+    creating graph subclasses by overwriting the base class `dict` with
+    a dictionary-like object.
     """
     def __init__(self, data=None, **attr):
         """Initialize a graph with edges, name, graph attributes.
@@ -285,7 +263,7 @@ def __init__(self, data=None, **attr):
 
         Arbitrary graph attribute pairs (key=value) may be assigned
 
-        >>> G=nx.Graph(e, day="Friday")
+        >>> G = nx.Graph(e, day="Friday")
         >>> G.graph
         {'day': 'Friday'}
 

diff --git a/networkx/classes/graph.py b/networkx/classes/graph.py
@@ -61,6 +61,7 @@ class Graph(object):
     DiGraph
     MultiGraph
     MultiDiGraph
+    OrderedGraph
 
     Examples
     --------
@@ -155,7 +156,7 @@ class Graph(object):
 
     >>> 1 in G     # check if node in graph
     True
-    >>> [n for n in G if n<3]   # iterate through nodes
+    >>> [n for n in G if n < 3]   # iterate through nodes
     [1, 2]
     >>> len(G)  # number of nodes in graph
     5
@@ -224,35 +225,6 @@ class Graph(object):
 
     Examples
     --------
-    Create a graph subclass that tracks the order nodes are added.
-    This example is provided as part of NetworkX via nx.OrderedGraph.
-
-    >>> from collections import OrderedDict
-    >>> class OrderedNodeGraph(nx.Graph):
-    ...     node_dict_factory=OrderedDict
-    ...     adjlist_outer_dict_factory=OrderedDict
-    >>> G=OrderedNodeGraph()
-    >>> G.add_nodes_from((2, 1))
-    >>> list(G.nodes())
-    [2, 1]
-    >>> G.add_edges_from(((2, 2), (2, 1), (1, 1)))
-    >>> # Edge addition order is not preserved
-
-    Create a graph object that tracks the order nodes are added
-    and for each node track the order that neighbors are added.
-    This example is provided as part of NetworkX via nx.OrderedGraph.
-
-    >>> class OrderedGraph(nx.Graph):
-    ...    node_dict_factory = OrderedDict
-    ...    adjlist_outer_dict_factory = OrderedDict
-    ...    adjlist_inner_dict_factory = OrderedDict
-    >>> G = OrderedGraph()
-    >>> G.add_nodes_from((2, 1))
-    >>> list(G.nodes())
-    [2, 1]
-    >>> G.add_edges_from(((2, 2), (2, 1), (1, 1)))
-    >>> list(G.edges())
-    [(2, 2), (2, 1), (1, 1)]
 
     Create a low memory graph class that effectively disallows edge
     attributes by using a single attribute dict for all edges.
@@ -271,6 +243,9 @@ class Graph(object):
     >>> G[2][1] is G[2][2]
     True
 
+    Please see :mod:`~networkx.classes.ordered` for more examples of
+    creating graph subclasses by overwriting the base class `dict` with
+    a dictionary-like object.
     """
     node_dict_factory = dict
     adjlist_outer_dict_factory = dict
@@ -306,7 +281,7 @@ def __init__(self, data=None, **attr):
 
         Arbitrary graph attribute pairs (key=value) may be assigned
 
-        >>> G=nx.Graph(e, day="Friday")
+        >>> G = nx.Graph(e, day="Friday")
         >>> G.graph
         {'day': 'Friday'}
 
@@ -1400,7 +1375,7 @@ def to_undirected(self):
         graph attributes which attempts to completely copy
         all of the data and references.
 
-        This is in contrast to the similar G=DiGraph(D) which returns a
+        This is in contrast to the similar `G = nx.DiGraph(D)` which returns a
         shallow copy of the data.
 
         See the Python copy module for more information on shallow
@@ -1632,7 +1607,7 @@ def number_of_selfloops(self):
 
         Examples
         --------
-        >>> G=nx.Graph()   # or DiGraph, MultiGraph, MultiDiGraph, etc
+        >>> G = nx.Graph()   # or DiGraph, MultiGraph, MultiDiGraph, etc
         >>> G.add_edge(1, 1)
         >>> G.add_edge(1, 2)
         >>> G.number_of_selfloops()
@@ -1707,26 +1682,26 @@ def number_of_edges(self, u=None, v=None):
         Examples
         --------
         For undirected graphs, this method counts the total number of
-        edges in the graph::
+        edges in the graph:
 
-            >>> G = nx.path_graph(4)
-            >>> G.number_of_edges()
-            3
+        >>> G = nx.path_graph(4)
+        >>> G.number_of_edges()
+        3
 
         If you specify two nodes, this counts the total number of edges
-        joining the two nodes::
+        joining the two nodes:
 
-            >>> G.number_of_edges(0, 1)
-            1
+        >>> G.number_of_edges(0, 1)
+        1
 
         For directed graphs, this method can count the total number of
-        directed edges from `u` to `v`::
+        directed edges from `u` to `v`:
 
-            >>> G = nx.DiGraph()
-            >>> G.add_edge(0, 1)
-            >>> G.add_edge(1, 0)
-            >>> G.number_of_edges(0, 1)
-            1
+        >>> G = nx.DiGraph()
+        >>> G.add_edge(0, 1)
+        >>> G.add_edge(1, 0)
+        >>> G.number_of_edges(0, 1)
+        1
 
         """
         if u is None:

diff --git a/networkx/classes/multidigraph.py b/networkx/classes/multidigraph.py
@@ -52,6 +52,7 @@ class MultiDiGraph(MultiGraph, DiGraph):
     Graph
     DiGraph
     MultiGraph
+    OrderedMultiDiGraph
 
     Examples
     --------
@@ -73,7 +74,7 @@ class MultiDiGraph(MultiGraph, DiGraph):
 
     >>> G.add_nodes_from([2, 3])
     >>> G.add_nodes_from(range(100, 110))
-    >>> H=nx.path_graph(10)
+    >>> H = nx.path_graph(10)
     >>> G.add_nodes_from(H)
 
     In addition to strings and integers any hashable Python object
@@ -226,38 +227,10 @@ class MultiDiGraph(MultiGraph, DiGraph):
 
     Examples
     --------
-    Create a multigraph subclass that tracks the order nodes are added.
-
-    >>> from collections import OrderedDict
-    >>> class OrderedGraph(nx.MultiDiGraph):
-    ...    node_dict_factory = OrderedDict
-    ...    adjlist_outer_dict_factory = OrderedDict
-    >>> G = OrderedGraph()
-    >>> G.add_nodes_from((2, 1))
-    >>> list(G.nodes())
-    [2, 1]
-    >>> keys = G.add_edges_from(((2, 2), (2, 1), (2, 1), (1, 1)))
-    >>> # Edge addition order is not preserved
-
-    Create a multdigraph object that tracks the order nodes are added
-    and for each node track the order that neighbors are added and for
-    each neighbor tracks the order that multiedges are added.
-
-    >>> class OrderedGraph(nx.MultiDiGraph):
-    ...    node_dict_factory = OrderedDict
-    ...    adjlist_outer_dict_factory = OrderedDict
-    ...    adjlist_inner_dict_factory = OrderedDict
-    ...    edge_key_dict_factory = OrderedDict
-    >>> G = OrderedGraph()
-    >>> G.add_nodes_from((2, 1))
-    >>> list(G.nodes())
-    [2, 1]
-    >>> elist = ((2, 2), (2, 1, 2, {'weight': 0.1}),
-    ...          (2, 1, 1, {'weight': 0.2}), (1, 1))
-    >>> keys = G.add_edges_from(elist)
-    >>> list(G.edges(keys=True))
-    [(2, 2, 0), (2, 1, 2), (2, 1, 1), (1, 1, 0)]
 
+    Please see :mod:`~networkx.classes.ordered` for examples of
+    creating graph subclasses by overwriting the base class `dict` with
+    a dictionary-like object.
     """
     # node_dict_factory = dict    # already assigned in Graph
     # adjlist_outer_dict_factory = dict