feat: needs

Signed-off-by: Henry Schreiner <[email protected]>

Author: henryiii

README.md

@@ -23,17 +23,16 @@ Every external plugin must specify a "provider", which is a module that provides
 the API listed in the next section.
 
 ```toml
-[tool.dynamic-metadata]
-<field-name>.provider = "<module>"
+[tool.dynamic-metadata.<field-name>]
+provider = "<module>"
 ```
 
 There is an optional field: "provider-path", which specifies a local path to
 load a plugin from, allowing plugins to reside inside your own project.
 
 All other fields are passed on to the plugin, allowing plugins to specify custom
 configuration per field. Plugins can, if desired, use their own `tool.*`
-sections as well; plugins only supporting one metadata field are more likely to
-do this.
+sections as well.
 
 ### Example: regex
 

pyproject.toml

@@ -25,12 +25,14 @@ classifiers = [
   "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
   "Topic :: Scientific/Engineering",
   "Typing :: Typed",
 ]
 dynamic = ["version"]
 dependencies = [
   "typing_extensions >=4.6; python_version<'3.11'",
+  "graphlib_backport >=1; python_version<'3.9'",
 ]
 
 [project.optional-dependencies]
@@ -106,7 +108,7 @@ disallow_untyped_defs = true
 disallow_incomplete_defs = true
 
 [[tool.mypy.overrides]]
-module = "setuptools_scm"
+module = ["setuptools_scm", "graphlib"]
 ignore_missing_imports = true
 
 
@@ -161,4 +163,5 @@ messages_control.disable = [
   "missing-function-docstring",
   "import-outside-toplevel",
   "invalid-name",
+  "unused-argument",  # Ruff
 ]

src/dynamic_metadata/info.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+__all__ = ["ALL_FIELDS", "DICT_STR_FIELDS", "LIST_STR_FIELDS", "STR_FIELDS"]
+
+
+# Name is not dynamically settable, so not in this list
+STR_FIELDS = frozenset(
+    [
+        "version",
+        "description",
+        "requires-python",
+        "license",
+    ]
+)
+
+# Dynamic is not dynamically settable, so not in this list
+LIST_STR_FIELDS = frozenset(
+    [
+        "classifiers",
+        "keywords",
+        "dependencies",
+        "license_files",
+    ]
+)
+
+
+DICT_STR_FIELDS = frozenset(
+    [
+        "urls",
+        "authors",
+        "maintainers",
+    ]
+)
+
+
+# "dynamic" and "name" can't be set or requested
+ALL_FIELDS = (
+    STR_FIELDS
+    | LIST_STR_FIELDS
+    | DICT_STR_FIELDS
+    | frozenset(
+        [
+            "optional-dependencies",
+            "readme",
+        ]
+    )
+)

src/dynamic_metadata/loader.py

@@ -4,7 +4,11 @@
 import sys
 from collections.abc import Generator, Iterable, Mapping
 from pathlib import Path
-from typing import Any, Protocol, Union
+from typing import Any, Protocol, Union, runtime_checkable
+
+from graphlib import TopologicalSorter
+
+from .info import ALL_FIELDS
 
 __all__ = ["load_dynamic_metadata", "load_provider"]
 
@@ -13,34 +17,41 @@ def __dir__() -> list[str]:
     return __all__
 
 
+@runtime_checkable
 class DynamicMetadataProtocol(Protocol):
     def dynamic_metadata(
-        self, fields: Iterable[str], settings: dict[str, Any]
+        self, fields: Iterable[str], settings: dict[str, Any], metadata: dict[str, Any]
     ) -> dict[str, Any]: ...
 
 
+@runtime_checkable
 class DynamicMetadataRequirementsProtocol(DynamicMetadataProtocol, Protocol):
     def get_requires_for_dynamic_metadata(
         self, settings: dict[str, Any]
     ) -> list[str]: ...
 
 
+@runtime_checkable
 class DynamicMetadataWheelProtocol(DynamicMetadataProtocol, Protocol):
     def dynamic_wheel(
         self, field: str, settings: Mapping[str, Any] | None = None
     ) -> bool: ...
 
 
-class DynamicMetadataRequirementsWheelProtocol(
-    DynamicMetadataRequirementsProtocol, DynamicMetadataWheelProtocol, Protocol
-): ...
+@runtime_checkable
+class DynamicMetadataNeeds(DynamicMetadataProtocol, Protocol):
+    def dynamic_metadata_needs(
+        self,
+        field: str,
+        settings: Mapping[str, object] | None = None,
+    ) -> list[str]: ...
 
 
 DMProtocols = Union[
     DynamicMetadataProtocol,
     DynamicMetadataRequirementsProtocol,
     DynamicMetadataWheelProtocol,
-    DynamicMetadataRequirementsWheelProtocol,
+    DynamicMetadataNeeds,
 ]
 
 
