Expose the configuration load mechanism to plugins (#2217)

Author: gaborbernat

.pre-commit-config.yaml

@@ -12,7 +12,7 @@ repos:
       - id: end-of-file-fixer
       - id: trailing-whitespace
   - repo: https://github.com/asottile/pyupgrade
-    rev: v2.25.1
+    rev: v2.26.0
     hooks:
       - id: pyupgrade
         args: ["--py36-plus"]
@@ -66,8 +66,11 @@ repos:
     hooks:
       - id: flake8
         additional_dependencies:
-        - flake8-bugbear==21.4.3
+        - flake8-bugbear==21.9.1
         - flake8-comprehensions==3.6.1
         - flake8-pytest-style==1.5
         - flake8-spellcheck==0.24
         - flake8-unused-arguments==0.0.6
+        - flake8-noqa==1.1.0
+        - flake8-eradicate==1.1.0
+        - pep8-naming==0.12.1

docs/changelog.rst

@@ -97,7 +97,7 @@ Improved Documentation - 4.0.0a7
 - Start documenting the plugin interface. Added :meth:`tox_register_tox_env <tox.plugin.spec.tox_register_tox_env>`,
   :meth:`tox_add_option <tox.plugin.spec.tox_add_option>`,
   :meth:`tox_add_core_config <tox.plugin.spec.tox_add_core_config>`,
-  :meth:`tox_configure <tox.plugin.spec.tox_configure>` - by :user:`gaborbernat`. (`#1991 <https://github.com/tox-dev/tox/issues/1991>`_)
+  ``tox_configure`` - by :user:`gaborbernat`. (`#1991 <https://github.com/tox-dev/tox/issues/1991>`_)
 - Explain how ``-v`` and ``-q`` flags play together to determine CLI verbosity level - by :user:`jugmac00`. (`#2005 <https://github.com/tox-dev/tox/issues/2005>`_)
 - Start polishing the documentation for the upcoming final release - by :user:`jugmac00`. (`#2006 <https://github.com/tox-dev/tox/issues/2006>`_)
 - Update documentation about changelog entries for trivial changes - by :user:`jugmac00`. (`#2007 <https://github.com/tox-dev/tox/issues/2007>`_)

docs/changelog/2191.bugfix.rst

@@ -0,0 +1,5 @@
+Expose the configuration loading mechanism to plugins to define and load their own sections. Add
+:meth:`tox_add_env_config <tox.plugin.spec.tox_add_env_config>` plugin hook called after the configuration environment
+is created for a tox environment and removed ``tox_configure``. Add the main configuration object as argument to
+:meth:`tox_add_core_config <tox.plugin.spec.tox_add_core_config>`. Move the environment list method from the state to
+the main configuration object to allow its use within plugins -- by :user:`gaborbernat`.

docs/changelog/2200.feature.rst

@@ -132,9 +132,13 @@ def resolve_xref(
                 "tox.config.loader.convert.T": "typing.TypeVar",
                 "tox.tox_env.installer.T": "typing.TypeVar",
                 "ToxParserT": "typing.TypeVar",
+                "_Section": "Section",
             }
             if target in mapping:
                 node["reftarget"] = mapping[target]
+            if target == "_Section":
+                target = "Section"
+                contnode = Text(target, target)
 
             return super().resolve_xref(env, fromdocname, builder, type, target, node, contnode)
 

docs/conf.py

@@ -29,6 +29,12 @@ config
    :members:
    :exclude-members: __init__, make
 
+.. autoclass:: tox.config.loader.section.Section
+   :members:
+
+.. autoclass:: tox.config.loader.api.ConfigLoadArgs
+   :members:
+
 .. autoclass:: tox.config.sets.ConfigSet
    :members:
    :special-members: __iter__, __contains__

docs/plugins_api.rst

@@ -23,9 +23,9 @@ def get_env_var(key: str, of_type: Type[Any]) -> Optional[Tuple[Any, str]]:
             value = os.environ[environ_key]
             try:
                 source = f"env var {environ_key}"
-                result = CONVERT.to(raw=value, of_type=of_type, kwargs={})
+                result = CONVERT.to(raw=value, of_type=of_type, factory=None)
                 return result, source
-            except Exception as exception:  # noqa
+            except Exception as exception:
                 logging.warning(
                     "env var %s=%r cannot be transformed to %r because %r",
                     environ_key,

src/tox/config/cli/env_var.py

@@ -9,7 +9,9 @@
 
 from platformdirs import user_config_dir
 
+from tox.config.loader.api import ConfigLoadArgs
 from tox.config.loader.ini import IniLoader
+from tox.config.source.ini_section import CORE
 
 DEFAULT_CONFIG_FILE = Path(user_config_dir("tox")) / "config.ini"
 
@@ -18,8 +20,6 @@ class IniConfig:
     TOX_CONFIG_FILE_ENV_VAR = "TOX_CONFIG_FILE"
     STATE = {None: "failed to parse", True: "active", False: "missing"}
 
-    section = "tox"
-
     def __init__(self) -> None:
         config_file = os.environ.get(self.TOX_CONFIG_FILE_ENV_VAR, None)
         self.is_env_var = config_file is not None
@@ -35,8 +35,9 @@ def __init__(self) -> None:
                 parser = ConfigParser()
                 with self.config_file.open() as file_handler:
                     parser.read_file(file_handler)
-                self.has_tox_section = parser.has_section("tox")
-                self.ini = IniLoader("tox", parser, overrides=[], core_prefix="") if self.has_tox_section else None
+                self.has_tox_section = parser.has_section(CORE.key)
+                if self.has_tox_section:
+                    self.ini = IniLoader(CORE, parser, overrides=[], core_section=CORE)
             except Exception as exception:
                 logging.error("failed to read config file %s because %r", config_file, exception)
                 self.has_config_file = None
@@ -51,11 +52,12 @@ def get(self, key: str, of_type: Type[Any]) -> Any:
                     result = None
                 else:
                     source = "file"
-                    value = self.ini.load(key, of_type=of_type, conf=None, env_name="tox", chain=[key], kwargs={})
+                    args = ConfigLoadArgs(chain=[key], name=CORE.prefix, env_name=None)
+                    value = self.ini.load(key, of_type=of_type, conf=None, factory=None, args=args)
                     result = value, source
             except KeyError:  # just not found
                 result = None
-            except Exception as exception:  # noqa
+            except Exception as exception:
                 logging.warning("%s key %s as type %r failed with %r", self.config_file, key, of_type, exception)
                 result = None
         self._cache[cache_key] = result

src/tox/config/cli/ini.py

@@ -35,7 +35,7 @@ def _get_base(args: Sequence[str]) -> Tuple[int, ToxHandler, Source]:
     parsed, _ = tox_parser.parse_known_args(args)
     guess_verbosity = parsed.verbosity
     handler = setup_report(guess_verbosity, parsed.is_colored)
-    from tox.plugin.manager import MANAGER  # noqa # load the plugin system right after we set up report
+    from tox.plugin.manager import MANAGER  # load the plugin system right after we set up report
 
     source = discover_source(parsed.config_file, parsed.root_dir)
 
@@ -55,7 +55,7 @@ def _get_all(args: Sequence[str]) -> Tuple[Parsed, Handlers]:
 def _get_parser() -> ToxParser:
     tox_parser = ToxParser.core()  # load the core options
     # plus options setup by plugins
-    from tox.plugin.manager import MANAGER  # noqa
+    from tox.plugin.manager import MANAGER
 
     MANAGER.tox_add_option(tox_parser)
     tox_parser.fix_defaults()

src/tox/config/cli/parse.py

@@ -48,8 +48,8 @@ def fix_default(self, action: Action) -> None:
             if outcome is not None:
                 action.default, default_value = outcome
                 action.default_source = default_value  # type: ignore[attr-defined]
-        if isinstance(action, argparse._SubParsersAction):  # noqa
-            for values in action.choices.values():  # noqa
+        if isinstance(action, argparse._SubParsersAction):
+            for values in action.choices.values():
                 if not isinstance(values, ToxParser):  # pragma: no cover
                     raise RuntimeError("detected sub-parser added without using our own add command")
                 values.fix_defaults()
@@ -58,16 +58,16 @@ def fix_default(self, action: Action) -> None:
     def get_type(action: Action) -> Type[Any]:
         of_type: Optional[Type[Any]] = getattr(action, "of_type", None)
         if of_type is None:
-            if isinstance(action, argparse._AppendAction):  # noqa
+            if isinstance(action, argparse._AppendAction):
                 of_type = List[action.type]  # type: ignore[name-defined]
-            elif isinstance(action, argparse._StoreAction) and action.choices:  # noqa
+            elif isinstance(action, argparse._StoreAction) and action.choices:
                 loc = locals()
                 loc["Literal"] = Literal
                 as_literal = f"Literal[{', '.join(repr(i) for i in action.choices)}]"
                 of_type = eval(as_literal, globals(), loc)
             elif action.default is not None:
                 of_type = type(action.default)
-            elif isinstance(action, argparse._StoreConstAction) and action.const is not None:  # noqa
+            elif isinstance(action, argparse._StoreConstAction) and action.const is not None:
                 of_type = type(action.const)
             else:
                 raise TypeError(action)
@@ -84,7 +84,7 @@ def __init__(self, prog: str) -> None:
 
     def _get_help_string(self, action: Action) -> Optional[str]:
 
-        text: str = super()._get_help_string(action) or ""  # noqa
+        text: str = super()._get_help_string(action) or ""
         if hasattr(action, "default_source"):
             default = " (default: %(default)s)"
             if text.endswith(default):  # pragma: no branch