diff --git a/docs/source/api/generators.rst b/docs/source/api/generators.rst index d6d630d13c..2f930704c7 100644 --- a/docs/source/api/generators.rst +++ b/docs/source/api/generators.rst @@ -33,3 +33,4 @@ Generators rustworkx.generators.complete_graph rustworkx.generators.directed_complete_graph rustworkx.generators.dorogovtsev_goltsev_mendes_graph + rustworkx.generators.karate_club_graph diff --git a/src/generators.rs b/src/generators.rs index ade905e2b3..40c5ae0ad8 100644 --- a/src/generators.rs +++ b/src/generators.rs @@ -23,14 +23,14 @@ use pyo3::Python; use super::{digraph, graph, StablePyGraph}; use rustworkx_core::generators as core_generators; -/// Generate an undirected cycle graph +/// Generate an undirected cycle graph. /// /// :param int num_nodes: The number of nodes to generate the graph with. Node /// weights will be None if this is specified. If both ``num_nodes`` and -/// ``weights`` are set this will be ignored and ``weights`` will be used. -/// :param list weights: A list of node weights, the first element in the list -/// will be the center node of the cycle graph. If both ``num_nodes`` and -/// ``weights`` are set this will be ignored and ``weights`` will be used. +/// ``weights`` are set, this will be ignored and ``weights`` will be used. +/// :param Sequence[Any] weights: A sequence of node weights, typically a list. +/// If both ``num_nodes`` and +/// ``weights`` are set, this will be ignored and ``weights`` will be used. /// :param bool multigraph: When set to ``False`` the output /// :class:`~rustworkx.PyGraph` object will not be not be a multigraph and /// won't allow parallel edges to be added. Instead @@ -76,14 +76,14 @@ pub fn cycle_graph( }) } -/// Generate a directed cycle graph +/// Generate a directed cycle graph. /// /// :param int num_nodes: The number of nodes to generate the graph with. Node /// weights will be None if this is specified. If both ``num_nodes`` and -/// ``weights`` are set this will be ignored and ``weights`` will be used. -/// :param list weights: A list of node weights, the first element in the list -/// will be the center node of the cycle graph. If both ``num_nodes`` and -/// ``weights`` are set this will be ignored and ``weights`` will be used. +/// ``weights`` are set, this will be ignored and ``weights`` will be used. +/// :param Sequence[Any] weights: A sequence of node weights, typically a list. +/// If both ``num_nodes`` and +/// ``weights`` are set, this will be ignored and ``weights`` will be used. /// :param bool bidirectional: Adds edges in both directions between two nodes /// if set to ``True``. Default value is ``False`` /// :param bool multigraph: When set to ``False`` the output @@ -139,14 +139,14 @@ pub fn directed_cycle_graph( }) } -/// Generate an undirected path graph +/// Generate an undirected path graph. /// /// :param int num_nodes: The number of nodes to generate the graph with. Node /// weights will be None if this is specified. If both ``num_nodes`` and -/// ``weights`` are set this will be ignored and ``weights`` will be used. -/// :param list weights: A list of node weights, the first element in the list -/// will be the center node of the path graph. If both ``num_nodes`` and -/// ``weights`` are set this will be ignored and ``weights`` will be used. +/// ``weights`` are set, this will be ignored and ``weights`` will be used. +/// :param Sequence[Any] weights: A sequence of node weights, typically a list. +/// If both ``num_nodes`` and +/// ``weights`` are set, this will be ignored and ``weights`` will be used. /// :param bool multigraph: When set to ``False`` the output /// :class:`~rustworkx.PyGraph` object will not be not be a multigraph and /// won't allow parallel edges to be added. Instead @@ -192,14 +192,14 @@ pub fn path_graph( }) } -/// Generate a directed path graph +/// Generate a directed path graph. /// /// :param int num_nodes: The number of nodes to generate the graph with. Node /// weights will be None if this is specified. If both ``num_nodes`` and -/// ``weights`` are set this will be ignored and ``weights`` will be used. -/// :param list weights: A list of node weights, the first element in the list -/// will be the center node of the path graph. If both ``num_nodes`` and -/// ``weights`` are set this will be ignored and ``weights`` will be used. +/// ``weights`` are set, this will be ignored and ``weights`` will be used. +/// :param Sequence[Any] weights: A sequence of node weights, typically a list. +/// If both ``num_nodes`` and +/// ``weights`` are set, this will be ignored and ``weights`` will be used. /// :param bool bidirectional: Adds edges in both directions between two nodes /// if set to ``True``. Default value is ``False`` /// :param bool multigraph: When set to ``False`` the output @@ -255,20 +255,20 @@ pub fn directed_path_graph( }) } -/// Generate an undirected star graph +/// Generate an undirected star graph. /// /// :param int num_nodes: The number of nodes to generate the graph with. Node /// weights will be None if this is specified. If both ``num_nodes`` and -/// ``weights`` are set this will be ignored and ``weights`` will be used. -/// :param list weights: A list of node weights, the first element in the list +/// ``weights`` are set, this will be ignored and ``weights`` will be used. +/// :param Sequence[Any] weights: A sequence of node weights, typically a list. +/// The first element in the list /// will be the center node of the star graph. If both ``num_nodes`` and -/// ``weights`` are set this will be ignored and ``weights`` will be used. +/// ``weights`` are set, this will be ignored and ``weights`` will be used. /// :param bool multigraph: When set to ``False`` the output /// :class:`~rustworkx.PyGraph` object will not be not be a multigraph and /// won't allow parallel edges to be added. Instead /// calls which would create a parallel edge will update the existing edge. /// -/// /// :returns: The generated star graph /// :rtype: PyGraph /// :raises IndexError: If neither ``num_nodes`` or ``weights`` are specified @@ -310,15 +310,16 @@ pub fn star_graph( }) } -/// Generate a directed star graph +/// Generate a directed star graph. /// /// :param int num_nodes: The number of nodes to generate the graph with. Node /// weights will be None if this is specified. If both ``num_nodes`` and -/// ``weights`` are set this will be ignored and ``weights`` will be used. -/// :param list weights: A list of node weights, the first element in the list +/// ``weights`` are set, this will be ignored and ``weights`` will be used. +/// :param Sequence[Any] weights: A sequence of node weights, typically a list. +/// The first element in the list /// will be the center node of the star graph. If both ``num_nodes`` and -/// ``weights`` are set this will be ignored and ``weights`` will be used. -/// :param bool inward: If set ``True`` the nodes will be directed towards the +/// ``weights`` are set, this will be ignored and ``weights`` will be used. +/// :param bool inward: If set to ``True``, the nodes will be directed towards the /// center node. This parameter is ignored if ``bidirectional`` is set to /// ``True``. /// :param bool bidirectional: Adds edges in both directions between two nodes @@ -386,13 +387,14 @@ pub fn directed_star_graph( }) } -/// Generate an undirected mesh (complete) graph where every node is connected to every other +/// Generate an undirected mesh (complete) graph where every node is connected to every other. /// /// :param int num_nodes: The number of nodes to generate the graph with. Node /// weights will be None if this is specified. If both ``num_nodes`` and -/// ``weights`` are set this will be ignored and ``weights`` will be used. -/// :param list weights: A list of node weights. If both ``num_nodes`` and -/// ``weights`` are set this will be ignored and ``weights`` will be used. +/// ``weights`` are set, this will be ignored and ``weights`` will be used. +/// :param Sequence[Any] weights: A sequence of node weights, typically a list. +/// If both ``num_nodes`` and +/// ``weights`` are set, this will be ignored and ``weights`` will be used. /// :param bool multigraph: When set to ``False`` the output /// :class:`~rustworkx.PyGraph` object will not be not be a multigraph and /// won't allow parallel edges to be added. Instead @@ -423,13 +425,14 @@ pub fn mesh_graph( complete_graph(py, num_nodes, weights, multigraph) } -/// Generate a directed mesh (complete) graph where every node is connected to every other +/// Generate a directed mesh (complete) graph where every node is connected to every other. /// /// :param int num_nodes: The number of nodes to generate the graph with. Node /// weights will be None if this is specified. If both ``num_nodes`` and -/// ``weights`` are set this will be ignored and ``weights`` will be used. -/// :param list weights: A list of node weights. If both ``num_nodes`` and -/// ``weights`` are set this will be ignored and ``weights`` will be used. +/// ``weights`` are set, this will be ignored and ``weights`` will be used. +/// :param Sequence[Any] weights: A sequence of node weights, typically a list. +/// If both ``num_nodes`` and +/// ``weights`` are set, this will be ignored and ``weights`` will be used. /// :param bool multigraph: When set to ``False`` the output /// :class:`~rustworkx.PyDiGraph` object will not be not be a multigraph and /// won't allow parallel edges to be added. Instead @@ -465,16 +468,17 @@ pub fn directed_mesh_graph( /// :param int rows: The number of rows to generate the graph with. /// If specified, ``cols`` also need to be specified /// :param int cols: The number of cols to generate the graph with. -/// If specified, ``rows`` also need to be specified. rows*cols +/// If specified, ``rows`` also need to be specified. ``rows * cols`` /// defines the number of nodes in the graph -/// :param list weights: A list of node weights. Nodes are filled row wise. +/// :param Sequence[Any] weights: A sequence of node weights, typically a list. +/// Nodes are filled row wise. /// If rows and cols are not specified, then a linear graph containing /// all the values in weights list is created. -/// If number of nodes(rows*cols) is less than length of +/// If number of nodes (``rows * cols``) is less than length of /// weights list, the trailing weights are ignored. -/// If number of nodes(rows*cols) is greater than length of +/// If number of nodes (``rows * cols``) is greater than length of /// weights list, extra nodes with None weight are appended. -/// :param bool multigraph: When set to ``False`` the output +/// :param bool multigraph: When set to ``False``, the output /// :class:`~rustworkx.PyGraph` object will not be not be a multigraph and /// won't allow parallel edges to be added. Instead /// calls which would create a parallel edge will update the existing edge. @@ -523,17 +527,18 @@ pub fn grid_graph( /// /// :param int rows: The number of rows to generate the graph with. /// If specified, ``cols`` also need to be specified. -/// :param int cols: The number of cols to generate the graph with. -/// If specified, ``rows`` also need to be specified. rows*cols +/// :param int cols: The number of columns to generate the graph with. +/// If specified, ``rows`` also need to be specified. ``rows * cols`` /// defines the number of nodes in the graph. -/// :param list weights: A list of node weights. Nodes are filled row wise. +/// :param Sequence[Any] weights: A sequence of node weights, typically a list. +/// Nodes are filled row wise. /// If rows and cols are not specified, then a linear graph containing /// all the values in weights list is created. -/// If number of nodes(rows*cols) is less than length of +/// If number of nodes(``rows * cols``) is less than length of /// weights list, the trailing weights are ignored. -/// If number of nodes(rows*cols) is greater than length of +/// If number of nodes(``rows * cols``) is greater than length of /// weights list, extra nodes with None weight are appended. -/// :param bidirectional: A parameter to indicate if edges should exist in +/// :param bool bidirectional: A parameter to indicate if edges should exist in /// both directions between nodes. Defaults to ``False``. /// :param bool multigraph: When set to ``False`` the output /// :class:`~rustworkx.PyDiGraph` object will not be not be a multigraph and @@ -617,10 +622,10 @@ pub fn directed_grid_graph( /// This function implements Fig 10.b left of the `paper `_. /// This function doesn't support the variant Fig 10.b right. /// -/// Note that if ``d`` is set to ``1`` a :class:`~rustworkx.PyGraph` with a +/// Note that if ``d`` is set to ``1``, a :class:`~rustworkx.PyGraph` with a /// single node will be returned. /// -/// :param int d: distance of the code. If ``d`` is set to ``1`` a +/// :param int d: distance of the code. If ``d`` is set to ``1``, a /// :class:`~rustworkx.PyGraph` with a single node will be returned. ``d`` must be /// an odd number. /// :param bool multigraph: When set to ``False`` the output @@ -630,7 +635,7 @@ pub fn directed_grid_graph( /// /// :returns: The generated heavy square graph /// :rtype: PyGraph -/// :raises IndexError: If d is even. +/// :raises IndexError: If ``d`` is even /// /// .. jupyter-execute:: /// @@ -690,10 +695,10 @@ pub fn heavy_square_graph(py: Python, d: usize, multigraph: bool) -> PyResult`_. /// This function doesn't support the variant Fig 10.b right. /// -/// :param int d: distance of the code. If ``d`` is set to ``1`` a +/// :param int d: distance of the code. If ``d`` is set to ``1``, a /// :class:`~rustworkx.PyDiGraph` with a single node will be returned. ``d`` must be /// an odd number. -/// :param bidirectional: A parameter to indicate if edges should exist in +/// :param bool bidirectional: A parameter to indicate if edges should exist in /// both directions between nodes. Defaults to ``False``. /// :param bool multigraph: When set to ``False`` the output /// :class:`~rustworkx.PyDiGraph` object will not be not be a multigraph and @@ -702,7 +707,7 @@ pub fn heavy_square_graph(py: Python, d: usize, multigraph: bool) -> PyResult PyResult PyResult (f64, f64) { /// Generate an undirected hexagonal lattice graph. /// -/// :param int rows: The number of rows to generate the graph with. -/// :param int cols: The number of columns to generate the graph with. -/// :param bool multigraph: When set to ``False`` the output +/// :param int rows: The number of rows to generate the graph with +/// :param int cols: The number of columns to generate the graph with +/// :param bool multigraph: When set to ``False``, the output /// :class:`~rustworkx.PyGraph` object will not be not be a multigraph and /// won't allow parallel edges to be added. Instead /// calls which would create a parallel edge will update the existing edge. -/// :param bool periodic: When set to ``True`` the boundaries of the lattice +/// :param bool periodic: When set to ``True``, the boundaries of the lattice /// will be joined to form a periodic grid. Requires ``cols`` to be even, /// ``rows > 1``, and ``cols > 1``. /// :param bool with_positions: When set to ``True`` each node will be assigned /// a pair of coordinates ``(x, y)`` as a weight. This embeds the nodes in /// the plane so that each hexagon is regular (with side length 1). /// -/// :returns: The generated hexagonal lattice graph. -/// +/// :returns: The generated hexagonal lattice graph /// :rtype: PyGraph -/// :raises TypeError: If either ``rows`` or ``cols`` are -/// not specified +/// :raises TypeError: If either ``rows`` or ``cols`` are not specified /// /// .. jupyter-execute:: /// @@ -1190,8 +1196,8 @@ pub fn hexagonal_lattice_graph( /// The edges propagate towards right and bottom direction if ``bidirectional`` is ``False`` /// /// :param int rows: The number of rows to generate the graph with. -/// :param int cols: The number of rows to generate the graph with. -/// :param bidirectional: A parameter to indicate if edges should exist in +/// :param int cols: The number of columns to generate the graph with. +/// :param bool bidirectional: A parameter to indicate if edges should exist in /// both directions between nodes. Defaults to ``False``. /// :param bool multigraph: When set to ``False`` the output /// :class:`~rustworkx.PyDiGraph` object will not be not be a multigraph and @@ -1204,11 +1210,9 @@ pub fn hexagonal_lattice_graph( /// a pair of coordinates ``(x, y)`` as a payload. This embeds the nodes in /// the plane so that each hexagon is regular (with side length 1). /// -/// :returns: The generated directed hexagonal lattice graph. -/// +/// :returns: The generated directed hexagonal lattice graph /// :rtype: PyDiGraph -/// :raises TypeError: If either ``rows`` or ``cols`` are -/// not specified +/// :raises TypeError: If either ``rows`` or ``cols`` are not specified /// /// .. jupyter-execute:: /// @@ -1276,22 +1280,24 @@ pub fn directed_hexagonal_lattice_graph( /// path. /// /// If neither ``num_path_nodes`` nor ``path_weights`` (both described -/// below) are specified then this is equivalent to +/// below) are specified, then this is equivalent to /// :func:`~rustworkx.generators.complete_graph` /// /// :param int num_mesh_nodes: The number of nodes to generate the mesh graph /// with. Node weights will be None if this is specified. If both -/// ``num_mesh_nodes`` and ``mesh_weights`` are set this will be ignored and +/// ``num_mesh_nodes`` and ``mesh_weights`` are set, this will be ignored and /// ``mesh_weights`` will be used. /// :param int num_path_nodes: The number of nodes to generate the path /// with. Node weights will be None if this is specified. If both -/// ``num_path_nodes`` and ``path_weights`` are set this will be ignored and +/// ``num_path_nodes`` and ``path_weights`` are set, this will be ignored and /// ``path_weights`` will be used. -/// :param list mesh_weights: A list of node weights for the mesh graph. If both -/// ``num_mesh_nodes`` and ``mesh_weights`` are set ``num_mesh_nodes`` will +/// :param Sequence[Any] mesh_weights: A sequence of node weights for the mesh graph, +/// typically a list. If both +/// ``num_mesh_nodes`` and ``mesh_weights`` are set, ``num_mesh_nodes`` will /// be ignored and ``mesh_weights`` will be used. -/// :param list path_weights: A list of node weights for the path. If both -/// ``num_path_nodes`` and ``path_weights`` are set ``num_path_nodes`` will +/// :param Sequence[Any] path_weights: A sequence of node weights for the path, +/// typically a list. If both +/// ``num_path_nodes`` and ``path_weights`` are set, ``num_path_nodes`` will /// be ignored and ``path_weights`` will be used. /// :param bool multigraph: When set to ``False`` the output /// :class:`~rustworkx.PyGraph` object will not be not be a multigraph and @@ -1354,21 +1360,23 @@ pub fn lollipop_graph( /// /// :param int num_mesh_nodes: The number of nodes to generate the mesh graphs /// with. Node weights will be None if this is specified. If both -/// ``num_mesh_nodes`` and ``mesh_weights`` are set this will be ignored and +/// ``num_mesh_nodes`` and ``mesh_weights`` are set, this will be ignored and /// ``mesh_weights`` will be used. /// :param int num_path_nodes: The number of nodes to generate the path /// with. Node weights will be None if this is specified. If both -/// ``num_path_nodes`` and ``path_weights`` are set this will be ignored and +/// ``num_path_nodes`` and ``path_weights`` are set, this will be ignored and /// ``path_weights`` will be used. -/// :param bool multigraph: When set to ``False`` the output +/// :param bool multigraph: When set to ``False``, the output /// :class:`~rustworkx.PyGraph` object will not be not be a multigraph and /// won't allow parallel edges to be added. Instead /// calls which would create a parallel edge will update the existing edge. -/// :param list mesh_weights: A list of node weights for the mesh graph. If both -/// ``num_mesh_nodes`` and ``mesh_weights`` are set ``num_mesh_nodes`` will +/// :param Sequence[Any] mesh_weights: A sequence of node weights for the path, +/// typically a list. If both +/// ``num_mesh_nodes`` and ``mesh_weights`` are set, ``num_mesh_nodes`` will /// be ignored and ``mesh_weights`` will be used. -/// :param list path_weights: A list of node weights for the path. If both -/// ``num_path_nodes`` and ``path_weights`` are set ``num_path_nodes`` will +/// :param Sequence[Any] path_weights: A sequence of node weights for the path, +/// typically a list. If both +/// ``num_path_nodes`` and ``path_weights`` are set, ``num_path_nodes`` will /// be ignored and ``path_weights`` will be used. /// /// :returns: The generated barbell graph @@ -1433,13 +1441,10 @@ pub fn barbell_graph( /// won't allow parallel edges to be added. Instead /// calls which would create a parallel edge will update the existing edge. /// -/// :returns: The generated generalized Petersen graph. -/// +/// :returns: The generated generalized Petersen graph /// :rtype: PyGraph -/// :raises IndexError: If either ``n`` or ``k`` are -/// not valid -/// :raises TypeError: If either ``n`` or ``k`` are -/// not non-negative integers +/// :raises IndexError: If either ``n`` or ``k`` are not valid +/// :raises TypeError: If either ``n`` or ``k`` are not non-negative integers /// /// .. jupyter-execute:: /// @@ -1495,7 +1500,7 @@ pub fn generalized_petersen_graph( /// Generate an undirected empty graph with ``n`` nodes and no edges. /// -/// :param int n: The number of nodes to generate the graph with. +/// :param int n: The number of nodes to generate the graph with /// /// :returns: The generated empty graph /// :rtype: PyGraph @@ -1527,7 +1532,7 @@ pub fn empty_graph(py: Python, n: usize, multigraph: bool) -> PyResult PyResult PyResult