Add nx.config dict for configuring dispatching and backends

networkx/__init__.py

@@ -17,7 +17,7 @@
 from networkx.exception import *
 
 from networkx import utils
-from networkx.utils.backends import _dispatchable
+from networkx.utils.backends import _dispatchable, config
 
 from networkx import classes
 from networkx.classes import filters

networkx/algorithms/operators/tests/test_binary.py

@@ -53,7 +53,7 @@ def test_intersection():
     assert set(I2.nodes()) == {1, 2, 3, 4}
     assert sorted(I2.edges()) == [(2, 3)]
     # Only test if not performing auto convert testing of backend implementations
-    if not nx.utils.backends._dispatchable._automatic_backends:
+    if not nx.config["backend_priority"]:
         with pytest.raises(TypeError):
             nx.intersection(G2, H)
         with pytest.raises(TypeError):

networkx/classes/tests/test_backends.py

@@ -31,8 +31,8 @@ def test_pickle():
 
 
 @pytest.mark.skipif(
-    "not nx._dispatchable._automatic_backends "
-    "or nx._dispatchable._automatic_backends[0] != 'nx-loopback'"
+    "not nx.config['backend_priority'] "
+    "or nx.config['backend_priority'][0] != 'nx-loopback'"
 )
 def test_graph_converter_needs_backend():
     # When testing, `nx.from_scipy_sparse_array` will *always* call the backend

networkx/conftest.py

@@ -45,12 +45,6 @@ def pytest_configure(config):
     backend = config.getoption("--backend")
     if backend is None:
         backend = os.environ.get("NETWORKX_TEST_BACKEND")
-    if backend:
-        networkx.utils.backends._dispatchable._automatic_backends = [backend]
-        fallback_to_nx = config.getoption("--fallback-to-nx")
-        if not fallback_to_nx:
-            fallback_to_nx = os.environ.get("NETWORKX_FALLBACK_TO_NX")
-        networkx.utils.backends._dispatchable._fallback_to_nx = bool(fallback_to_nx)
     # nx-loopback backend is only available when testing
     backends = entry_points(name="nx-loopback", group="networkx.backends")
     if backends:
@@ -64,16 +58,22 @@ def pytest_configure(config):
             "        Try `pip install -e .`, or change your PYTHONPATH\n"
             "        Make sure python finds the networkx repo you are testing\n\n"
         )
+    if backend:
+        networkx.config["backend_priority"] = [backend]
+        fallback_to_nx = config.getoption("--fallback-to-nx")
+        if not fallback_to_nx:
+            fallback_to_nx = os.environ.get("NETWORKX_FALLBACK_TO_NX")
+        networkx.utils.backends._dispatchable._fallback_to_nx = bool(fallback_to_nx)
 
 
 def pytest_collection_modifyitems(config, items):
     # Setting this to True here allows tests to be set up before dispatching
     # any function call to a backend.
     networkx.utils.backends._dispatchable._is_testing = True
-    if automatic_backends := networkx.utils.backends._dispatchable._automatic_backends:
+    if backend_priority := networkx.config["backend_priority"]:
         # Allow pluggable backends to add markers to tests (such as skip or xfail)
         # when running in auto-conversion test mode
-        backend = networkx.utils.backends.backends[automatic_backends[0]].load()
+        backend = networkx.utils.backends.backends[backend_priority[0]].load()
         if hasattr(backend, "on_start_tests"):
             getattr(backend, "on_start_tests")(items)
 

networkx/utils/backends.py

@@ -106,7 +106,7 @@ class WrappedSparse:
 from ..exception import NetworkXNotImplemented
 from .decorators import argmap
 
-__all__ = ["_dispatchable"]
+__all__ = ["_dispatchable", "config"]
 
 
 def _do_nothing():
@@ -142,6 +142,31 @@ def _get_backends(group, *, load_and_call=False):
 backends = _get_backends("networkx.backends")
 backend_info = _get_backends("networkx.backend_info", load_and_call=True)
 
