gh-39932: add parameter immutable to method `is_planar`
    
Add parameter immutable to method `is_planar` to control the returned
Kuratowski subgraphs.

This is also related to discussions in #39177, i.e., ensure a correct
behavior with immutable graphs.


### 📝 Checklist

<!-- Put an `x` in all the boxes that apply. -->

- [x] The title is concise and informative.
- [x] The description explains in detail what this PR is about.
- [x] I have linked a relevant issue or discussion.
- [x] I have created tests covering the changes.
- [ ] I have updated the documentation and checked the documentation
preview.

### ⌛ Dependencies

<!-- List all open PRs that this PR logically depends on. For example,
-->
<!-- - #12345: short description why this is a dependency -->
<!-- - #34567: ... -->
    
URL: #39932
Reported by: David Coudert
Reviewer(s): David Coudert, Frédéric Chapoton

Author: Release Manager

src/sage/graphs/generic_graph.py

@@ -5742,7 +5742,8 @@ def minimum_cycle_basis(self, algorithm=None, weight_function=None, by_weight=Fa
 
     # Planarity
 
-    def is_planar(self, on_embedding=None, kuratowski=False, set_embedding=False, set_pos=False):
+    def is_planar(self, on_embedding=None, kuratowski=False, set_embedding=False,
+                  set_pos=False, immutable=None):
         r"""
         Check whether the graph is planar.
 
@@ -5796,6 +5797,11 @@ def is_planar(self, on_embedding=None, kuratowski=False, set_embedding=False, se
           set to False. Also, the position dictionary will only be updated if a
           planar embedding is found.
 
+        - ``immutable`` -- boolean (default: ``None``); whether to create a
+          mutable/immutable graph. ``immutable=None`` (default) means that the
+          graph and the Kuratowski subgraph will behave the same way.
+          This parameter is ignored when ``kuratowski=False``.
+
         EXAMPLES::
 
             sage: g = graphs.CubeGraph(4)
@@ -5956,6 +5962,21 @@ def is_planar(self, on_embedding=None, kuratowski=False, set_embedding=False, se
             True
             sage: Graph(1).is_planar()
             True
+
+        Check the behavior of parameter ``immutable``::
+
+            sage: G = graphs.PetersenGraph()
+            sage: G.is_planar(kuratowski=True)
+            (False, Kuratowski subgraph of (Petersen graph): Graph on 9 vertices)
+            sage: G.is_planar(kuratowski=True)[1].is_immutable()
+            False
+            sage: G.is_planar(kuratowski=True, immutable=True)[1].is_immutable()
+            True
+            sage: G = G.copy(immutable=True)
+            sage: G.is_planar(kuratowski=True)[1].is_immutable()
+            True
+            sage: G.is_planar(kuratowski=True, immutable=False)[1].is_immutable()
+            False
         """
         # Quick check first
         if (on_embedding is None and not kuratowski and not set_embedding and not set_pos
@@ -5979,10 +6000,11 @@ def is_planar(self, on_embedding=None, kuratowski=False, set_embedding=False, se
             return (0 == self.genus(minimal=False, set_embedding=False, on_embedding=on_embedding))
 
         # We take the underlying undirected and simple graph
-        G = self.to_simple(to_undirected=True, immutable=False)
+        G = self.to_simple(to_undirected=True)
         # And check if it is planar
         from sage.graphs.planarity import is_planar
-        planar = is_planar(G, kuratowski=kuratowski, set_pos=set_pos, set_embedding=set_embedding)
+        planar = is_planar(G, kuratowski=kuratowski, set_pos=set_pos,
+                           set_embedding=set_embedding, immutable=immutable)
         if kuratowski:
             bool_result = planar[0]
         else:

src/sage/graphs/planarity.pyx

@@ -30,7 +30,7 @@ cdef extern from "planarity/graph.h":
     cdef int gp_SortVertices(graphP theGraph)
 
 
-def is_planar(g, kuratowski=False, set_pos=False, set_embedding=False):
+def is_planar(g, kuratowski=False, set_pos=False, set_embedding=False, immutable=None):
     r"""
     Check whether ``g`` is planar using Boyer's planarity algorithm.
 
@@ -55,6 +55,11 @@ def is_planar(g, kuratowski=False, set_pos=False, set_embedding=False):
       combinatorial embedding returned (see
       :meth:`~sage.graphs.generic_graph.GenericGraph.get_embedding`)
 
+    - ``immutable`` -- boolean (default: ``None``); whether to create a
+      mutable/immutable graph. ``immutable=None`` (default) means that
+      the graph and the Kuratowski subgraph will behave the same way.
+      This parameter is ignored when ``kuratowski=False``.
+
     EXAMPLES::
 
         sage: G = graphs.DodecahedralGraph()
@@ -94,6 +99,21 @@ def is_planar(g, kuratowski=False, set_pos=False, set_embedding=False):
             ....:     assert is_planar(G, set_embedding=set_embedding, set_pos=set_pos)
             ....:     assert (hasattr(G, '_embedding') and G._embedding is not None) == set_embedding, (set_embedding, set_pos)
             ....:     assert (hasattr(G, '_pos') and G._pos is not None) == set_pos, (set_embedding, set_pos)
+
+    Check the behavior of parameter ``immutable``::
+
+        sage: G = graphs.PetersenGraph()
+        sage: G.is_planar(kuratowski=True)
+        (False, Kuratowski subgraph of (Petersen graph): Graph on 9 vertices)
+        sage: G.is_planar(kuratowski=True)[1].is_immutable()
+        False
+        sage: G.is_planar(kuratowski=True, immutable=True)[1].is_immutable()
+        True
+        sage: G = G.copy(immutable=True)
+        sage: G.is_planar(kuratowski=True)[1].is_immutable()
+        True
+        sage: G.is_planar(kuratowski=True, immutable=False)[1].is_immutable()
+        False
     """
     g._scream_if_not_simple()
     if set_pos and not g.is_connected():
@@ -137,7 +157,7 @@ def is_planar(g, kuratowski=False, set_pos=False, set_embedding=False):
                 gp_Free(&theGraph)
                 return False
             # With just the current edges, we have a nonplanar graph,
-            # so to isolate a kuratowski subgraph, just keep going.
+            # so to isolate a Kuratowski subgraph, just keep going.
             break
 
     status = gp_Embed(theGraph, EMBEDFLAGS_PLANAR)
@@ -161,11 +181,14 @@ def is_planar(g, kuratowski=False, set_pos=False, set_embedding=False):
                 j = theGraph.E[j].link[1]
             if linked_list:
                 g_dict[to[i]] = linked_list
+        if immutable is None:
+            immutable = g.is_immutable()
         gp_Free(&theGraph)
         G = g.__class__(data=g_dict, weighted=g._weighted,
                         loops=g.allows_loops(),
                         multiedges=g.allows_multiple_edges(),
-                        name="Kuratowski subgraph of (%s)" % g.name())
+                        name="Kuratowski subgraph of (%s)" % g.name(),
+                        immutable=immutable)
         if g.get_pos():
             G.set_pos({u: g._pos[u] for u in g_dict})
         return (False, G)