plugin based backend infrastructure to use multiple computation backends (#6000)

* Wrappers classes to dispatch to a backend

* Rework the backend dispatching

- Use __networkx_plugin__=name to find graph-like objects instead of
  subclassing
- Add PluginInfo to smooth over differences in importlib.metadata across
  python versions
- Add dispatch behavior override via environment variable to aid in
  testing plugins

* Dispatch more algorithms and improve auto-test capabilities

* Allow dispatcher decorator without a name

- Name is taken from the decorated function
- Raise error if backend doesn't implement a decorated function which is called
- Check for duplicate names for dispatching algorithms

* Make sphinx pick up backend docs

* make black happy

* Rename decorator to _dispatch as it's experimental

* A few more dispatched functions

* Make convert to and from methods for auto-testing

- Rename `convert` to `convert_from_nx`
- Add `convert_to_nx` function

These will allow backends to return native objects when dispatching,
but provide a mechanism to convert the result to the type expected
by NetworkX tests for the auto-test plugin mechanism.

* More dispatching

* Include name with `convert_**_nx` methods

* Remove known plugin names

This check is not needed, as any plugin can register itself in the entry points section.
The dispatching and auto-testing explicitly specify the plugin to use, so there is no
need to hardcode the options.
These were originally included for security, but any malicious actor would simply use one
of the valid names, so having a hardcoded list does not actually provide any meaningful
security.

* Add `dispatchname` to dispatchable functions

Co-authored-by: Jim Kitchen <jim22k@gmail.com>
Co-authored-by: Erik Welch <erik.n.welch@gmail.com>

1 files changed, 13 insertions, 0 deletions

diff --git a/doc/reference/classes/index.rst b/doc/reference/classes/index.rst
index 0f0b6891..a4acd53c 100644
--- a/doc/reference/classes/index.rst
+++ b/doc/reference/classes/index.rst
@@ -95,3 +95,16 @@ Filters
    show_diedges
    show_multidiedges
    show_multiedges
+
+Backends
+========
+
+.. note:: This is an experimental feature to dispatch your computations to an
+   alternate backend like GraphBLAS, instead of using pure Python dictionaries
+   for computation. Things will change and break in the future!
+
+.. automodule:: networkx.classes.backends
+.. autosummary::
+   :toctree: generated/
+
+   _dispatch