#147: Allow initializing files and persisting substitutions

CHANGELOG.md

@@ -1,3 +1,10 @@
+## Unreleased
+
+* Added:
+  * `tool.poetry-dynamic-versioning.files` config section.
+    This allows you to create a file in a default state before applying substitutions to it.
+    You can also leave the substitutions in place when the plugin deactivates.
+
 ## v1.0.1 (2023-08-21)
 
 * Fixed:

README.md

@@ -248,6 +248,30 @@ In your pyproject.toml file, you may configure the following options:
 
     This will check the default file globs (e.g., `./*.py`)
     as well as the same file globs inside of `src` (e.g., `./src/*.py`).
+* `[tool.poetry-dynamic-versioning.files]` (table, default: empty):
+  This section lets you tweak the behavior for individual files.
+  Each table key is a path to a specific file (no globs) relative to the project root.
+  Each nested table supports these fields:
+
+  * `persistent-substitution` (boolean, optional):
+    If true, then do not revert any substitutions applied to this file.
+    This is primarily useful for editable installs, if you need the version to remain in a file ignored by your VCS.
+  * `initial-content` (string, optional):
+    Set the file content before the substitution phase.
+    The file will be created or overwritten as necessary.
+    Common leading whitespace will be stripped from each line.
+
+  Example:
+
+  ```toml
+  [tool.poetry-dynamic-versioning.files."package/_version.py"]
+  persistent-substitution = true
+  initial-content = """
+    # These version placeholders will be replaced later during substitution.
+    __version__ = "0.0.0"
+    __version_tuple__ = (0, 0, 0)
+  """
+  ```
 
 Simple example:
 

poetry_dynamic_versioning/__init__.py

@@ -7,6 +7,7 @@
 import shlex
 import subprocess
 import sys
+import textwrap
 from importlib import import_module
 from pathlib import Path
 from typing import Mapping, MutableMapping, Optional, Sequence, Tuple, Union
@@ -103,6 +104,7 @@ def _default_config() -> Mapping:
                     ],
                     "folders": [],
                 },
+                "files": {},
                 "style": None,
                 "metadata": None,
                 "format": None,
@@ -192,6 +194,9 @@ def _validate_config(config: Optional[Mapping] = None) -> Sequence[str]:
 def _validate_config_section(
     config: Mapping, default: Mapping, path: Sequence[str]
 ) -> Sequence[str]:
+    if not default:
+        return []
+
     errors = []
 
     for (key, value) in config.items():
@@ -426,6 +431,14 @@ def _apply_version(
 
     name = pyproject["tool"]["poetry"]["name"]  # type: ignore
 
+    for file_name, file_info in config["files"].items():
+        full_file = pyproject_path.parent.joinpath(file_name)
+        if "initial-content" in file_info:
+            if not full_file.parent.exists():
+                full_file.parent.mkdir()
+            initial = textwrap.dedent(file_info["initial-content"])
+            full_file.write_bytes(initial.encode("utf-8"))
+
     _substitute_version(
         name,  # type: ignore
         version,
@@ -493,7 +506,17 @@ def _revert_version(retain: bool = False) -> None:
         state.path.write_bytes(tomlkit.dumps(pyproject).encode("utf-8"))
 
         if state.substitutions:
+            config = _get_config(pyproject)
+
+            persistent = []
+            for file, file_info in config["files"].items():
+                if file_info.get("persistent-substitution"):
+                    persistent.append(state.path.parent.joinpath(file))
+
             for file, content in state.substitutions.items():
+                if file in persistent:
+                    continue
+
                 file.write_bytes(content.encode("utf-8"))
 
     _state.projects.clear()