Add $HFPR_VERSION substitution (#39)

Author: hynek

CHANGELOG.md

@@ -13,6 +13,13 @@ The **third number** is for emergencies when we need to start branches for older
 
 ## [Unreleased](https://github.com/hynek/hatch-fancy-pypi-readme/compare/23.1.0...HEAD)
 
+### Added
+
+- `$HFPR_VERSION` is now replaced by the package version in the PyPI readme.
+  The version is not available in CLI mode, therefore it's replaced by the dummy value of `42.0`.
+  [#39](https://github.com/hynek/hatch-fancy-pypi-readme/pull/39)
+
+
 ## [23.1.0](https://github.com/hynek/hatch-fancy-pypi-readme/compare/22.8.0...23.1.0) - 2023-05-22
 
 ### Added

README.md

@@ -230,6 +230,14 @@ replacement = "[#\\1](https://github.com/hynek/hatch-fancy-pypi-readme/issues/\\
 Again, please check out our [example configuration][example-config] for a complete example.
 
 
+### Referencing Packaging Metadata
+
+If the final contains the string `$HFPR_VERSION`, it is replaced by the current package version.
+
+When running *hatch-fancy-pypi-readme* in CLI mode (as described in the next section), packaging metadata is not available.
+In that case `$HFPR_VERSION` is hardcoded to `42.0` so you can still test your readme.
+
+
 ## CLI Interface
 
 For faster feedback loops, *hatch-fancy-pypi-readme* comes with a CLI interface that takes a `pyproject.toml` file as an argument and renders out the readme that would go into respective package.
@@ -243,7 +251,7 @@ Therefore we recommend running it using [*pipx*](https://pypa.github.io/pipx/):
 
 
 ```shell
-pipx run hatch-fancy-pypi-readme
+$ pipx run hatch-fancy-pypi-readme
 ```
 
 ---

src/hatch_fancy_pypi_readme/_builder.py

@@ -13,11 +13,13 @@
 
 
 def build_text(
-    fragments: list[Fragment], substitutions: list[Substituter]
+    fragments: list[Fragment],
+    substitutions: list[Substituter],
+    version: str,
 ) -> str:
     text = "".join(f.render() for f in fragments)
 
     for sub in substitutions:
         text = sub.substitute(text)
 
-    return text
+    return text.replace("$HFPR_VERSION", version)

src/hatch_fancy_pypi_readme/_cli.py

@@ -65,7 +65,7 @@ def cli_run(
             + "\n".join(f"- {msg}" for msg in e.errors),
         )
 
-    print(build_text(config.fragments, config.substitutions), file=out)
+    print(build_text(config.fragments, config.substitutions, "42.0"), file=out)
 
 
 def _fail(msg: str) -> NoReturn:

src/hatch_fancy_pypi_readme/hooks.py

@@ -20,12 +20,15 @@ def update(self, metadata: dict[str, Any]) -> None:
         """
         Update the project table's metadata.
         """
-
         config = load_and_validate_config(self.config)
 
         metadata["readme"] = {
             "content-type": config.content_type,
-            "text": build_text(config.fragments, config.substitutions),
+            "text": build_text(
+                config.fragments,
+                config.substitutions,
+                version=metadata.get("version", ""),
+            ),
         }
 
 

tests/test_builder.py

@@ -11,8 +11,8 @@ def test_single_text_fragment(self):
         """
         A single text fragment becomes the readme.
         """
-        assert "This is the README!" == build_text(
-            [TextFragment("This is the README!")], []
+        assert "This is the README for 1.0!" == build_text(
+            [TextFragment("This is the README for $HFPR_VERSION!")], [], "1.0"
         )
 
     def test_multiple_text_fragment(self):
@@ -26,4 +26,5 @@ def test_multiple_text_fragment(self):
                 TextFragment("This is the README!"),
             ],
             [],
+            "1.0",
         )