docstr: Dispatches to a backend algorithm based on input graph types.
  
  Parameters
  ----------
  func : function
  
  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.
  
  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 of parameter name to argument position 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 an argument is a list of graphs, do e.g. ``"[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.
docstr_tok: ["Dispatches","to","a","backend","algorithm","based","on","input","graph","types",".","Parameters","--","--","--","--","--","func",":","function","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",".","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","of","parameter","name","to","argument","position","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","an","argument","is","a","list","of","graphs",",","do","e.g",".","``","``","[","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","."]
code: def __new__(
      cls,
      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,
  ):
      """Dispatches to a backend algorithm based on input graph types.
  
      Parameters
      ----------
      func : function
  
      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.
  
      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 of parameter name to argument position 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 an argument is a list of graphs, do e.g. ``"[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.
  
      """
      if func is None:
          return partial(
              _dispatchable,
              name=name,
              graphs=graphs,
              edge_attrs=edge_attrs,
              node_attrs=node_attrs,
              preserve_edge_attrs=preserve_edge_attrs,
              preserve_node_attrs=preserve_node_attrs,
              preserve_graph_attrs=preserve_graph_attrs,
              preserve_all_attrs=preserve_all_attrs,
          )
      if isinstance(func, str):
          raise TypeError(
              "'name' and 'graphs' must be passed by keyword"
          ) from None
      # If name not provided, use the name of the function
      if name is None:
          name = func.__name__
  
      self = object.__new__(cls)
  
      # standard function-wrapping stuff
      # __annotations__ not used
      self.__name__ = func.__name__
      # self.__doc__ = func.__doc__  # __doc__ handled as cached property
      self.__defaults__ = func.__defaults__
      # We "magically" add `backend=` keyword argument to allow backend to be specified
      if func.__kwdefaults__:
          self.__kwdefaults__ = {**func.__kwdefaults__, "backend": None}
      else:
          self.__kwdefaults__ = {"backend": None}
      self.__module__ = func.__module__
      self.__qualname__ = func.__qualname__
      self.__dict__.update(func.__dict__)
      self.__wrapped__ = func
  
      # Supplement docstring with backend info; compute and cache when needed
      self._orig_doc = func.__doc__
      self._cached_doc = None
  
      self.orig_func = func
      self.name = name
      self.edge_attrs = edge_attrs
      self.node_attrs = node_attrs
      self.preserve_edge_attrs = (
          preserve_edge_attrs or preserve_all_attrs
      )
      self.preserve_node_attrs = (
          preserve_node_attrs or preserve_all_attrs
      )
      self.preserve_graph_attrs = (
          preserve_graph_attrs or preserve_all_attrs
      )
  
      if edge_attrs is not None and not isinstance(
          edge_attrs, str | dict
      ):
          raise TypeError(
              f"Bad type for edge_attrs: {type(edge_attrs)}. Expected str or dict."
          ) from None
      if node_attrs is not None and not isinstance(
          node_attrs, str | dict
      ):
          raise TypeError(
              f"Bad type for node_attrs: {type(node_attrs)}. Expected str or dict."
          ) from None
      if not isinstance(self.preserve_edge_attrs, bool | str | dict):
          raise TypeError(
              f"Bad type for preserve_edge_attrs: {type(self.preserve_edge_attrs)}."
              " Expected bool, str, or dict."
          ) from None
      if not isinstance(self.preserve_node_attrs, bool | str | dict):
          raise TypeError(
              f"Bad type for preserve_node_attrs: {type(self.preserve_node_attrs)}."
              " Expected bool, str, or dict."
          ) from None
      if not isinstance(self.preserve_graph_attrs, bool | set):
          raise TypeError(
              f"Bad type for preserve_graph_attrs: {type(self.preserve_graph_attrs)}."
              " Expected bool or set."
          ) from None
  
      if isinstance(graphs, str):
          graphs = {graphs: 0}
      elif graphs is None:
          pass
      elif not isinstance(graphs, dict):
          raise TypeError(
              f"Bad type for graphs: {type(graphs)}. Expected str or dict."
          ) from None
      elif len(graphs) == 0:
          raise KeyError(
              "'graphs' must contain at least one variable name"
          ) from None
  
      # This dict comprehension is complicated for better performance; equivalent shown below.
      self.optional_graphs = set()
      self.list_graphs = set()
      if graphs is None:
          self.graphs = {}
      else:
          self.graphs = {
              self.optional_graphs.add(val := k[:-1]) or val
              if (last := k[-1]) == "?"
              else self.list_graphs.add(val := k[1:-1]) or val
              if last == "]"
              else k: v
              for k, v in graphs.items()
          }
      # The above is equivalent to:
      # self.optional_graphs = {k[:-1] for k in graphs if k[-1] == "?"}
      # self.list_graphs = {k[1:-1] for k in graphs if k[-1] == "]"}
      # self.graphs = {k[:-1] if k[-1] == "?" else k: v for k, v in graphs.items()}
  
      # Compute and cache the signature on-demand
      self._sig = None
  
      # Which backends implement this function?
      self.backends = {
          backend
          for backend, info in backend_info.items()
          if "functions" in info and name in info["functions"]
      }
  
      if name in _registered_algorithms:
          raise KeyError(
              f"Algorithm already exists in dispatch registry: {name}"
          ) from None
      _registered_algorithms[name] = self
      return self
  
imports: import inspect
  import os
  import sys
  import warnings
  from functools import partial
  from importlib.metadata import entry_points
  import networkx
  from ..exception import NetworkXNotImplemented
label_desc: Use image node_id 1 for calling the _dispatchable obj's underlying member method code with example usage: obj.__new__(cls, func) and returns: self, partial