@@ -62,14 +73,41 @@ def load_provider(
         sys.path.pop(0)
 
 
-def load_dynamic_metadata(
+def _load_dynamic_metadata(
     metadata: Mapping[str, Mapping[str, str]],
-) -> Generator[tuple[str, DMProtocols | None, dict[str, str]], None, None]:
+) -> Generator[
+    tuple[str, DMProtocols | None, dict[str, str], frozenset[str]], None, None
+]:
     for field, orig_config in metadata.items():
         if "provider" in orig_config:
+            if field not in ALL_FIELDS:
+                msg = f"{field} is not a valid field"
+                raise KeyError(msg)
             config = dict(orig_config)
             provider = config.pop("provider")
             provider_path = config.pop("provider-path", None)
-            yield field, load_provider(provider, provider_path), config
+            loaded_provider = load_provider(provider, provider_path)
+            needs = frozenset(
+                loaded_provider.dynamic_metadata_needs(field, config)
+                if isinstance(loaded_provider, DynamicMetadataNeeds)
+                else []
+            )
+            if needs > ALL_FIELDS:
+                msg = f"Invalid dyanmic_metada_needs: {needs - ALL_FIELDS}"
+                raise KeyError(msg)
+            yield field, loaded_provider, config, needs
         else:
-            yield field, None, dict(orig_config)
+            yield field, None, dict(orig_config), frozenset()
+
+
+def load_dynamic_metadata(
+    metadata: Mapping[str, Mapping[str, str]],
+) -> list[tuple[str, DMProtocols | None, dict[str, str]]]:
+    initial = {f: (p, c, n) for (f, p, c, n) in _load_dynamic_metadata(metadata)}
+
+    dynamic_fields = initial.keys()
+    sorter = TopologicalSorter(
+        {f: n & dynamic_fields for f, (_, _, n) in initial.items()}
+    )
+    order = sorter.static_order()
+    return [(f, *initial[f][:2]) for f in order]

src/dynamic_metadata/plugins/__init__.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import typing
+from collections.abc import Callable
+
+from ..info import DICT_STR_FIELDS, LIST_STR_FIELDS, STR_FIELDS
+
+T = typing.TypeVar("T", bound="str | list[str] | dict[str, str] | dict[str, list[str]]")
+
+
+def _process_dynamic_metadata(field: str, action: Callable[[str], str], result: T) -> T:
+    """
+    Helper function for processing the an action on the various possible metadata fields.
+    """
+
+    if field in STR_FIELDS:
+        if not isinstance(result, str):
+            msg = f"Field {field!r} must be a string"
+            raise RuntimeError(msg)
+        return action(result)  # type: ignore[return-value]
+    if field in LIST_STR_FIELDS:
+        if not (isinstance(result, list) and all(isinstance(r, str) for r in result)):
+            msg = f"Field {field!r} must be a list of strings"
+            raise RuntimeError(msg)
+        return [action(r) for r in result]  # type: ignore[return-value]
+    if field in DICT_STR_FIELDS:
+        if not isinstance(result, dict) or not all(
+            isinstance(v, str) for v in result.values()
+        ):
+            msg = f"Field {field!r} must be a dictionary of strings"
+            raise RuntimeError(msg)
+        return {k: action(v) for k, v in result.items()}  # type: ignore[return-value]
+    if field == "optional-dependencies":
+        if not isinstance(result, dict) or not all(
+            isinstance(v, list) for v in result.values()
+        ):
+            msg = "Field 'optional-dependencies' must be a dictionary of lists"
+            raise RuntimeError(msg)
+        return {k: [action(r) for r in v] for k, v in result.items()}  # type: ignore[return-value]
+
+    msg = f"Unsupported field {field!r} for action"
+    raise RuntimeError(msg)

src/dynamic_metadata/plugins/fancy_pypi_readme.py

@@ -1,10 +1,15 @@
 from __future__ import annotations
 
 from pathlib import Path
+from typing import Any, Mapping
 
 from .._compat import tomllib
 
-__all__ = ["dynamic_metadata", "get_requires_for_dynamic_metadata"]
+__all__ = [
+    "dynamic_metadata",
+    "dynamic_requires_needs",
+    "get_requires_for_dynamic_metadata",
+]
 
 
 def __dir__() -> list[str]:
@@ -13,7 +18,8 @@ def __dir__() -> list[str]:
 
 def dynamic_metadata(
     field: str,
-    settings: dict[str, list[str] | str] | None = None,
+    settings: dict[str, list[str] | str],
+    metadata: Mapping[str, Any],
 ) -> dict[str, str | None]:
     from hatch_fancy_pypi_readme._builder import build_text
     from hatch_fancy_pypi_readme._config import load_and_validate_config
@@ -35,8 +41,9 @@ def dynamic_metadata(
 
     if hasattr(config, "substitutions"):
         try:
-            # We don't have access to the version at this point
-            text = build_text(config.fragments, config.substitutions, "")
+            text = build_text(
+                config.fragments, config.substitutions, metadata["version"]
+            )
         except TypeError:
             # Version 23.2.0 and before don't have a version field
             # pylint: disable-next=no-value-for-parameter
@@ -56,3 +63,10 @@ def get_requires_for_dynamic_metadata(
     _settings: dict[str, object] | None = None,
 ) -> list[str]:
     return ["hatch-fancy-pypi-readme>=22.3"]
+
+
+def dynamic_requires_needs(
+    _field: str,
+    _settings: dict[str, object],
+) -> list[str]:
+    return ["version"]

src/dynamic_metadata/plugins/regex.py

@@ -1,9 +1,14 @@
 from __future__ import annotations
 
+import functools
 import re
-from collections.abc import Mapping
 from pathlib import Path
-from typing import Any
+from typing import TYPE_CHECKING, Any
+
+from . import _process_dynamic_metadata
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
 
 __all__ = ["dynamic_metadata"]
 
@@ -12,28 +17,44 @@ def __dir__() -> list[str]:
     return __all__
 
 
+KEYS = {"input", "regex", "result", "remove"}
+
+
+def _process(match: re.Match[str], remove: str, result: str) -> str:
+    retval = result.format(*match.groups(), **match.groupdict())
+    if remove:
+        retval = re.sub(remove, "", retval)
+    return retval
+
+
 def dynamic_metadata(
     field: str,
     settings: Mapping[str, Any],
+    _metadata: Mapping[str, Any],
 ) -> str:
     # Input validation
-    if field not in {"version", "description", "requires-python"}:
-        msg = "Only string fields supported by this plugin"
-        raise RuntimeError(msg)
-    if settings.keys() > {"input", "regex"}:
-        msg = "Only 'input' and 'regex' settings allowed by this plugin"
+    if settings.keys() > KEYS:
+        msg = f"Only {KEYS} settings allowed by this plugin"
         raise RuntimeError(msg)
     if "input" not in settings:
         msg = "Must contain the 'input' setting to perform a regex on"
         raise RuntimeError(msg)
-    if not all(isinstance(x, str) for x in settings.values()):
-        msg = "Must set 'input' and/or 'regex' to strings"
+    if field != "version" and "regex" not in settings:
+        msg = "Must contain the 'regex' setting if not getting version"
         raise RuntimeError(msg)
+    for key in KEYS:
+        if key in settings and not isinstance(settings[key], str):
+            msg = f"Setting {key!r} must be a string"
+            raise RuntimeError(msg)
 
     input_filename = settings["input"]
     regex = settings.get(
-        "regex", r'(?i)^(__version__|VERSION) *= *([\'"])v?(?P<value>.+?)\2'
+        "regex",
+        r'(?i)^(__version__|VERSION)(?: ?\: ?str)? *= *([\'"])v?(?P<value>.+?)\2',
     )
+    result = settings.get("result", "{value}")
+    assert isinstance(result, str)
+    remove = settings.get("remove", "")
 
     with Path(input_filename).open(encoding="utf-8") as f:
         match = re.search(regex, f.read(), re.MULTILINE)
@@ -42,4 +63,6 @@ def dynamic_metadata(
         msg = f"Couldn't find {regex!r} in {input_filename}"
         raise RuntimeError(msg)
 
-    return match.group("value")
+    return _process_dynamic_metadata(
+        field, functools.partial(_process, match, remove), result
+    )

src/dynamic_metadata/plugins/setuptools_scm.py

@@ -9,7 +9,8 @@ def __dir__() -> list[str]:
 
 def dynamic_metadata(
     field: str,
-    settings: dict[str, object] | None = None,
+    settings: dict[str, object],
+    _metadata: dict[str, object],
 ) -> str:
     # this is a classic implementation, waiting for the release of
     # vcs-versioning and an improved public interface