Add a format module

Have a central location to view and evaluate all format variables used in the evaluation of the `pyproject.toml`

Signed-off-by: Cristian Le <[email protected]>

Author: LecrisUT

docs/api/scikit_build_core.rst

@@ -41,6 +41,14 @@ scikit\_build\_core.errors module
    :show-inheritance:
    :undoc-members:
 
+scikit\_build\_core.format module
+---------------------------------
+
+.. automodule:: scikit_build_core.format
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
 scikit\_build\_core.program\_search module
 ------------------------------------------
 

pyproject.toml

@@ -290,9 +290,6 @@ known-local-folder = ["pathutils"]
 "typing.Self".msg = "Use scikit_build_core._compat.typing.Self instead."
 "typing_extensions.Self".msg = "Use scikit_build_core._compat.typing.Self instead."
 "typing.Final".msg = "Add scikit_build_core._compat.typing.Final instead."
-"typing.NotRequired".msg = "Add scikit_build_core._compat.typing.NotRequired instead."
-"typing.OrderedDict".msg = "Add scikit_build_core._compat.typing.OrderedDict instead."
-"typing.TypedDict".msg = "Add scikit_build_core._compat.typing.TypedDict instead."
 "typing.assert_never".msg = "Add scikit_build_core._compat.typing.assert_never instead."
 "tomli".msg = "Use scikit_build_core._compat.tomllib instead."
 "tomllib".msg = "Use scikit_build_core._compat.tomllib instead."

src/scikit_build_core/format.py

@@ -0,0 +1,37 @@
+"""Format variables available in the ``pyproject.toml`` evaluation"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, TypedDict
+
+if TYPE_CHECKING:
+    from scikit_build_core.settings.skbuild_model import ScikitBuildSettings
+
+__all__ = [
+    "PyprojectFormatter",
+    "pyproject_format",
+]
+
+
+def __dir__() -> list[str]:
+    return __all__
+
+
+class PyprojectFormatter(TypedDict, total=False):
+    """Format helper for pyproject.toml.
+
+    Stores all known variables that can be used for evaluating a formatted string
+    in the pyproject.toml config file.
+    """
+
+
+def pyproject_format(
+    *,
+    settings: ScikitBuildSettings | None = None,  # noqa: ARG001
+    dummy: bool = False,
+) -> PyprojectFormatter | dict[str, str]:
+    """Generate :py:class:`PyprojectFormatter` dictionary to use in f-string format."""
+    if dummy:
+        # Return a dict with all the known keys but with values replaced with dummy values
+        return {key: "*" for key in PyprojectFormatter.__annotations__}
+    return PyprojectFormatter()