Skip to main content
`Ctrl`+`K`

# _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:
    func callable, 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.

    name str, 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")`.

    graphs str 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_attrs str 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_attrs str or dict, optional

      Like `edge_attrs`, but for node attributes.

    preserve_edge_attrs bool 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_attrs bool or str or dict, optional

      Like `preserve_edge_attrs`, but for node attributes.

    preserve_graph_attrs bool or set

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

    preserve_all_attrs bool

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

    mutates_input bool 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_graph bool, 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.