+# We must import from config after defining `backends` above
+from .configs import Config, config
+
+# Get default configuration from environment variables at import time
+config.backend_priority = [
+    x.strip()
+    for x in os.environ.get(
+        "NETWORKX_BACKEND_PRIORITY",
+        os.environ.get("NETWORKX_AUTOMATIC_BACKENDS", ""),
+    ).split(",")
+    if x.strip()
+]
+# Initialize default configuration for backends
+config.backends = Config(
+    **{
+        backend: (
+            cfg if isinstance(cfg := info["default_config"], Config) else Config(**cfg)
+        )
+        if "default_config" in info
+        else Config()
+        for backend, info in backend_info.items()
+    }
+)
+type(config.backends).__doc__ = "All installed NetworkX backends and their configs."
+
 # Load and cache backends on-demand
 _loaded_backends = {}  # type: ignore[var-annotated]
 
@@ -180,11 +205,6 @@ class _dispatchable:
     _fallback_to_nx = (
         os.environ.get("NETWORKX_FALLBACK_TO_NX", "true").strip().lower() == "true"
     )
-    _automatic_backends = [
-        x.strip()
-        for x in os.environ.get("NETWORKX_AUTOMATIC_BACKENDS", "").split(",")
-        if x.strip()
-    ]
 
     def __new__(
         cls,
@@ -532,11 +552,12 @@ def __call__(self, /, *args, backend=None, **kwargs):
                     for g in graphs_resolved.values()
                 }
 
-        if self._is_testing and self._automatic_backends and backend_name is None:
+        backend_priority = config.backend_priority
+        if self._is_testing and backend_priority and backend_name is None:
             # Special path if we are running networkx tests with a backend.
             # This even runs for (and handles) functions that mutate input graphs.
             return self._convert_and_call_for_tests(
-                self._automatic_backends[0],
+                backend_priority[0],
                 args,
                 kwargs,
                 fallback_to_nx=self._fallback_to_nx,
@@ -563,7 +584,7 @@ def __call__(self, /, *args, backend=None, **kwargs):
                 raise ImportError(f"Unable to load backend: {graph_backend_name}")
             if (
                 "networkx" in graph_backend_names
-                and graph_backend_name not in self._automatic_backends
+                and graph_backend_name not in backend_priority
             ):
                 # Not configured to convert networkx graphs to this backend
                 raise TypeError(
@@ -584,7 +605,7 @@ def __call__(self, /, *args, backend=None, **kwargs):
                     )
                 # All graphs are backend graphs--no need to convert!
                 return getattr(backend, self.name)(*args, **kwargs)
-            # Future work: try to convert and run with other backends in self._automatic_backends
+            # Future work: try to convert and run with other backends in backend_priority
             raise NetworkXNotImplemented(
                 f"'{self.name}' not implemented by {graph_backend_name}"
             )
@@ -622,7 +643,7 @@ def __call__(self, /, *args, backend=None, **kwargs):
             )
         ):
             # Should we warn or log if we don't convert b/c the input will be mutated?
