passagemath-graphs 10.5.43__cp39-cp39-musllinux_1_2_aarch64.whl

sage/graphs/graph_plot.py

@@ -0,0 +1,1749 @@
+# sage_setup: distribution = sagemath-graphs
+# sage.doctest: needs sage.plot
+r"""
+Graph plotting
+
+*(For LaTeX drawings of graphs, see the* :mod:`~sage.graphs.graph_latex` *module.)*
+
+All graphs have an associated Sage graphics object, which you can display::
+
+    sage: G = graphs.WheelGraph(15)
+    sage: P = G.plot()
+    sage: P.show()  # long time
+
+.. PLOT::
+
+    sphinx_plot(graphs.WheelGraph(15))
+
+When plotting a graph created using Sage's ``Graph`` command,
+node positions are determined using the spring-layout algorithm.
+Special graphs available from ``graphs.*`` have preset positions.
+For example, compare the two plots of the Petersen graph,
+as obtained using ``Graph`` or as obtained from that database::
+
+    sage: petersen_spring = Graph(':I`ES@obGkqegW~')
+    sage: petersen_spring.show()  # long time
+
+.. PLOT::
+
+    petersen_spring = Graph(':I`ES@obGkqegW~')
+    sphinx_plot(petersen_spring)
+
+::
+
+    sage: petersen_database = graphs.PetersenGraph()
+    sage: petersen_database.show()  # long time
+
+.. PLOT::
+
+    petersen_database = graphs.PetersenGraph()
+    sphinx_plot(petersen_database)
+
+All constructors in this database (except some random graphs) prefill
+the position dictionary, bypassing the spring-layout positioning algorithm.
+
+**Plot options**
+
+Here is the list of options accepted by
+:meth:`~sage.graphs.generic_graph.GenericGraph.plot` and the constructor of
+:class:`GraphPlot`. Those two functions also accept all options of
+:meth:`sage.plot.graphics.Graphics.show`.
+
+.. csv-table::
+    :class: contentstable
+    :widths: 30, 70
+    :delim: |
+
+{PLOT_OPTIONS_TABLE}
+
+**Default options**
+
+This module defines two dictionaries containing default options for the
+:meth:`~sage.graphs.generic_graph.GenericGraph.plot` and
+:meth:`~sage.graphs.generic_graph.GenericGraph.show` methods. These two
+dictionaries are ``sage.graphs.graph_plot.DEFAULT_PLOT_OPTIONS`` and
+``sage.graphs.graph_plot.DEFAULT_SHOW_OPTIONS``, respectively.
+
+Obviously, these values are overruled when arguments are given explicitly.
+
+Here is how to define the default size of a graph drawing to be ``(6, 6)``.
+The first two calls to :meth:`~sage.graphs.generic_graph.GenericGraph.show`
+use this option, while the third does not (a value for ``figsize``
+is explicitly given)::
+
+    sage: import sage.graphs.graph_plot
+    sage: sage.graphs.graph_plot.DEFAULT_SHOW_OPTIONS['figsize'] = (6, 6)
+    sage: graphs.PetersenGraph().show()  # long time
+    sage: graphs.ChvatalGraph().show()  # long time
+    sage: graphs.PetersenGraph().show(figsize=(4, 4))  # long time
+
+We can now reset the default to its initial value, and now display graphs as
+previously::
+
+    sage: sage.graphs.graph_plot.DEFAULT_SHOW_OPTIONS['figsize'] = (4, 4)
+    sage: graphs.PetersenGraph().show()  # long time
+    sage: graphs.ChvatalGraph().show()  # long time
+
+.. NOTE::
+
+    * While ``DEFAULT_PLOT_OPTIONS`` affects both ``G.show()`` and ``G.plot()``,
+      settings from ``DEFAULT_SHOW_OPTIONS`` only affects ``G.show()``.
+
+    * In order to define a default value permanently, you can add a couple of
+      lines to `Sage's startup scripts <../../../repl/startup.html>`_. Example::
+
+       sage: import sage.graphs.graph_plot
+       sage: sage.graphs.graph_plot.DEFAULT_SHOW_OPTIONS['figsize'] = (4, 4)
+
+**Index of methods and functions**
+
+.. csv-table::
+    :class: contentstable
+    :widths: 30, 70
+    :delim: |
+
+    :meth:`GraphPlot.set_pos` | Set the position plotting parameters for this GraphPlot.
+    :meth:`GraphPlot.set_vertices` | Set the vertex plotting parameters for this GraphPlot.
+    :meth:`GraphPlot.set_edges` | Set the edge (or arrow) plotting parameters for the GraphPlot object.
+    :meth:`GraphPlot.show` | Show the (Di)Graph associated with this GraphPlot object.
+    :meth:`GraphPlot.plot` | Return a graphics object representing the (di)graph.
+    :meth:`GraphPlot.layout_tree` | Compute a nice layout of a tree.
+"""
+
+# ****************************************************************************
+#      Copyright (C) 2009   Emily Kirkman
+#                    2009   Robert L. Miller <rlmillster@gmail.com>
+#
+#  Distributed under the terms of the GNU General Public License (GPL)
+#
+#    This code is distributed in the hope that it will be useful,
+#    but WITHOUT ANY WARRANTY; without even the implied warranty of
+#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+#    General Public License for more details.
+#
+#  The full text of the GPL is available at:
+#
+#                  https://www.gnu.org/licenses/
+# ****************************************************************************
+
+from collections import defaultdict
+from math import sqrt, cos, sin, atan, pi
+from sage.structure.sage_object import SageObject
+from sage.misc.lazy_import import lazy_import
+lazy_import("sage.plot.all", [
+    "Graphics", "scatter_plot", "bezier_path", "line", "arrow", "text", "circle"])
+
+
+layout_options = {
+    'layout':
+        'A layout algorithm -- one of : "acyclic", "circular" (plots the '
+        'graph with vertices evenly distributed on a circle), "ranked", '
+        '"graphviz", "planar", "spring" (traditional spring layout, using '
+        'the graph\'s current positions as initial positions), or "tree" '
+        '(the tree will be plotted in levels, depending on minimum distance '
+        'for the root).',
+    'iterations':
+        'The number of times to execute the spring layout algorithm.',
+    'heights':
+        'A dictionary mapping heights to the list of vertices at this height.',
+    'spring':
+        'Use spring layout to finalize the current layout.',
+    'tree_root':
+        'A vertex designation for drawing trees. A vertex of the tree to '
+        'be used as the root for the ``layout=\'tree\'`` option. If no root '
+        'is specified, then one is chosen close to the center of the tree. '
+        'Ignored unless ``layout=\'tree\'``.',
+    'forest_roots':
+        'An iterable specifying which vertices to use as roots for the '
+        '``layout=\'forest\'`` option. If no root is specified for a tree, '
+        'then one is chosen close to the center of the tree. '
+        'Ignored unless ``layout=\'forest\'``.',
+    'tree_orientation':
+        'The direction of tree branches -- \'up\', \'down\', '
+        '\'left\' or \'right\'.',
+    'save_pos':
+        'Whether or not to save the computed position for the graph.',
+    'dim':
+        'The dimension of the layout -- 2 or 3.',
+    'prog':
+        'Which graphviz layout program to use -- one of '
+        '"circo", "dot", "fdp", "neato", or "twopi".',
+    'by_component':
+        'Whether to do the spring layout by connected component -- boolean.'}
+
+graphplot_options = layout_options.copy()
+
+graphplot_options.update({
+    'pos':
+        'The position dictionary of vertices.',
+    'vertex_labels':
+        'Vertex labels to draw. This can be ``True``/``False`` to indicate '
+        'whether to print the vertex string representation of not, '
+        'a dictionary keyed by vertices and associating to each vertex '
+        'a label string, or a function taking as input a vertex and returning '
+        'a label string.',
+    'vertex_label_shift':
+        'If layout is circular and we have vertex labels, will shift vertices '
+        'away from center of circle in coordinate fashion `(x, y)`.',
+    'vertex_color':
+        'Default color for vertices not listed '
+        'in vertex_colors dictionary.',
+    'vertex_colors':
+        'A dictionary specifying vertex colors: '
+        'each key is a color recognizable by matplotlib, '
+        'and each corresponding value is a list of vertices.',
+    'vertex_size':
+        'The size to draw the vertices.',
+    'vertex_shape':
+        'The shape to draw the vertices. '
+        'Currently unavailable for Multi-edged DiGraphs.',
+    'edge_labels':
+        'Whether or not to draw edge labels.',
+    'edge_style':
+        'The linestyle of the edges. It should be '
+        'one of "solid", "dashed", "dotted", "dashdot", '
+        'or "-", "--", ":", "-.", respectively. ',
+    'edge_styles':
+        'A dictionary specifying edge styles: '
+        'each key is an edge or a label (all same) and value is the linestyle '
+        'of the edge. It should be one of "solid", "dashed", "dotted", '
+        '"dashdot", or "-", "--", ":", "-.", respectively.',
+    'edge_thickness':
+        'The thickness of the edges.',
+    'edge_thicknesses':
+        'A dictionary specifying edge thicknesses: '
+        'each key is an edge or a label (all same) and thickness of the '
+        'corresponding edge.',
+    'edge_color':
+        'The default color for edges not listed in edge_colors.',
+    'edge_colors':
+        'A dictionary specifying edge colors: '
+        'each key is a color recognized by matplotlib, '
+        'and each corresponding value is a list of edges.',
+    'color_by_label':
+        'Whether to color the edges according to their labels. This also '
+        'accepts a function or dictionary mapping labels to colors.',
+    'partition':
+        'A partition of the vertex set. If specified, plot will show each '
+        'cell in a different color; vertex_colors takes precedence.',
+    'loop_size':
+        'The radius of the smallest loop.',
+    'arrowsize':
+        'Size of arrows.',
+    'dist':
+        'The distance between multiedges.',
+    'max_dist':
+        'The max distance range to allow multiedges.',
+    'talk':
+        'Whether to display the vertices in talk mode (larger and white).',
+    'label_fontsize':
+       'font size of all labels',
+    'graph_border':
+        'Whether or not to draw a frame around the graph.',
+    'edge_labels_background':
+        'The color of the background of the edge labels.'})
+
+_PLOT_OPTIONS_TABLE = ""
+
+for key, value in graphplot_options.items():
+    _PLOT_OPTIONS_TABLE += f"    ``{key}`` | {value}\n"
+
+__doc__ = __doc__.format(PLOT_OPTIONS_TABLE=_PLOT_OPTIONS_TABLE)
+
+DEFAULT_SHOW_OPTIONS = {'figsize': (4, 4)}
+
+DEFAULT_PLOT_OPTIONS = {
+    'vertex_size'               : 200,
+    'vertex_labels'             : True,
+    'vertex_label_shift'        : None,
+    'layout'                    : None,
+    'edge_style'                : 'solid',
+    'edge_styles'               : None,
+    'edge_thickness'            : 1,
+    'edge_thicknesses'          : None,
+    'edge_color'                : 'black',
+    'edge_colors'               : None,
+    'edge_labels'               : False,
+    'iterations'                : 50,
+    'tree_orientation'          : 'down',
+    'heights'                   : None,
+    'graph_border'              : False,
+    'talk'                      : False,
+    'color_by_label'            : False,
+    'partition'                 : None,
+    'dist'                      : .075,
+    'max_dist'                  : 1.5,
+    'label_fontsize'            : 10,
+    'loop_size'                 : .075,
+    'edge_labels_background'    : 'white'}
+
+
+class GraphPlot(SageObject):
+    def __init__(self, graph, options):
+        """
+        Return a ``GraphPlot`` object, which stores all the parameters needed
+        for plotting (Di)Graphs.
+
+        A ``GraphPlot`` has a plot and show function, as well as some functions
+        to set parameters for vertices and edges.  This constructor assumes
+        default options are set.  Defaults are shown in the example below.
+
+        EXAMPLES::
+
+            sage: from sage.graphs.graph_plot import GraphPlot
+            sage: options = {
+            ....:     'vertex_size': 200,
+            ....:     'vertex_labels': True,
+            ....:     'layout': None,
+            ....:     'edge_style': 'solid',
+            ....:     'edge_color': 'black',
+            ....:     'edge_colors': None,
+            ....:     'edge_labels': False,
+            ....:     'iterations': 50,
+            ....:     'tree_orientation': 'down',
+            ....:     'heights': None,
+            ....:     'graph_border': False,
+            ....:     'talk': False,
+            ....:     'color_by_label': False,
+            ....:     'partition': None,
+            ....:     'dist': .075,
+            ....:     'max_dist': 1.5,
+            ....:     'loop_size': .075,
+            ....:     'edge_labels_background': 'transparent'}
+            sage: g = Graph({0: [1, 2], 2: [3], 4: [0, 1]})
+            sage: GP = GraphPlot(g, options)
+        """
+        # Setting the default values if needed
+        for k, value in DEFAULT_PLOT_OPTIONS.items():
+            if k not in options:
+                options[k] = value
+        self._plot_components = {}
+        self._nodelist = list(graph)
+        self._graph = graph
+        self._options = options  # contains both plot and show options
+        self._arcs = self._graph.has_multiple_edges(to_undirected=True)
+        self._loops = self._graph.has_loops()
+        self._arcdigraph = self._graph.is_directed() and self._arcs
+
+        self.set_pos()
+        self.set_vertices()
+        self.set_edges()
+
+    def _repr_(self):
+        """
+        Return a string representation of a ``GraphPlot`` object.
+
+        EXAMPLES:
+
+        This function is called implicitly by the code below::
+
+            sage: g = Graph({0: [1, 2], 2: [3], 4: [0, 1]})
+            sage: g.graphplot()  # indirect doctest
+            GraphPlot object for Graph on 5 vertices
+        """
+        return f"GraphPlot object for {self._graph}"
+
+    def set_pos(self):
+        """
+        Set the position plotting parameters for this GraphPlot.
+
+        EXAMPLES:
+
+        This function is called implicitly by the code below::
+
+            sage: g = Graph({0: [1, 2], 2: [3], 4: [0, 1]})
+            sage: g.graphplot(save_pos=True, layout='circular')  # indirect doctest
+            GraphPlot object for Graph on 5 vertices
+
+        The following illustrates the format of a position dictionary, but due
+        to numerical noise we do not check the values themselves::
+
+            sage: g.get_pos()
+            {0: (0.0, 1.0),
+             1: (-0.951..., 0.309...),
+             2: (-0.587..., -0.809...),
+             3: (0.587..., -0.809...),
+             4: (0.951..., 0.309...)}
+
+        ::
+
+            sage: T = list(graphs.trees(7))
+            sage: t = T[3]
+            sage: t.plot(heights={0: [0], 1: [4, 5, 1], 2: [2], 3: [3, 6]})
+            Graphics object consisting of 14 graphics primitives
+
+        .. PLOT::
+
+            g = Graph({0: [1, 2], 2: [3], 4: [0, 1]})
+            g.graphplot(save_pos=True, layout='circular')  # indirect doctest
+            T = list(graphs.trees(7))
+            t = T[3]
+            P = t.plot(heights={0: [0], 1: [4, 5, 1], 2: [2], 3: [3, 6]})
+            sphinx_plot(P)
+
+        TESTS:
+
+        Make sure that vertex locations are floats.  Not being floats isn't
+        a bug in itself but made it too easy to accidentally introduce a bug
+        elsewhere, such as in :meth:`set_edges` (:issue:`10124`), via silent
+        truncating division of Python 2 integers::
+
+            sage: g = graphs.FruchtGraph()
+            sage: gp = g.graphplot()
+            sage: set(map(type, flatten(gp._pos.values())))
+            {<... 'float'>}
+            sage: g = graphs.BullGraph()
+            sage: gp = g.graphplot(save_pos=True)
+            sage: set(map(type, flatten(gp._pos.values())))
+            {<... 'float'>}
+
+        Non-ascii labels are also possible using unicode (:issue:`21008`)::
+
+            sage: Graph({u'où': [u'là', u'ici']}).plot()
+            Graphics object consisting of 6 graphics primitives
+        """
+        self._pos = self._graph.layout(**self._options)
+        # Make sure the positions are floats (trac #10124)
+        self._pos = {k: (float(v[0]), float(v[1]))
+                     for k, v in self._pos.items()}
+
+    def set_vertices(self, **vertex_options):
+        """
+        Set the vertex plotting parameters for this ``GraphPlot``.
+
+        This function is called by the constructor but can also be
+        called to make updates to the vertex options of an existing
+        ``GraphPlot`` object. Note that the changes are cumulative.
+
+        EXAMPLES::
+
+            sage: g = Graph({}, loops=True, multiedges=True, sparse=True)
+            sage: g.add_edges([(0, 0, 'a'), (0, 0, 'b'), (0, 1, 'c'),
+            ....:              (0, 1, 'd'), (0, 1, 'e'), (0, 1, 'f'),
+            ....:              (0, 1, 'f'), (2, 1, 'g'), (2, 2, 'h')])
+            sage: GP = g.graphplot(vertex_size=100, edge_labels=True,
+            ....:                  color_by_label=True, edge_style='dashed')
+            sage: GP.set_vertices(talk=True)
+            sage: GP.plot()
+            Graphics object consisting of 22 graphics primitives
+            sage: GP.set_vertices(vertex_color='green', vertex_shape='^')
+            sage: GP.plot()
+            Graphics object consisting of 22 graphics primitives
+
+        .. PLOT::
+
+            g = Graph({}, loops=True, multiedges=True, sparse=True)
+            g.add_edges([(0, 0, 'a'), (0, 0, 'b'), (0, 1, 'c'),
+                         (0, 1, 'd'), (0, 1, 'e'), (0, 1, 'f'),
+                         (0, 1, 'f'), (2, 1, 'g'), (2, 2, 'h')])
+            GP = g.graphplot(vertex_size=100, edge_labels=True,
+                             color_by_label=True, edge_style='dashed')
+            GP.set_vertices(talk=True)
+            sphinx_plot(GP)
+
+        .. PLOT::
+
+            g = Graph({}, loops=True, multiedges=True, sparse=True)
+            g.add_edges([(0, 0, 'a'), (0, 0, 'b'), (0, 1, 'c'),
+                         (0, 1, 'd'), (0, 1, 'e'), (0, 1, 'f'),
+                         (0, 1, 'f'), (2, 1, 'g'), (2, 2, 'h')])
+            GP = g.graphplot(vertex_size=100, edge_labels=True,
+                             color_by_label=True, edge_style='dashed')
+            GP.set_vertices(talk=True)
+            GP.set_vertices(vertex_color='green', vertex_shape='^')
+            sphinx_plot(GP)
+
+        Vertex labels are flexible::
+
+            sage: g = graphs.PathGraph(4)
+            sage: g.plot(vertex_labels=False)
+            Graphics object consisting of 4 graphics primitives
+
+        .. PLOT::
+
+            g = graphs.PathGraph(4)
+            P = g.graphplot(vertex_labels=False)
+            sphinx_plot(P)
+
+        ::
+
+            sage: g = graphs.PathGraph(4)
+            sage: g.plot(vertex_labels=True)
+            Graphics object consisting of 8 graphics primitives
+
+        .. PLOT::
+
+            g = graphs.PathGraph(4)
+            P = g.graphplot(vertex_labels=True)
+            sphinx_plot(P)
+
+        ::
+
+            sage: g = graphs.PathGraph(4)
+            sage: g.plot(vertex_labels=dict(zip(g, ['+', '-', '/', '*'])))
+            Graphics object consisting of 8 graphics primitives
+
+        .. PLOT::
+
+            g = graphs.PathGraph(4)
+            P = g.graphplot(vertex_labels=dict(zip(g, ['+', '-', '/', '*'])))
+            sphinx_plot(P)
+
+        ::
+
+            sage: g = graphs.PathGraph(4)
+            sage: g.plot(vertex_labels=lambda x: str(x % 2))
+            Graphics object consisting of 8 graphics primitives
+
+        .. PLOT::
+
+            g = graphs.PathGraph(4)
+            P = g.graphplot(vertex_labels=lambda x: str(x % 2))
+            sphinx_plot(P)
+        """
+        # Handle base vertex options
+        voptions = {}
+
+        for arg in vertex_options:
+            self._options[arg] = vertex_options[arg]
+
+        # First set defaults for styles
+        vertex_colors = None
+        if self._options['talk']:
+            voptions['markersize'] = 500
+            if self._options['partition'] is None:
+                vertex_colors = '#ffffff'
+        else:
+            voptions['markersize'] = self._options['vertex_size']
+
+        if ('vertex_color' not in self._options
+                or self._options['vertex_color'] is None):
+            vertex_color = '#fec7b8'
+        else:
+            vertex_color = self._options['vertex_color']
+
+        if ('vertex_colors' not in self._options
+                or self._options['vertex_colors'] is None):
+            if self._options['partition'] is not None:
+                from sage.plot.colors import rainbow
+                partition = self._options['partition']
+                length = len(partition)
+                R = rainbow(length)
+                vertex_colors = {R[i]: partition[i] for i in range(length)}
+            elif not vertex_colors:
+                vertex_colors = vertex_color
+        else:
+            vertex_colors = self._options['vertex_colors']
+
+        if 'vertex_shape' in self._options:
+            voptions['marker'] = self._options['vertex_shape']
+
+        if self._graph.is_directed():
+            self._vertex_radius = sqrt(voptions['markersize'] / pi)
+            self._arrowshorten = 2 * self._vertex_radius
+            if self._arcdigraph:
+                self._vertex_radius = sqrt(voptions['markersize'] / (20500 * pi))
+
+        voptions['zorder'] = 7
+
+        if not isinstance(vertex_colors, dict):
+            voptions['facecolor'] = vertex_colors
+            pos = list(self._pos.values())
+            if self._arcdigraph:
+                self._plot_components['vertices'] = [
+                    circle(p, self._vertex_radius, fill=True, clip=False,
+                           edgecolor='black', facecolor=vertex_colors)
+                    for p in pos]
+            else:
+                self._plot_components['vertices'] = (
+                    scatter_plot(pos, clip=False, **voptions))
+        else:
+            # Color list must be ordered:
+            pos = []
+            colors = []
+            for i in vertex_colors:
+                pos.extend([self._pos[j] for j in vertex_colors[i]])
+                colors.extend([i] * len(vertex_colors[i]))
+
+            # If all the vertices have not been assigned a color
+            if len(self._pos) != len(pos):
+                leftovers = [j for j in self._pos.values() if j not in pos]
+                pos.extend(leftovers)
+                colors.extend([vertex_color] * len(leftovers))
+
+            if self._arcdigraph:
+                self._plot_components['vertices'] = [
+                    circle(p, self._vertex_radius, fill=True, clip=False,
+                           facecolor=colors[i], edgecolor='black')
+                    for i, p in enumerate(pos)]
+            else:
+                self._plot_components['vertices'] = scatter_plot(
+                    pos, facecolor=colors, clip=False, **voptions)
+
+        vlabels = self._options['vertex_labels']
+        if vlabels:
+            if vlabels is True:
+                vfun = str
+            elif isinstance(vlabels, dict):
+                def vfun(x):
+                    return vlabels.get(x, "")
+            else:
+                vfun = vlabels
+
+            # TODO: allow text options
+            if self._options['layout'] == 'circular' and self._options['vertex_label_shift'] is not None:
+                def pos_shift(v, shift):
+                    return (v[0] + (v[0] * shift[0])/100, v[1] + (v[1] * shift[1])/100)
+                self._plot_components['vertex_labels'] = [
+                    text(
+                        vfun(v),
+                        pos_shift(self._pos[v], self._options['vertex_label_shift']),
+                        fontsize=self._options['label_fontsize'],
+                        color='black',
+                        zorder=8
+                    )
+                    for v in self._nodelist
+                    ]
+            else:
+                self._plot_components['vertex_labels'] = [
+                    text(vfun(v), self._pos[v], color='black', zorder=8, fontsize=self._options['label_fontsize'])
+                    for v in self._nodelist
+                    ]
+
+    def set_edges(self, **edge_options):
+        """
+        Set edge plotting parameters for the ``GraphPlot`` object.
+
+        This function is called by the constructor but can also be called to
+        update the edge options of an existing ``GraphPlot`` object.
+        Note that the changes are cumulative.
+
+        EXAMPLES::
+
+            sage: g = Graph(loops=True, multiedges=True, sparse=True)
+            sage: g.add_edges([(0, 0, 'a'), (0, 0, 'b'), (0, 1, 'c'),
+            ....:              (0, 1, 'd'), (0, 1, 'e'), (0, 1, 'f'),
+            ....:              (0, 1, 'f'), (2, 1, 'g'), (2, 2, 'h')])
+            sage: GP = g.graphplot(vertex_size=100, edge_labels=True,
+            ....:                  color_by_label=True, edge_style='dashed')
+            sage: GP.set_edges(edge_style='solid')
+            sage: GP.plot()
+            Graphics object consisting of 22 graphics primitives
+
+        .. PLOT::
+
+            g = Graph(loops=True, multiedges=True, sparse=True)
+            g.add_edges([(0, 0, 'a'), (0, 0, 'b'), (0, 1, 'c'),
+                         (0, 1, 'd'), (0, 1, 'e'), (0, 1, 'f'),
+                         (0, 1, 'f'), (2, 1, 'g'), (2, 2, 'h')])
+            GP = g.graphplot(vertex_size=100, edge_labels=True,
+                             color_by_label=True, edge_style='dashed')
+            GP.set_edges(edge_style='solid')
+            sphinx_plot(GP)
+
+        ::
+
+            sage: GP.set_edges(edge_color='black')
+            sage: GP.plot()
+            Graphics object consisting of 22 graphics primitives
+
+        .. PLOT::
+
+            g = Graph(loops=True, multiedges=True, sparse=True)
+            g.add_edges([(0, 0, 'a'), (0, 0, 'b'), (0, 1, 'c'),
+                         (0, 1, 'd'), (0, 1, 'e'), (0, 1, 'f'),
+                         (0, 1, 'f'), (2, 1, 'g'), (2, 2, 'h')])
+            GP = g.graphplot(vertex_size=100, edge_labels=True,
+                             color_by_label=True, edge_style='dashed')
+            GP.set_edges(edge_style='solid')
+            GP.set_edges(edge_color='black')
+            sphinx_plot(GP)
+
+        ::
+
+            sage: d = DiGraph(loops=True, multiedges=True, sparse=True)
+            sage: d.add_edges([(0, 0, 'a'), (0, 0, 'b'), (0, 1, 'c'),
+            ....:              (0, 1, 'd'), (0, 1, 'e'), (0, 1, 'f'),
+            ....:              (0, 1, 'f'), (2, 1, 'g'), (2, 2, 'h')])
+            sage: GP = d.graphplot(vertex_size=100, edge_labels=True,
+            ....:                  color_by_label=True, edge_style='dashed')
+            sage: GP.set_edges(edge_style='solid')
+            sage: GP.plot()
+            Graphics object consisting of 24 graphics primitives
+
+        .. PLOT::
+
+            d = DiGraph(loops=True, multiedges=True, sparse=True)
+            d.add_edges([(0, 0, 'a'), (0, 0, 'b'), (0, 1, 'c'),
+                         (0, 1, 'd'), (0, 1, 'e'), (0, 1, 'f'),
+                         (0, 1, 'f'), (2, 1, 'g'), (2, 2, 'h')])
+            GP = d.graphplot(vertex_size=100, edge_labels=True,
+                             color_by_label=True, edge_style='dashed')
+            GP.set_edges(edge_style='solid')
+            sphinx_plot(GP)
+
+        ::
+
+            sage: GP.set_edges(edge_color='black')
+            sage: GP.plot()
+            Graphics object consisting of 24 graphics primitives
+
+        .. PLOT::
+
+            d = DiGraph(loops=True, multiedges=True, sparse=True)
+            d.add_edges([(0, 0, 'a'), (0, 0, 'b'), (0, 1, 'c'),
+                         (0, 1, 'd'), (0, 1, 'e'), (0, 1, 'f'),
+                         (0, 1, 'f'), (2, 1, 'g'), (2, 2, 'h')])
+            GP = d.graphplot(vertex_size=100, edge_labels=True,
+                             color_by_label=True, edge_style='dashed')
+            GP.set_edges(edge_style='solid')
+            GP.set_edges(edge_color='black')
+            sphinx_plot(GP)
+
+        TESTS::
+
+            sage: G = Graph("Fooba")
+            sage: G.show(edge_colors={'red':[(3, 6), (2, 5)]})
+
+        Check default edge labels are pretty close to halfway between
+        the vertices in some cases where they weren't due to Python 2
+        truncating division (:issue:`10124`)::
+
+            sage: test_graphs = graphs.FruchtGraph(), graphs.BullGraph()
+            sage: tol = 0.001
+            sage: for G in test_graphs:
+            ....:     E = G.edges(sort=True)
+            ....:     for e0, e1, elab in E:
+            ....:         G.set_edge_label(e0, e1, '%d %d' % (e0, e1))
+            ....:     gp = G.graphplot(save_pos=True, edge_labels=True)
+            ....:     vx = gp._plot_components['vertices'][0].xdata
+            ....:     vy = gp._plot_components['vertices'][0].ydata
+            ....:     for elab in gp._plot_components['edge_labels']:
+            ....:         textobj = elab[0]
+            ....:         x, y, s = textobj.x, textobj.y, textobj.string
+            ....:         v0, v1 = map(int, s.split())
+            ....:         m = sum(vector((vx[v], vy[v])) for v in (v0, v1))/2
+            ....:         assert (vector((x, y)) - m).norm() < tol
+
+        Issue :issue:`24051` is fixed::
+
+            sage: G = Graph([(0, 1), (0, 1)], multiedges=True)
+            sage: G.plot(edge_colors={"red": [(1, 0)]})
+            Graphics object consisting of 5 graphics primitives
+
+        Issue :issue:`31542` is fixed::
+
+            sage: s = 'ABCCCCDABCDABCDA'
+            sage: g = DiGraph({}, loops=True, multiedges=True)
+            sage: for a, b in [(s[i], u) for i, u in enumerate(s[1:])]:
+            ....:     g.add_edge(a, b, b)
+            sage: g.plot(color_by_label=True, layout='circular')
+            Graphics object consisting of 23 graphics primitives
+        """
+        for arg in edge_options:
+            self._options[arg] = edge_options[arg]
+        if 'edge_colors' in edge_options:
+            self._options['color_by_label'] = False
+        if self._options['edge_labels_background'] == "transparent":
+            self._options['edge_labels_background'] = "None"
+
+        # Whether a key is an edge or not:
+        #   None => edge_x is not set
+        #   True => keys are edges
+        #   False => keys are labels
+        style_key_edges = None
+        thickness_key_edges = None
+        if isinstance(self._options['edge_styles'], dict):
+            style_key_edges = next(iter(self._options['edge_styles'])) in self._graph.edges()
+        if isinstance(self._options['edge_thicknesses'], dict):
+            thickness_key_edges = next(iter(self._options['edge_thicknesses'])) in self._graph.edges()
+
+        eoptions = {}
+        if 'arrowsize' in self._options:
+            eoptions['arrowsize'] = self._options['arrowsize']
+
+        # Set labels param to add labels on the fly
+        labels = False
+        if self._options['edge_labels']:
+            labels = True
+            self._plot_components['edge_labels'] = []
+
+        # Make dict collection of all edges (keep label and edge color)
+        edges_to_draw = defaultdict(list)
+
+        v_to_int = {v: i for i, v in enumerate(self._graph)}
+
+        if (self._options['color_by_label']
+                or isinstance(self._options['edge_colors'], dict)):
+            if self._options['color_by_label']:
+                edge_colors = self._graph._color_by_label(
+                    format=self._options['color_by_label'])
+            else:
+                edge_colors = self._options['edge_colors']
+            edges_drawn = []
+            for color in edge_colors:
+                for edge in edge_colors[color]:
+                    a, b = edge[0], edge[1]
+                    if v_to_int[a] < v_to_int[b]:
+                        key = (a, b)
+                        head = 1
+                    else:
+                        key = (b, a)
+                        head = 0
+                    if len(edge) < 3:
+                        label = self._graph.edge_label(a, b)
+                        if isinstance(label, list):
+                            edges_to_draw[key].append((label[-1], color, head))
+                            edges_drawn.append((a, b, label[-1]))
+                            for lab in label[:-1]:
+                                edges_to_draw[key].append((lab, color, head))
+                                edges_drawn.append((a, b, lab))
+                        else:
+                            edges_to_draw[key].append((label, color, head))
+                            edges_drawn.append((a, b, label))
+                    else:
+                        label = edge[2]
+                        edges_to_draw[key].append((label, color, head))
+                        edges_drawn.append((a, b, label))
+
+            # Add unspecified edges (default color black set in DEFAULT_PLOT_OPTIONS)
+            for a, b, c in self._graph.edge_iterator():
+                if ((a, b, c) not in edges_drawn
+                        and (self._graph.is_directed()
+                             or (b, a, c) not in edges_drawn)):
+                    if v_to_int[a] < v_to_int[b]:
+                        key = (a, b)
+                        head = 1
+                    else:
+                        key = (b, a)
+                        head = 0
+                    edges_to_draw[key].append((c, self._options['edge_color'], head))
+
+        else:
+            for a, b, c in self._graph.edge_iterator():
+                if v_to_int[a] < v_to_int[b]:
+                    key = (a, b)
+                    head = 1
+                else:
+                    key = (b, a)
+                    head = 0
+                edges_to_draw[key].append((c, self._options['edge_color'], head))
+
+        if edges_to_draw:
+            self._plot_components['edges'] = []
+        else:
+            return
+
+        # Check for multi-edges or loops
+        if self._arcs or self._loops:
+            tmp = edges_to_draw.copy()
+            dist = self._options['dist'] * 2
+            min_loop_size = self._options['loop_size']
+            max_dist = self._options['max_dist']
+            from sage.misc.functional import sqrt
+            for a, b in tmp:
+                if a == b:
+                    # Multiple loops need varying loop radius starting at
+                    # minimum loop size and respecting other distances
+                    loop_size = min_loop_size  # current loop radius
+                    distance = dist
+                    local_labels = edges_to_draw.pop((a, b))
+                    len_local_labels = len(local_labels)
+                    if len_local_labels * dist > max_dist:
+                        distance = float(max_dist) / len_local_labels
+                    loop_size_increment = distance / 4
+                    # Now add all the loops at this vertex, varying their size
+                    for lab, col, _ in local_labels:
+                        x, y = self._pos[a][0], self._pos[a][1] - loop_size
+
+                        estyle = self._options['edge_style']
+                        ethickness = self._options['edge_thickness']
+                        if (style_key_edges is not None
+                            and ((style_key_edges and (x, y) in self._options['edge_styles'])
+                                 or (not style_key_edges and lab in self._options['edge_styles']))):
+                            estyle = style_key_edges and self._options['edge_styles'][(x, y)] or self._options['edge_styles'][lab]
+                        if (thickness_key_edges is not None
+                            and ((thickness_key_edges and (x, y) in self._options['edge_thicknesses'])
+                                 or (not thickness_key_edges and lab in self._options['edge_thicknesses']))):
+                            ethickness = thickness_key_edges and self._options['edge_thicknesses'][(x, y)] or self._options['edge_thicknesses'][lab]
+
+                        c = circle((x, y), loop_size, rgbcolor=col, linestyle=estyle, thickness=ethickness)
+                        self._plot_components['edges'].append(c)
+                        if labels:
+                            bg = self._options['edge_labels_background']
+                            y -= loop_size  # place label at bottom of loop
+                            t = text(lab, (x, y), background_color=bg, fontsize=self._options['label_fontsize'])
+                            self._plot_components['edge_labels'].append(t)
+                        loop_size += loop_size_increment
+                elif len(edges_to_draw[a, b]) > 1:
+                    # Multi-edge
+                    local_labels = edges_to_draw.pop((a, b))
+
+                    # Compute perpendicular bisector
+                    p1 = self._pos[a]
+                    p2 = self._pos[b]
+                    m = ((p1[0] + p2[0]) / 2., (p1[1] + p2[1]) / 2.)  # midpoint
+                    if not p1[1] == p2[1]:
+                        s = (p1[0] - p2[0]) / (p2[1] - p1[1])  # perp slope
+
+                        def y(x):
+                            return s * (x - m[0]) + m[1]  # perp bisector line
+
+                        # f, g are functions to determine x-values of point
+                        # on line y at distance d from point m (on each side)
+                        def f(d):
+                            return sqrt(d**2 / (1. + s**2)) + m[0]
+
+                        def g(d):
+                            return -sqrt(d**2 / (1. + s**2)) + m[0]
+
+                        odd_x = f
+                        even_x = g
+                        if p1[0] == p2[0]:
+                            def odd_y(d):
+                                return m[1]
+
+                            even_y = odd_y
+                        else:
+                            def odd_y(x):
+                                return y(f(x))
+
+                            def even_y(x):
+                                return y(g(x))
+                    else:
+                        def odd_x(d):
+                            return m[0]
+
+                        even_x = odd_x
+
+                        def odd_y(d):
+                            return m[1] + d
+
+                        def even_y(d):
+                            return m[1] - d
+
+                    def odd_xy(d):
+                        return (odd_x(d), odd_y(d))
+
+                    def even_xy(d):
+                        return (even_x(d), even_y(d))
+
+                    # We now have the control points for each Bezier curve
+                    # in terms of distance parameter d.
+                    # Also note each edge label should be drawn at d/2.
+                    # (This is because we're using the perp bisectors).
+                    distance = dist
+                    len_local_labels = len(local_labels)
+                    if len_local_labels * dist > max_dist:
+                        distance = float(max_dist) / len_local_labels
+                    for i in range(len_local_labels // 2):
+                        k = (i + 1.0) * distance
+                        estyle = self._options['edge_style']
+                        ethickness = self._options['edge_thickness']
+
+                        if self._arcdigraph:
+                            vr = self._vertex_radius
+                            ph = self._polar_hack_for_multidigraph
+                            odd_start = ph(p1, odd_xy(k), vr)[0]
+                            odd_end = ph(odd_xy(k), p2, vr)[1]
+                            even_start = ph(p1, even_xy(k), vr)[0]
+                            even_end = ph(even_xy(k), p2, vr)[1]
+
+                            self._plot_components['edges'].append(
+                                arrow(path=[[odd_start, odd_xy(k), odd_end]],
+                                      head=local_labels[2 * i][2], zorder=1,
+                                      rgbcolor=local_labels[2 * i][1],
+                                      linestyle=estyle,
+                                      width=ethickness,
+                                      **eoptions
+                                      ))
+                            self._plot_components['edges'].append(
+                                arrow(path=[[even_start, even_xy(k), even_end]],
+                                      head=local_labels[2 * i + 1][2], zorder=1,
+                                      rgbcolor=local_labels[2 * i + 1][1],
+                                      linestyle=estyle,
+                                      width=ethickness,
+                                      **eoptions
+                                      ))
+                        else:
+                            self._plot_components['edges'].append(
+                                bezier_path([[p1, odd_xy(k), p2]], zorder=1,
+                                            rgbcolor=local_labels[2 * i][1],
+                                            linestyle=estyle,
+                                            thickness=ethickness
+                                            ))
+                            self._plot_components['edges'].append(
+                                bezier_path([[p1, even_xy(k), p2]], zorder=1,
+                                            rgbcolor=local_labels[2 * i + 1][1],
+                                            linestyle=estyle,
+                                            thickness=ethickness
+                                            ))
+                        if labels:
+                            j = k / 2.0
+                            bg = self._options['edge_labels_background']
+                            self._plot_components['edge_labels'].append(
+                                text(local_labels[2 * i][0], odd_xy(j),
+                                     background_color=bg, fontsize=self._options['label_fontsize']))
+                            self._plot_components['edge_labels'].append(
+                                text(local_labels[2 * i + 1][0], even_xy(j),
+                                     background_color=bg, fontsize=self._options['label_fontsize']))
+                    if len_local_labels % 2:
+                        # draw line for last odd
+                        edges_to_draw[a, b] = [local_labels[-1]]
+
+        is_directed = self._graph.is_directed()
+        for a, b in edges_to_draw:
+            elabel = edges_to_draw[a, b][0][0]
+            ecolor = edges_to_draw[a, b][0][1]
+            ehead = edges_to_draw[a, b][0][2]
+            e = (a, b, elabel)
+
+            estyle = self._options['edge_style']
+            ethickness = self._options['edge_thickness']
+            if (style_key_edges is not None
+                and ((style_key_edges and e in self._options['edge_styles'])
+                    or (not style_key_edges and elabel in self._options['edge_styles']))):
+                estyle = style_key_edges and self._options['edge_styles'][e] or self._options['edge_styles'][elabel]
+            if (thickness_key_edges is not None
+                and ((thickness_key_edges and e in self._options['edge_thicknesses'])
+                    or (not thickness_key_edges and elabel in self._options['edge_thicknesses']))):
+                ethickness = thickness_key_edges and self._options['edge_thicknesses'][e] or self._options['edge_thicknesses'][elabel]
+
+            if self._arcdigraph:
+                ph = self._polar_hack_for_multidigraph
+                C, D = ph(self._pos[a], self._pos[b], self._vertex_radius)
+                self._plot_components['edges'].append(
+                    arrow(C, D,
+                          rgbcolor=ecolor,
+                          head=ehead,
+                          linestyle=estyle,
+                          width=ethickness,
+                          **eoptions
+                          ))
+                if labels:
+                    bg = self._options['edge_labels_background']
+                    self._plot_components['edge_labels'].append(
+                        text(str(elabel),
+                             [(C[0] + D[0]) / 2., (C[1] + D[1]) / 2.],
+                             background_color=bg,
+                             fontsize=self._options['label_fontsize']
+                             ))
+            elif is_directed:
+                self._plot_components['edges'].append(
+                    arrow(self._pos[a], self._pos[b],
+                          rgbcolor=ecolor,
+                          arrowshorten=self._arrowshorten,
+                          head=ehead,
+                          linestyle=estyle,
+                          width=ethickness,
+                          **eoptions
+                          ))
+            else:
+                self._plot_components['edges'].append(
+                    line([self._pos[a], self._pos[b]],
+                         rgbcolor=ecolor,
+                         linestyle=estyle,
+                         thickness=ethickness
+                         ))
+            if labels and not self._arcdigraph:
+                bg = self._options['edge_labels_background']
+                self._plot_components['edge_labels'].append(
+                    text(str(edges_to_draw[a, b][0][0]),
+                         [(self._pos[a][0] + self._pos[b][0]) / 2.,
+                         (self._pos[a][1] + self._pos[b][1]) / 2.],
+                         background_color=bg,
+                         fontsize=self._options['label_fontsize']
+                         ))
+
+    def _polar_hack_for_multidigraph(self, A, B, VR):
+        """
+        Helper function to quickly compute the two points of intersection
+        of a line segment from ``A`` to ``B`` (provided as xy pairs) and
+        circles centered at ``A`` and ``B``, both with radius ``VR``.
+        Returns a pair of xy pairs representing the two points.
+
+        EXAMPLES::
+
+            sage: d = DiGraph(loops=True, multiedges=True, sparse=True)
+            sage: d.add_edges([(0, 0, 'a'), (0, 0, 'b'), (0, 1, 'c'),
+            ....:              (0, 1, 'd'), (0, 1, 'e'), (0, 1, 'f'),
+            ....:              (0, 1, 'f'), (2, 1, 'g'), (2, 2, 'h')])
+            sage: GP = d.graphplot(vertex_size=100, edge_labels=True,
+            ....:                  color_by_label=True, edge_style='dashed')
+            sage: GP._polar_hack_for_multidigraph((0, 1), (1, 1), .1)
+            ([0.10..., 1.00...], [0.90..., 1.00...])
+
+        TESTS:
+
+        Make sure that Python ints are acceptable arguments (:issue:`10124`)::
+
+            sage: GP = DiGraph().graphplot()
+            sage: GP._polar_hack_for_multidigraph((0, 1), (2, 2), .1)
+            ([0.08..., 1.04...], [1.91..., 1.95...])
+            sage: GP._polar_hack_for_multidigraph((int(0), int(1)),
+            ....:                                 (int(2), int(2)), .1)
+            ([0.08..., 1.04...], [1.91..., 1.95...])
+        """
+        D = [float(B[i] - A[i]) for i in range(2)]
+        R = sqrt(D[0]**2 + D[1]**2)
+        theta = 3 * pi / 2
+        if D[0] > 0:
+            theta = atan(D[1] / D[0])
+            if D[1] < 0:
+                theta += 2 * pi
+        elif D[0] < 0:
+            theta = atan(D[1] / D[0]) + pi
+        elif D[1] > 0:
+            theta = pi / 2
+        cos_theta = cos(theta)
+        sin_theta = sin(theta)
+        return ([VR * cos_theta + A[0], VR * sin_theta + A[1]],
+                [(R - VR) * cos_theta + A[0], (R - VR) * sin_theta + A[1]])
+
+    def show(self, **kwds):
+        """
+        Show the (di)graph associated with this ``GraphPlot`` object.
+
+        INPUT:
+
+        This method accepts all parameters of
+        :meth:`sage.plot.graphics.Graphics.show`.
+
+        .. NOTE::
+
+            - See :mod:`the module's documentation <sage.graphs.graph_plot>`
+              for information on default values of this method.
+
+            - Any options not used by plot will be passed on to the
+              :meth:`~sage.plot.graphics.Graphics.show` method.
+
+        EXAMPLES::
+
+            sage: C = graphs.CubeGraph(8)
+            sage: P = C.graphplot(vertex_labels=False, vertex_size=0,
+            ....:                 graph_border=True)
+            sage: P.show()
+
+        .. PLOT::
+
+            C = graphs.CubeGraph(8)
+            P = C.graphplot(vertex_labels=False, vertex_size=0,
+                            graph_border=True)
+            sphinx_plot(P)
+        """
+        # Setting the default values if needed
+        for k, value in DEFAULT_SHOW_OPTIONS.items():
+            if k not in kwds:
+                kwds[k] = value
+
+        self.plot().show(**kwds)
+
+    def plot(self, **kwds):
+        """
+        Return a graphics object representing the (di)graph.
+
+        INPUT:
+
+        The options accepted by this method are to be found in the
+        documentation of the :mod:`sage.graphs.graph_plot` module,
+        and the :meth:`~sage.plot.graphics.Graphics.show` method.
+
+        .. NOTE::
+
+            See :mod:`the module's documentation <sage.graphs.graph_plot>` for
+            information on default values of this method.
+
+        We can specify some pretty precise plotting of familiar graphs::
+
+            sage: from math import sin, cos, pi
+            sage: P = graphs.PetersenGraph()
+            sage: d = {'#FF0000': [0, 5], '#FF9900': [1, 6], '#FFFF00': [2, 7],
+            ....:      '#00FF00': [3, 8], '#0000FF': [4,9]}
+            sage: pos_dict = {}
+            sage: for i in range(5):
+            ....:  x = float(cos(pi/2 + ((2*pi)/5)*i))
+            ....:  y = float(sin(pi/2 + ((2*pi)/5)*i))
+            ....:  pos_dict[i] = [x,y]
+            ...
+            sage: for i in range(5, 10):
+            ....:  x = float(0.5*cos(pi/2 + ((2*pi)/5)*i))
+            ....:  y = float(0.5*sin(pi/2 + ((2*pi)/5)*i))
+            ....:  pos_dict[i] = [x,y]
+            ...
+            sage: pl = P.graphplot(pos=pos_dict, vertex_colors=d)
+            sage: pl.show()
+
+        .. PLOT::
+
+            from math import sin, cos, pi
+            P = graphs.PetersenGraph()
+            d = {'#FF0000': [0, 5], '#FF9900': [1, 6], '#FFFF00': [2, 7],
+                 '#00FF00': [3, 8], '#0000FF': [4,9]}
+            pos_dict = {}
+            for i in range(5):
+                x = float(cos(pi/2 + ((2*pi)/5)*i))
+                y = float(sin(pi/2 + ((2*pi)/5)*i))
+                pos_dict[i] = [x,y]
+
+            for i in range(5, 10):
+                x = float(0.5*cos(pi/2 + ((2*pi)/5)*i))
+                y = float(0.5*sin(pi/2 + ((2*pi)/5)*i))
+                pos_dict[i] = [x,y]
+
+            pl = P.graphplot(pos=pos_dict, vertex_colors=d)
+            sphinx_plot(pl)
+
+        Here are some more common graphs with typical options::
+
+            sage: C = graphs.CubeGraph(8)
+            sage: P = C.graphplot(vertex_labels=False, vertex_size=0,
+            ....:                 graph_border=True)
+            sage: P.show()
+
+        .. PLOT::
+
+            C = graphs.CubeGraph(8)
+            P = C.graphplot(vertex_labels=False, vertex_size=0,
+                            graph_border=True)
+            sphinx_plot(P)
+
+        ::
+
+            sage: G = graphs.HeawoodGraph().copy(sparse=True)
+            sage: for u, v, l in G.edges(sort=True):
+            ....:     G.set_edge_label(u, v, f'({u},{v})')
+            sage: G.graphplot(edge_labels=True).show()
+
+        .. PLOT::
+
+            G = graphs.HeawoodGraph().copy(sparse=True)
+            for u, v, l in G.edges(sort=True):
+                G.set_edge_label(u, v, f'({u},{v})')
+            sphinx_plot(G.graphplot(edge_labels=True))
+
+        The options for plotting also work with directed graphs::
+
+            sage: D = DiGraph({
+            ....:     0: [1, 10, 19], 1: [8, 2], 2: [3, 6], 3: [19, 4],
+            ....:     4: [17, 5], 5: [6, 15], 6: [7], 7: [8, 14], 8: [9],
+            ....:     9: [10, 13], 10: [11], 11: [12, 18], 12: [16, 13],
+            ....:     13: [14], 14: [15], 15: [16], 16: [17], 17: [18],
+            ....:     18: [19], 19: []})
+            sage: for u, v, l in D.edges(sort=True):
+            ....:     D.set_edge_label(u, v, f'({u},{v})')
+            sage: D.graphplot(edge_labels=True, layout='circular').show()
+
+        .. PLOT::
+
+            D = DiGraph({
+                0: [1, 10, 19], 1: [8, 2], 2: [3, 6], 3: [19, 4],
+                4: [17, 5], 5: [6, 15], 6: [7], 7: [8, 14], 8: [9],
+                9: [10, 13], 10: [11], 11: [12, 18], 12: [16, 13],
+                13: [14], 14: [15], 15: [16], 16: [17], 17: [18],
+                18: [19], 19: []})
+            for u, v, l in D.edges(sort=True):
+                D.set_edge_label(u, v, f'({u},{v})')
+            sphinx_plot(D.graphplot(edge_labels=True, layout='circular'))
+
+        For graphs with ``circular`` layouts, one may shift the vertex labels by
+        specifying coordinates to shift by::
+
+            sage: D = DiGraph({
+            ....:     0: [1, 10, 19], 1: [8, 2], 2: [3, 6], 3: [19, 4],
+            ....:     4: [17, 5], 5: [6, 15], 6: [7], 7: [8, 14], 8: [9],
+            ....:     9: [10, 13], 10: [11], 11: [12, 18], 12: [16, 13],
+            ....:     13: [14], 14: [15], 15: [16], 16: [17], 17: [18],
+            ....:     18: [19], 19: []})
+            sage: for u, v, l in D.edges(sort=True):
+            ....:     D.set_edge_label(u, v, f'({u},{v})')
+            sage: D.graphplot(edge_labels=True, layout='circular', vertex_label_shift=(15,10)).show()
+
+        .. PLOT::
+
+            D = DiGraph({
+                0: [1, 10, 19], 1: [8, 2], 2: [3, 6], 3: [19, 4],
+                4: [17, 5], 5: [6, 15], 6: [7], 7: [8, 14], 8: [9],
+                9: [10, 13], 10: [11], 11: [12, 18], 12: [16, 13],
+                13: [14], 14: [15], 15: [16], 16: [17], 17: [18],
+                18: [19], 19: []})
+            for u, v, l in D.edges(sort=True):
+                D.set_edge_label(u, v, f'({u},{v})')
+            sphinx_plot(D.graphplot(edge_labels=True, layout='circular', vertex_label_shift=(15,10)))
+
+        This example shows off the coloring of edges::
+
+            sage: from sage.plot.colors import rainbow
+            sage: C = graphs.CubeGraph(5)
+            sage: R = rainbow(5)
+            sage: edge_colors = {}
+            sage: for i in range(5):
+            ....:     edge_colors[R[i]] = []
+            sage: for u, v, l in C.edges(sort=True):
+            ....:     for i in range(5):
+            ....:         if u[i] != v[i]:
+            ....:             edge_colors[R[i]].append((u, v, l))
+            sage: C.graphplot(vertex_labels=False, vertex_size=0,
+            ....:             edge_colors=edge_colors).show()
+
+        .. PLOT::
+
+            from sage.plot.colors import rainbow
+            C = graphs.CubeGraph(5)
+            R = rainbow(5)
+            edge_colors = {}
+            for i in range(5):
+                edge_colors[R[i]] = []
+            for u, v, l in C.edges(sort=True):
+                for i in range(5):
+                    if u[i] != v[i]:
+                        edge_colors[R[i]].append((u, v, l))
+            sphinx_plot(C.graphplot(vertex_labels=False, vertex_size=0,
+                                    edge_colors=edge_colors))
+
+        With the ``partition`` option, we can separate out same-color groups
+        of vertices::
+
+            sage: D = graphs.DodecahedralGraph()
+            sage: Pi = [[6, 5, 15, 14, 7], [16, 13, 8, 2, 4],
+            ....:       [12, 17, 9, 3, 1], [0, 19, 18, 10, 11]]
+            sage: D.show(partition=Pi)
+
+        .. PLOT::
+
+            D = graphs.DodecahedralGraph()
+            Pi = [[6, 5, 15, 14, 7], [16, 13, 8, 2, 4],
+                  [12, 17, 9, 3, 1], [0, 19, 18, 10, 11]]
+            sphinx_plot(D.plot(partition=Pi))
+
+        Loops are also plotted correctly::
+
+            sage: G = graphs.PetersenGraph()
+            sage: G.allow_loops(True)
+            sage: G.add_edge(0,0)
+            sage: G.show()
+
+        .. PLOT::
+
+            G = graphs.PetersenGraph()
+            G.allow_loops(True)
+            G.add_edge(0,0)
+            sphinx_plot(G)
+
+        ::
+
+            sage: D = DiGraph({0:[0,1], 1:[2], 2:[3]}, loops=True)
+            sage: D.show()
+            sage: D.show(edge_colors={(0, 1, 0): [(0, 1, None), (1, 2, None)],
+            ....:                     (0, 0, 0): [(2, 3, None)]})
+
+        .. PLOT::
+
+            D = DiGraph({0:[0,1], 1:[2], 2:[3]}, loops=True)
+            P = D.plot(edge_colors={(0, 1, 0): [(0, 1, None), (1, 2, None)],
+                                    (0, 0, 0): [(2, 3, None)]})
+            sphinx_plot(P)
+
+        More options::
+
+            sage: pos = {0: [0.0, 1.5], 1: [-0.8, 0.3], 2: [-0.6, -0.8],
+            ....:        3:[0.6, -0.8], 4:[0.8, 0.3]}
+            sage: g = Graph({0: [1], 1: [2], 2: [3], 3: [4], 4: [0]})
+            sage: g.graphplot(pos=pos, layout='spring', iterations=0).plot()
+            Graphics object consisting of 11 graphics primitives
+
+        .. PLOT::
+
+            pos = {0: [0.0, 1.5], 1: [-0.8, 0.3], 2: [-0.6, -0.8],
+                   3: [0.6, -0.8], 4:[0.8, 0.3]}
+            g = Graph({0: [1], 1: [2], 2: [3], 3: [4], 4: [0]})
+            P = g.graphplot(pos=pos, layout='spring', iterations=0).plot()
+            sphinx_plot(P)
+
+        ::
+
+            sage: D = graphs.CubeGraph(3)
+            sage: D.graphplot(layout='planar').plot()                                   # needs planarity
+            Graphics object consisting of 21 graphics primitives
+
+        .. PLOT::
+
+            D = graphs.CubeGraph(3)
+            sphinx_plot(D.graphplot(layout='planar'))
+
+        ::
+
+            sage: G = Graph()
+            sage: P = G.graphplot().plot()
+            sage: P.axes()
+            False
+            sage: G = DiGraph()
+            sage: P = G.graphplot().plot()
+            sage: P.axes()
+            False
+
+        We can plot multiple graphs::
+
+            sage: T = list(graphs.trees(7))
+            sage: t = T[3]
+            sage: t.graphplot(heights={0: [0], 1: [4, 5, 1],
+            ....:                      2: [2], 3: [3, 6]}
+            ....:            ).plot()
+            Graphics object consisting of 14 graphics primitives
+
+        .. PLOT::
+
+            T = list(graphs.trees(7))
+            t = T[3]
+            sphinx_plot(t.graphplot(heights={0: [0], 1: [4, 5, 1],
+                                             2: [2], 3: [3, 6]}))
+
+        ::
+
+            sage: T = list(graphs.trees(7))
+            sage: t = T[3]
+            sage: t.graphplot(heights={0: [0], 1: [4, 5, 1],
+            ....:                      2: [2], 3: [3, 6]}
+            ....:            ).plot()
+            Graphics object consisting of 14 graphics primitives
+
+        .. PLOT::
+
+            T = list(graphs.trees(7))
+            t = T[3]
+            sphinx_plot(t.graphplot(heights={0: [0], 1: [4, 5, 1],
+                                             2: [2], 3: [3, 6]}))
+
+        ::
+
+            sage: t.set_edge_label(0, 1, -7)
+            sage: t.set_edge_label(0, 5, 3)
+            sage: t.set_edge_label(0, 5, 99)
+            sage: t.set_edge_label(1, 2, 1000)
+            sage: t.set_edge_label(3, 2, 'spam')
+            sage: t.set_edge_label(2, 6, 3/2)
+            sage: t.set_edge_label(0, 4, 66)
+            sage: t.graphplot(heights={0: [0], 1: [4, 5, 1],
+            ....:                      2: [2], 3: [3, 6]},
+            ....:             edge_labels=True
+            ....:            ).plot()
+            Graphics object consisting of 20 graphics primitives
+
+        .. PLOT::
+
+            T = list(graphs.trees(7))
+            t = T[3]
+            t.set_edge_label(0, 1, -7)
+            t.set_edge_label(0, 5, 3)
+            t.set_edge_label(0, 5, 99)
+            t.set_edge_label(1, 2, 1000)
+            t.set_edge_label(3, 2, 'spam')
+            t.set_edge_label(2, 6, 3/2)
+            t.set_edge_label(0, 4, 66)
+            sphinx_plot(t.graphplot(heights={0: [0], 1: [4, 5, 1],
+                                             2: [2], 3: [3, 6]},
+                                    edge_labels=True))
+
+        ::
+
+            sage: T = list(graphs.trees(7))
+            sage: t = T[3]
+            sage: t.graphplot(layout='tree').show()
+
+        .. PLOT::
+
+            T = list(graphs.trees(7))
+            t = T[3]
+            sphinx_plot(t.graphplot(layout='tree'))
+
+        The tree layout is also useful::
+
+            sage: t = DiGraph('JCC???@A??GO??CO??GO??')
+            sage: t.graphplot(layout='tree', tree_root=0,
+            ....:             tree_orientation="up"
+            ....:            ).show()
+
+        .. PLOT::
+
+            t = DiGraph('JCC???@A??GO??CO??GO??')
+            sphinx_plot(t.graphplot(layout='tree', tree_root=0,
+                                    tree_orientation='up'))
+
+        More examples::
+
+            sage: D = DiGraph({0:[1,2,3], 2:[1,4], 3:[0]})
+            sage: D.graphplot().show()
+
+        .. PLOT::
+
+            D = DiGraph({0:[1,2,3], 2:[1,4], 3:[0]})
+            sphinx_plot(D.graphplot())
+
+        ::
+
+            sage: D = DiGraph({0:[1,2,3], 2:[1,4], 3:[0]})
+            sage: D.graphplot(label_fontsize=20, arrowsize=10).show()
+
+        .. PLOT::
+
+            D = DiGraph({0:[1,2,3], 2:[1,4], 3:[0]})
+            sphinx_plot(D.graphplot(label_fontsize=20, arrowsize=10))
+
+
+        ::
+
+            sage: D = DiGraph(multiedges=True, sparse=True)
+            sage: for i in range(5):
+            ....:   D.add_edge((i, i + 1, 'a'))
+            ....:   D.add_edge((i, i - 1, 'b'))
+            sage: D.graphplot(edge_labels=True,
+            ....:             edge_colors=D._color_by_label()
+            ....:            ).plot()
+            Graphics object consisting of 34 graphics primitives
+
+        .. PLOT::
+
+            D = DiGraph(multiedges=True, sparse=True)
+            for i in range(5):
+                 D.add_edge((i, i + 1, 'a'))
+                 D.add_edge((i, i - 1, 'b'))
+            sphinx_plot(D.graphplot(edge_labels=True,
+                                    edge_colors=D._color_by_label()))
+
+        ::
+
+            sage: g = Graph({}, loops=True, multiedges=True, sparse=True)
+            sage: g.add_edges([(0, 0, 'a'), (0, 0, 'b'), (0, 1, 'c'),
+            ....:              (0, 1, 'd'), (0, 1, 'e'), (0, 1, 'f'),
+            ....:              (0, 1, 'f'), (2, 1, 'g'), (2, 2, 'h')])
+            sage: g.graphplot(edge_labels=True,
+            ....:             color_by_label=True,
+            ....:             edge_style='dashed'
+            ....:            ).plot()
+            Graphics object consisting of 22 graphics primitives
+
+        .. PLOT::
+
+            g = Graph({}, loops=True, multiedges=True, sparse=True)
+            g.add_edges([(0, 0, 'a'), (0, 0, 'b'), (0, 1, 'c'),
+                         (0, 1, 'd'), (0, 1, 'e'), (0, 1, 'f'),
+                         (0, 1, 'f'), (2, 1, 'g'), (2, 2, 'h')])
+            sphinx_plot(g.graphplot(edge_labels=True,
+                                    color_by_label=True,
+                                    edge_style='dashed'))
+
+        The ``edge_style`` option may be provided in the short format too::
+
+
+            sage: g.graphplot(edge_labels=True,
+            ....:             color_by_label=True,
+            ....:             edge_style='--'
+            ....:            ).plot()
+            Graphics object consisting of 22 graphics primitives
+
+        The ``edge_styles`` option may be provided if you need only certain edges
+        to have certain styles::
+
+            sage: g = Graph(loops=True, multiedges=True, sparse=True)
+            sage: g.add_edges([(0, 0, 'a'), (0, 0, 'b'), (0, 1, 'c'),
+            ....:              (0, 1, 'd'), (0, 1, 'e'), (0, 1, 'f'),
+            ....:              (0, 1, 'f'), (2, 1, 'g'), (2, 2, 'h')])
+            sage: GP = g.graphplot(vertex_size=100, edge_labels=True,
+            ....:                  color_by_label=True, edge_style='dashed')
+            sage: GP.set_edges(edge_styles={'a':'dashed', 'g':'dotted'})
+            sage: GP.plot()
+            Graphics object consisting of 22 graphics primitives
+
+        .. PLOT::
+
+            g = Graph(loops=True, multiedges=True, sparse=True)
+            g.add_edges([(0, 0, 'a'), (0, 0, 'b'), (0, 1, 'c'),
+                         (0, 1, 'd'), (0, 1, 'e'), (0, 1, 'f'),
+                         (0, 1, 'f'), (2, 1, 'g'), (2, 2, 'h')])
+            GP = g.graphplot(vertex_size=100, edge_labels=True,
+                             color_by_label=True, edge_style='dashed')
+            GP.set_edges(edge_style='solid')
+            GP.set_edges(edge_color='black')
+            GP.set_edges(edge_styles={'a':'dashed', 'g':'dotted'})
+            sphinx_plot(GP)
+
+        ::
+
+            sage: g = Graph(loops=True, multiedges=True, sparse=True)
+            sage: g.add_edges([(0, 0, 'a'), (0, 0, 'b'), (0, 1, 'c'),
+            ....:              (0, 1, 'd'), (0, 1, 'e'), (0, 1, 'f'),
+            ....:              (0, 1, 'f'), (2, 1, 'g'), (2, 2, 'h')])
+            sage: GP = g.graphplot(vertex_size=100, edge_labels=True,
+            ....:                  color_by_label=True, edge_thickness=3)
+            sage: GP.set_edges(edge_thicknesses={'a':1, 'g':5})
+            sage: GP.plot()
+            Graphics object consisting of 22 graphics primitives
+
+        .. PLOT::
+
+            g = Graph(loops=True, multiedges=True, sparse=True)
+            g.add_edges([(0, 0, 'a'), (0, 0, 'b'), (0, 1, 'c'),
+                         (0, 1, 'd'), (0, 1, 'e'), (0, 1, 'f'),
+                         (0, 1, 'f'), (2, 1, 'g'), (2, 2, 'h')])
+            GP = g.graphplot(vertex_size=100, edge_labels=True,
+                             color_by_label=True, edge_thickness=3)
+            GP.set_edges(edge_style='solid')
+            GP.set_edges(edge_color='black')
+            GP.set_edges(edge_thicknesses={'a':1, 'g':5})
+            sphinx_plot(GP)
+
+        TESTS:
+
+        Make sure that show options work with plot also::
+
+            sage: g = Graph({})
+            sage: g.plot(title='empty graph', axes=True)
+            Graphics object consisting of 0 graphics primitives
+
+        Check for invalid inputs::
+
+            sage: p = graphs.PetersenGraph().plot(egabrag='garbage')
+            Traceback (most recent call last):
+            ...
+            ValueError: invalid input 'egabrag=garbage'
+
+        Make sure that no graphics primitive is clipped::
+
+            sage: tadpole = Graph({0: [0, 1]}).plot()
+            sage: bbox = tadpole.get_minmax_data()
+            sage: for part in tadpole:
+            ....:      part_bbox = part.get_minmax_data()
+            ....:      assert (bbox['xmin'] <= part_bbox['xmin']
+            ....:              <= part_bbox['xmax'] <= bbox['xmax'])
+            ....:      assert (bbox['ymin'] <= part_bbox['ymin']
+            ....:              <= part_bbox['ymax'] <= bbox['ymax'])
+
+        Check that one can plot immutable graphs (:issue:`17340`)::
+
+            sage: Graph({0: [0]}, immutable=True).plot()
+            Graphics object consisting of 3 graphics primitives
+        """
+        G = Graphics()
+        options = self._options.copy()
+        options.update(kwds)
+        G._set_extra_kwds(Graphics._extract_kwds_for_show(options))
+
+        # Check the arguments
+        for o in options:
+            if o not in graphplot_options and o not in G._extra_kwds:
+                raise ValueError("invalid input '{}={}'".format(o, options[o]))
+
+        for comp in self._plot_components.values():
+            if not isinstance(comp, list):
+                G += comp
+            else:
+                for item in comp:
+                    G += item
+
+        if self._options['graph_border']:
+            xmin = G.xmin()
+            xmax = G.xmax()
+            ymin = G.ymin()
+            ymax = G.ymax()
+            dx = (xmax - xmin) / 10.0
+            dy = (ymax - ymin) / 10.0
+            border = (line([(xmin - dx, ymin - dy), (xmin - dx, ymax + dy),
+                            (xmax + dx, ymax + dy), (xmax + dx, ymin - dy),
+                            (xmin - dx, ymin - dy)], thickness=1.3))
+            border.axes_range(xmin=(xmin - dx), xmax=(xmax + dx),
+                              ymin=(ymin - dy), ymax=(ymax + dy))
+            G += border
+        G.set_aspect_ratio(1)
+        G.axes(False)
+        return G
+
+    def layout_tree(self, root, orientation):
+        """
+        Compute a nice layout of a tree.
+
+        INPUT:
+
+        - ``root`` -- the root vertex
+
+        - ``orientation`` -- whether to place the root at the top or at the
+          bottom:
+
+          * ``orientation="down"`` -- children are placed below their parent
+          * ``orientation="top"`` -- children are placed above their parent
+
+        EXAMPLES::
+
+            sage: from sage.graphs.graph_plot import GraphPlot
+            sage: G = graphs.HoffmanSingletonGraph()
+            sage: T = Graph()
+            sage: T.add_edges(G.min_spanning_tree(starting_vertex=0))
+            sage: T.show(layout='tree', tree_root=0)  # indirect doctest
+        """
+        T = self._graph
+
+        if not self._graph.is_tree():
+            raise RuntimeError("cannot use tree layout on this graph: "
+                               "self.is_tree() returns False")
+
+        children = {root: T.neighbors(root)}
+
+        # Always make a copy of the children because they get eaten
+        stack = [list(children[root])]
+        stick = [root]
+        parent = {u: root for u in children[root]}
+        pos = {}
+        obstruction = [0.0] * T.num_verts()
+        if orientation == 'down':
+            o = -1
+        else:
+            o = 1
+
+        def slide(v, dx):
+            """
+            Shift the vertex v and its descendants to the right by dx.
+
+            Precondition: v and its descendents have already had their
+            positions computed.
+            """
+            level = [v]
+            while level:
+                nextlevel = []
+                for u in level:
+                    x, y = pos[u]
+                    x += dx
+                    obstruction[y] = max(x + 1, obstruction[y])
+                    pos[u] = x, y
+                    nextlevel += children[u]
+                level = nextlevel
+
+        while stack:
+            C = stack[-1]
+            if not C:
+                p = stick.pop()
+                stack.pop()
+                cp = children[p]
+                y = o * len(stack)
+                if not cp:
+                    x = obstruction[y]
+                    pos[p] = x, y
+                else:
+                    x = sum([pos[c][0] for c in cp]) / float(len(cp))
+                    pos[p] = x, y
+                    ox = obstruction[y]
+                    if x < ox:
+                        slide(p, ox - x)
+                        x = ox
+                obstruction[y] = x + 1
+                continue
+
+            t = C.pop()
+            pt = parent[t]
+
+            ct = [u for u in T.neighbors(t) if u != pt]
+            for c in ct:
+                parent[c] = t
+            children[t] = ct
+
+            stack.append(ct)
+            stick.append(t)
+
+        return pos