_dispatchable

_dispatchable(func=None, *, name=None, graphs='G', edge_attrs=None, node_attrs=None, preserve_edge_attrs=False, preserve_node_attrs=False, preserve_graph_attrs=False, preserve_all_attrs=False, mutates_input=False, returns_graph=False)

A decorator function that is used to redirect the execution of func function to its backend implementation.

This decorator function dispatches to a different backend implementation based on the input graph types, and it also manages all the backend_kwargs. Usage can be any of the following decorator forms:

• @_dispatchable

• @_dispatchable()

• @_dispatchable(name="override_name")

• @_dispatchable(graphs="graph_var_name")

• @_dispatchable(edge_attrs="weight")

• @_dispatchable(graphs={"G": 0, "H": 1}, edge_attrs={"weight": "default"})

  with 0 and 1 giving the position in the signature function for graph objects. When edge_attrs is a dict, keys are keyword names and values are defaults.

Parameters:

funccallable, optional

The function to be decorated. If func is not provided, returns a partial object that can be used to decorate a function later. If func is provided, returns a new callable object that dispatches to a backend algorithm based on input graph types.

namestr, optional

The name of the algorithm to use for dispatching. If not provided, the name of func will be used. name is useful to avoid name conflicts, as all dispatched algorithms live in a single namespace. For example, tournament.is_strongly_connected had a name conflict with the standard nx.is_strongly_connected, so we used @_dispatchable(name="tournament_is_strongly_connected").

graphsstr or dict or None, default “G”

If a string, the parameter name of the graph, which must be the first argument of the wrapped function. If more than one graph is required for the algorithm (or if the graph is not the first argument), provide a dict keyed to argument names with argument position as values for each graph argument. For example, @_dispatchable(graphs={"G": 0, "auxiliary?": 4}) indicates the 0th parameter G of the function is a required graph, and the 4th parameter auxiliary? is an optional graph. To indicate that an argument is a list of graphs, do "[graphs]". Use graphs=None, if no arguments are NetworkX graphs such as for graph generators, readers, and conversion functions.

edge_attrsstr or dict, optional

edge_attrs holds information about edge attribute arguments and default values for those edge attributes. If a string, edge_attrs holds the function argument name that indicates a single edge attribute to include in the converted graph. The default value for this attribute is 1. To indicate that an argument is a list of attributes (all with default value 1), use e.g. "[attrs]". If a dict, edge_attrs holds a dict keyed by argument names, with values that are either the default value or, if a string, the argument name that indicates the default value.

node_attrsstr or dict, optional

Like edge_attrs, but for node attributes.

preserve_edge_attrsbool or str or dict, optional

For bool, whether to preserve all edge attributes. For str, the parameter name that may indicate (with True or a callable argument) whether all edge attributes should be preserved when converting. For dict of {graph_name: {attr: default}}, indicate pre-determined edge attributes (and defaults) to preserve for input graphs.

preserve_node_attrsbool or str or dict, optional

Like preserve_edge_attrs, but for node attributes.

preserve_graph_attrsbool or set

For bool, whether to preserve all graph attributes. For set, which input graph arguments to preserve graph attributes.

preserve_all_attrsbool

Whether to preserve all edge, node and graph attributes. This overrides all the other preserve_*_attrs.

mutates_inputbool or dict, default False

For bool, whether the function mutates an input graph argument. For dict of {arg_name: arg_pos}, arguments that indicate whether an input graph will be mutated, and arg_name may begin with "not " to negate the logic (for example, this is used by copy= arguments). By default, dispatching doesn’t convert input graphs to a different backend for functions that mutate input graphs.

returns_graphbool, default False

Whether the function can return or yield a graph object. By default, dispatching doesn’t convert input graphs to a different backend for functions that return graphs.