-            for backend_name in self._automatic_backends:
+            for backend_name in backend_priority:
                 if self._should_backend_run(backend_name, *args, **kwargs):
                     return self._convert_and_call(
                         backend_name,

networkx/utils/configs.py

@@ -0,0 +1,183 @@
+import collections
+import types
+import typing
+from dataclasses import dataclass
+
+__all__ = ["Config", "config"]
+
+
+@dataclass(init=False, eq=False, slots=True, kw_only=True, match_args=False)
+class Config:
+    """The base class for NetworkX configuration.
+
+    There are two ways to use this to create configurations. The first is to
+    simply pass the initial configuration as keyword arguments to ``Config``:
+
+    >>> cfg = Config(eggs=1, spam=5)
+    >>> cfg
+    Config(eggs=1, spam=5)
+
+    The second--and preferred--way is to subclass ``Config`` with docs and annotations.
+
+    >>> class MyConfig(Config):
+    ...     '''Breakfast!'''
+    ...
+    ...     eggs: int
+    ...     spam: int
+    ...
+    ...     def _check_config(self, key, value):
+    ...         assert isinstance(value, int) and value >= 0
+    >>> cfg = MyConfig(eggs=1, spam=5)
+
+    Once defined, configuration items may be modified, but can't be added or deleted.
+    ``Config`` is a ``Mapping``, and can get and set configs via attributes or brackets:
+
+    >>> cfg.eggs = 2
+    >>> cfg.eggs
+    2
+    >>> cfg["spam"] = 42
+    >>> cfg["spam"]
+    42
+
+    Subclasses may also define ``_check_config`` (as done in the example above)
+    to ensure the value being assigned is valid:
+
+    >>> cfg.spam = -1
+    Traceback (most recent call last):
+        ...
+    AssertionError
+
+    """
+
+    def __new__(cls, **kwargs):
+        orig_class = cls
+        if cls is Config:
+            # Enable the "simple" case of accepting config definition as keywords
+            cls = type(
+                cls.__name__,
+                (cls,),
+                {"__annotations__": {key: typing.Any for key in kwargs}},
+            )
+        cls = dataclass(eq=False, slots=True, kw_only=True, match_args=False)(cls)
+        cls._orig_class = orig_class  # Save original class so we can pickle
+        instance = object.__new__(cls)
+        instance.__init__(**kwargs)
+        return instance
+
+    def _check_config(self, key, value):
+        """Check whether config value is valid. This is useful for subclasses."""
+
+    # Control behavior of attributes
+    def __dir__(self):
+        return self.__dataclass_fields__.keys()
+
+    def __setattr__(self, key, value):
+        if key not in self.__dataclass_fields__:
+            raise AttributeError(f"Invalid config name: {key!r}")
+        self._check_config(key, value)
+        object.__setattr__(self, key, value)
+
+    def __delattr__(self, key):
+        raise TypeError(f"Configuration items can't be deleted (can't delete {key!r}).")
+
+    # Be a `collection.abc.Collection`
+    def __contains__(self, key):
+        return key in self.__dataclass_fields__
+
+    def __iter__(self):
+        return iter(self.__dataclass_fields__)
+
+    def __len__(self):
+        return len(self.__dataclass_fields__)
+
+    def __reversed__(self):
+        return reversed(self.__dataclass_fields__)
+
+    # Add dunder methods for `collections.abc.Mapping`
+    def __getitem__(self, key):
+        try:
+            return getattr(self, key)
+        except AttributeError as err:
+            raise KeyError(*err.args) from None
+
+    def __setitem__(self, key, value):
+        try:
+            setattr(self, key, value)
+        except AttributeError as err:
+            raise KeyError(*err.args) from None
+
+    __delitem__ = __delattr__
+    _ipython_key_completions_ = __dir__  # config["<TAB>
+
+    # Go ahead and make it a `collections.abc.Mapping`
+    def get(self, key, default=None):
+        return getattr(self, key, default)
+
+    def items(self):
+        return collections.abc.ItemsView(self)
+
+    def keys(self):
+        return collections.abc.KeysView(self)
+
+    def values(self):
+        return collections.abc.ValuesView(self)
+
+    # dataclass can define __eq__ for us, but do it here so it works after pickling
+    def __eq__(self, other):
+        if not isinstance(other, Config):
+            return NotImplemented
+        return self._orig_class == other._orig_class and self.items() == other.items()
+
+    # Make pickle work
+    def __reduce__(self):
+        return self._deserialize, (self._orig_class, dict(self))
+
+    @staticmethod
+    def _deserialize(cls, kwargs):
+        return cls(**kwargs)
+
+    # Make type annotations work with key and value types; e.g. Config[str, int]
+    def __class_getitem__(cls, item):
+        return types.GenericAlias(cls, item)
+
+
+# Register, b/c `Mapping.__subclasshook__` returns `NotImplemented`
+collections.abc.Mapping.register(Config)
+
+
+class NetworkXConfig(Config):
+    """Write me!"""
+
+    backend_priority: list[str]
+    backends: Config[str, Config]
+
+    def _check_config(self, key, value):
+        from .backends import backends
+
+        if key == "backend_priority":
+            if not (isinstance(value, list) and all(isinstance(x, str) for x in value)):
+                raise TypeError(
+                    f"{key!r} config must be a list of backend names; got {value!r}"
+                )
+            if missing := {x for x in value if x not in backends}:
+                missing = ", ".join(map(repr, sorted(missing)))
+                raise ValueError(f"Unknown backend when setting {key!r}: {missing}")
+        elif key == "backends":
+            if not (
+                isinstance(value, Config)
+                and all(isinstance(key, str) for key in value)
+                and all(isinstance(val, Config) for val in value.values())
+            ):
+                raise TypeError(
+                    f"{key!r} config must be a Config of backend configs; got {value!r}"
+                )
+            if missing := {x for x in value if x not in backends}:
+                missing = ", ".join(map(repr, sorted(missing)))
+                raise ValueError(f"Unknown backend when setting {key!r}: {missing}")
+
+
+# Backend configuration will be updated in backends.py
+config = NetworkXConfig(
+    backend_priority=[],
+    backends=Config(),
+)