Trac 15603: More doctests, nicer error message

src/sage/graphs/digraph.py

@@ -435,7 +435,17 @@ class DiGraph(GenericGraph):
         Traceback (most recent call last):
         ...
         TypeError: This graph is mutable, and thus not hashable. Create an
-        immutable copy by `g.copy(data_structure='static_sparse')`
+        immutable copy by `g.copy(immutable=True)`
+
+    The error message states that one can also create immutable graphs by
+    specifying the ``immutable`` optional argument (not only by
+    ``data_structure='static_sparse'`` as above)::
+
+        sage: J_imm = DiGraph(G, immutable=True)
+        sage: J_imm == G_imm
+        True
+        sage: type(J_imm._backend) == type(G_imm._backend)
+        True
 
     """
     _directed = True
@@ -516,6 +526,26 @@ def __init__(self, data=None, pos=None, loops=None, format=None,
             sage: g = graphs.PetersenGraph()
             sage: g = DiGraph(g.edges(),immutable=False)
             sage: g.add_edge("Hey", "Heyyyyyyy")
+            sage: {g:1}[g]
+            Traceback (most recent call last):
+            ...
+            TypeError: This graph is mutable, and thus not hashable. Create an immutable copy by `g.copy(immutable=True)`
+            sage: copy(g) is g
+            False
+            sage: {g.copy(immutable=True):1}[g.copy(immutable=True)]
+            1
+
+        But building it with ``immutable=True`` returns an immutable graph::
+
+            sage: g = DiGraph(graphs.PetersenGraph(), immutable=True)
+            sage: g.add_edge("Hey", "Heyyyyyyy")
+            Traceback (most recent call last):
+            ...
+            NotImplementedError
+            sage: {g:1}[g]
+            1
+            sage: copy(g) is g
+            True
 
         """
         msg = ''

src/sage/graphs/generic_graph.py

@@ -481,7 +481,7 @@ def __hash__(self):
             Traceback (most recent call last):
             ...
             TypeError: This graph is mutable, and thus not hashable. Create
-            an immutable copy by `g.copy(data_structure='static_sparse')`
+            an immutable copy by `g.copy(immutable=True)`
             sage: G_imm = Graph(G, data_structure="static_sparse")
             sage: G_imm == G
             True
@@ -494,7 +494,7 @@ def __hash__(self):
         if getattr(self, "_immutable", False):
             return hash((tuple(self.vertices()), tuple(self.edges())))
         raise TypeError("This graph is mutable, and thus not hashable. "
-                        "Create an immutable copy by `g.copy(data_structure='static_sparse')`")
+                        "Create an immutable copy by `g.copy(immutable=True)`")
 
     def __mul__(self, n):
         """
@@ -820,15 +820,18 @@ def __copy__(self, implementation='c_graph', data_structure=None,
             Traceback (most recent call last):
             ...
             TypeError: This graph is mutable, and thus not hashable. Create an
-            immutable copy by `g.copy(data_structure='static_sparse')`
-            sage: g = G.copy(data_structure='static_sparse')
+            immutable copy by `g.copy(immutable=True)`
+            sage: g = G.copy(immutable=True)
             sage: hash(g)    # random
             1833517720
             sage: g==G
             True
             sage: g is copy(g) is g.copy()
             True
-            sage: g is g.copy(data_structure='static_sparse')
+
+        ``immutable=True`` is a short-cut for ``data_structure='static_sparse'``::
+
+            sage: g is g.copy(data_structure='static_sparse') is g.copy(immutable=True)
             True
 
         If a graph pretends to be immutable, but does not use the static sparse
@@ -2408,13 +2411,21 @@ def weighted(self, new=None):
             Traceback (most recent call last):
             ...
             TypeError: This graph is immutable and can thus not be changed.
-            Create a mutable copy, e.g., by `g.copy(sparse=False)`
+            Create a mutable copy, e.g., by `g.copy(immutable=False)`
+            sage: G_mut = G_imm.copy(immutable=False)
+            sage: G_mut == G_imm
+            True
+            sage: G_mut.weighted(True)
+            sage: G_mut == G_imm
+            False
+            sage: G_mut == H
+            True
 
         """
         if new is not None:
             if getattr(self, '_immutable', False):
                 raise TypeError("This graph is immutable and can thus not be changed. "
-                                "Create a mutable copy, e.g., by `g.copy(sparse=False)`")
+                                "Create a mutable copy, e.g., by `g.copy(immutable=False)`")
             if new in [True, False]:
                 self._weighted = new
         else:

src/sage/graphs/graph.py

@@ -503,8 +503,8 @@
     sage: {G:1}[G]
     Traceback (most recent call last):
     ...
-    TypeError: This graph is mutable, and thus not hashable. Create an immutable copy by `g.copy(data_structure='static_sparse')`
-    sage: G_immutable = Graph(G, data_structure="static_sparse")
+    TypeError: This graph is mutable, and thus not hashable. Create an immutable copy by `g.copy(immutable=True)`
+    sage: G_immutable = Graph(G, immutable=True)
     sage: G_immutable == G
     True
     sage: {G_immutable:1}[G_immutable]
@@ -965,14 +965,14 @@ class Graph(GenericGraph):
           sage: {G:1}[H]
           Traceback (most recent call last):
           ...
-          TypeError: This graph is mutable, and thus not hashable. Create an immutable copy by `g.copy(data_structure='static_sparse')`
+          TypeError: This graph is mutable, and thus not hashable. Create an immutable copy by `g.copy(immutable=True)`
 
-    If the ``data_structure`` is equal to ``"static_sparse"``, then an
-    immutable graph results. Note that this does not use the NetworkX data
-    structure::
+    When providing the optional arguments ``data_structure="static_sparse"``
+    or ``immutable=True`` (both mean the same), then an immutable graph
+    results. Note that this does not use the NetworkX data structure::
 
           sage: G_imm = Graph(g, immutable=True)
-          sage: H_imm = Graph(g, immutable=True)
+          sage: H_imm = Graph(g, data_structure='static_sparse')
           sage: G_imm == H_imm == G == H
           True
           sage: hasattr(G_imm._backend, "_nxg")