python-semantic-release 9.19.0__py3-none-any.whl → 9.20.0__py3-none-any.whl

{python_semantic_release-9.19.0.dist-info → python_semantic_release-9.20.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-semantic-release
-Version: 9.19.0
+Version: 9.20.0
 Summary: Automatic Semantic Versioning for Python projects
 Author-email: Rolf Erik Lekang <me@rolflekang.com>
 License: MIT
@@ -33,6 +33,7 @@ Requires-Dist: importlib-resources~=6.0
 Requires-Dist: pydantic~=2.0
 Requires-Dist: rich~=13.0
 Requires-Dist: shellingham~=1.5
+Requires-Dist: Deprecated~=1.2
 Provides-Extra: build
 Requires-Dist: build~=1.2; extra == "build"
 Provides-Extra: dev
@@ -45,7 +46,8 @@ Requires-Dist: sphinxcontrib-apidoc==0.5.0; extra == "docs"
 Requires-Dist: sphinx-autobuild==2024.2.4; extra == "docs"
 Requires-Dist: furo~=2024.1; extra == "docs"
 Provides-Extra: mypy
-Requires-Dist: mypy==1.14.1; extra == "mypy"
+Requires-Dist: mypy==1.15.0; extra == "mypy"
+Requires-Dist: types-Deprecated~=1.2; extra == "mypy"
 Requires-Dist: types-requests~=2.32.0; extra == "mypy"
 Requires-Dist: types-pyyaml~=6.0; extra == "mypy"
 Provides-Extra: test

{python_semantic_release-9.19.0.dist-info → python_semantic_release-9.20.0.dist-info}/RECORD

@@ -1,11 +1,11 @@
-semantic_release/__init__.py,sha256=GB2rbgAWEPV8Ke_LT5SweTJGMfuCbPkhjXovRKWl0AQ,1229
-semantic_release/__main__.py,sha256=KOIBOvLruqfi5ArXcWK3ucIZ7NB55kfCbycJaxx6aQg,1485
+semantic_release/__init__.py,sha256=3oeARQKsIRDyheNZV8Tz48-9tVR4TZcIbaK1QTt1V1U,1229
+semantic_release/__main__.py,sha256=pksxr6g1vkKq98Q1lShsxG8tk55IMiSMHzAHKyFU5x0,1704
 semantic_release/const.py,sha256=wInJR7vcOgT1ysm5VuJQ6lD_ZGYnCwRVKz7Uz3htQc4,861
 semantic_release/enums.py,sha256=vrEw1UNRcNrFjPqOFnuUzfeoqKj0ChixVVlyk5fqbng,1744
 semantic_release/errors.py,sha256=PY9rmviSFBZkqawW6VXbUfmF9C_RNOIObcmeGxLefMo,2904
 semantic_release/gitproject.py,sha256=G4XrucN-ZwT1Kj4RMrABcr1vWb0bjKgurEeJjcL-61c,9422
-semantic_release/globals.py,sha256=imI9WKGa6MS2pTRAZiWZ2qIJup2eWnBz3OZmIj2YIHM,158
-semantic_release/helpers.py,sha256=8yQTYUS3InvEnEqqhzJPM_R-69Pk6k9gF1NgPlgQx1Q,9774
+semantic_release/globals.py,sha256=TV0c_Ir1eZIahPvLOBdm_SeE8IRL5X3h5ZiVwPjDHNM,256
+semantic_release/helpers.py,sha256=H-23ZRg_zq2-eXGQJnCPwzAh6txmhCUBogxFIR6Qssc,9979
 semantic_release/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 semantic_release/changelog/__init__.py,sha256=Bg6Xe5Vt32rWoMscW-hd4sUwiZqzWmsg4CD1EhMesMY,262
 semantic_release/changelog/context.py,sha256=WeLQ2BvYEWunIF8XEl6ldQE4IRg0d7r8mYSBi-TqK7o,5988
@@ -14,17 +14,17 @@ semantic_release/changelog/template.py,sha256=R3V5m-7kv9ES23e_g37fe17tk-ESgvwV0C
 semantic_release/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 semantic_release/cli/changelog_writer.py,sha256=92DntVFFGdzFc5eBUgrRXbSOSV9KVvV769NyhLOTirg,9281
 semantic_release/cli/cli_context.py,sha256=Nop71LdVCJOeSUHgTXunMyK3xAu_QKQC2cRp1QBVkX0,4134
-semantic_release/cli/config.py,sha256=S57MXS2feHW6p9xWOl7waMKyivFoAfH6RLmsh0b2msk,33830
+semantic_release/cli/config.py,sha256=-8xKYBwlMINnWQz9e7ppRtS_-GwUGHxfqelAf4k0FQ8,33516
 semantic_release/cli/const.py,sha256=h7XE2D0D__TAZSrUUtVszwvzpkHTMOiQCf97XQNbEvA,163
 semantic_release/cli/github_actions_output.py,sha256=6oNwjnQBg9XF5QgGc4TgbwX_-W0aj65VwGSL4ALvqVg,2296
 semantic_release/cli/masking_filter.py,sha256=ric34rnXfN5RiAVVaKnhiMJOxTnEl26kI06jQqZPZoQ,3072
-semantic_release/cli/util.py,sha256=FyXaBkeL7nXKjy3X9rQLEwvn7p46xPekp2V8Z-5MVrk,3755
+semantic_release/cli/util.py,sha256=kkn_bJmlbC5hR4GjV1l4uBpL1SfluSkb9WkDUTg9G0o,3720
 semantic_release/cli/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 semantic_release/cli/commands/changelog.py,sha256=i3j6jhcfhFo3d7Bgrp1tD01vJkuTZvtaWX7bPteLQbA,5345
 semantic_release/cli/commands/generate_config.py,sha256=2xZOu3NpyhBp0pWr7d8ugKl_kjqQgpSsSMHq5wHTfrE,1699
-semantic_release/cli/commands/main.py,sha256=237rn_Od4LOWfjUjiUKI_jSV820MfcCtRpwPjxjLbyU,4312
+semantic_release/cli/commands/main.py,sha256=P0YlSPLNXxB6CRQFQStslw1fCrURvN5skUd7-Ij5VKw,4271
 semantic_release/cli/commands/publish.py,sha256=y_LalPti_kZeQJzl2CR2pTZUK8DCMvNSTe4NaMC5TJA,2875
-semantic_release/cli/commands/version.py,sha256=BMAOXToqOC_U0nh3d-QszAOS7xhN86aGhFiaePSdfws,25287
+semantic_release/cli/commands/version.py,sha256=zwxZoi76vP3oWUXiQ86V1rb6meCRe5gouwFGJ-4dD58,25578
 semantic_release/commit_parser/__init__.py,sha256=6euiDgj9bwOx1rP96vUjq090usviXkbo7OVOnRBGfcw,742
 semantic_release/commit_parser/_base.py,sha256=oDifeTmFDpS238cp_DDrGzfidaKeAD5olCB5IM4Q6z8,3058
 semantic_release/commit_parser/angular.py,sha256=UM88ethWT34__kDgsBXXb26d0V8FN1ZFjcU7psuOhgY,19259
@@ -34,12 +34,12 @@ semantic_release/commit_parser/scipy.py,sha256=0rYZglJ7uib-1Deu4J30wHh7AZS8KfO0e
 semantic_release/commit_parser/tag.py,sha256=oGB3lgyp2Eu3Tg3jjxqNzN86N6bokSaFu6f4Ir6IS_k,3546
 semantic_release/commit_parser/token.py,sha256=ECgi7eeSgk3Biq1Y_ChbFJZQLkrUpNvGhIaEOXrNC4M,7904
 semantic_release/commit_parser/util.py,sha256=_ACiopznjwINn4t1zPHl8bxZEc0zOAURTycNU-sXs3M,3959
-semantic_release/data/templates/angular/md/.release_notes.md.j2,sha256=3d4ihVVY1u2rAm7XgydRKQq92YfQkFWanpEP5uQ8xmM,2512
+semantic_release/data/templates/angular/md/.release_notes.md.j2,sha256=DlMVAJMGqE27TwJ-2kviYaFhd3uWqXiU6Ikl15Ukne8,2512
 semantic_release/data/templates/angular/md/CHANGELOG.md.j2,sha256=FZmrQ-qOIoSoJmAa_NFaRelfmqUpypU2xlDeScdGOf4,729
 semantic_release/data/templates/angular/md/.components/changelog_header.md.j2,sha256=qNxTuSr59CV_yyimVU_RYp5azCnK0l6nJ03Zf0u5Ugg,166
 semantic_release/data/templates/angular/md/.components/changelog_init.md.j2,sha256=MyEQdWUemGXKWDhvpTmubZdozd3iaLECZAI1VRlE7mg,862
 semantic_release/data/templates/angular/md/.components/changelog_update.md.j2,sha256=uVF4wbbjTMvl6Kbsq9xy3YIrj-uhBnHylEfA7S76aHI,2606
-semantic_release/data/templates/angular/md/.components/changes.md.j2,sha256=NIdXNNao4Oq9nWHaq6X4ZbGMMJ2H-7yxqAP5HmBmSV8,5965
+semantic_release/data/templates/angular/md/.components/changes.md.j2,sha256=hGBKJhZwnyNRPpSeNA9k3n46_gCn9fvKPRKfzg-bfXw,5965
 semantic_release/data/templates/angular/md/.components/first_release.md.j2,sha256=-S2aJV3ka4YicLs8UF6BEV-CDnL8iXLcNRRIiENFrYE,421
 semantic_release/data/templates/angular/md/.components/macros.md.j2,sha256=RzBVwKSCb-WmRIMFVQL9U157mAih-PzZ_iRcfyWkG20,8196
 semantic_release/data/templates/angular/md/.components/unreleased_changes.md.j2,sha256=HRLj6cyRfPZXC0s-0Av6s0Gp3jKxWg9AIEtIXBVqJuY,177
@@ -48,7 +48,7 @@ semantic_release/data/templates/angular/rst/CHANGELOG.rst.j2,sha256=VmkXEMHiPBdZ
 semantic_release/data/templates/angular/rst/.components/changelog_header.rst.j2,sha256=c9xN1SEYLFwMvPYXYKt-ZbYPn2-Ss0V7zepEtFFj3Os,200
 semantic_release/data/templates/angular/rst/.components/changelog_init.rst.j2,sha256=XD0l3eTyz1yydLKsmSqBk-u8RnO-RdQ2Q8uWezHMAWw,866
 semantic_release/data/templates/angular/rst/.components/changelog_update.rst.j2,sha256=x23-qk9owJrOQaHx8SgSnIZECITjPf1R2awfv9EOHN0,2604
-semantic_release/data/templates/angular/rst/.components/changes.rst.j2,sha256=IZdUJ5tt-8P5AyPgS1hsTuu2vg10GDINJ9wLJ4CpP68,7352
+semantic_release/data/templates/angular/rst/.components/changes.rst.j2,sha256=XIJQOzH7vzPOZszMaAJBa5O4m-syfwraBLpHnX3QmU4,7352
 semantic_release/data/templates/angular/rst/.components/first_release.rst.j2,sha256=huaO-B3BRs7h2LRks2a6-656W2qzURkzLiyuKvYxMTg,462
 semantic_release/data/templates/angular/rst/.components/macros.rst.j2,sha256=WLNUD2H2V-5vrwT7TKelwQ2wclLcZxFs0E2Lk3Ld10U,9096
 semantic_release/data/templates/angular/rst/.components/unreleased_changes.rst.j2,sha256=ARBhc1ZpKwehGKDvOMqukmN59mTJiHzHsS7rOfKYCt8,202
@@ -64,13 +64,18 @@ semantic_release/hvcs/token_auth.py,sha256=ZjT56-NIPB4OKIt1qwHCu1TavXnrWFIBl9ARl
 semantic_release/hvcs/util.py,sha256=guxisysY_IW5tv7aaV-iVPEVJzgbOs375kiRRpSquTI,2879
 semantic_release/version/__init__.py,sha256=CLhtGQry9dLIij5XyRa9ZevxU_1p8tjMTSQ-K_GMpWM,270
 semantic_release/version/algorithm.py,sha256=s5lso4Py-PiVzuPhgeJOz6IDzIdqc6EeoUirmBZ8IXY,16696
-semantic_release/version/declaration.py,sha256=f6Ld7hIhrqvDrRBapJHr-KDimuyo-4IG8009Zu9BIgU,7357
+semantic_release/version/declaration.py,sha256=aDpgfh0G-35TLXU6x4y3V0nFr8WBR4bw1GDldf0v8_Q,3638
 semantic_release/version/translator.py,sha256=P1noIsVBn8u6zNOFjG0xKYOWapxqf_PHSMvMeLJ9kXg,3050
 semantic_release/version/version.py,sha256=6PCtSbLP88U1daoxnCwHc--YguZo4waGNLqJ5JfeczE,14175
-python_semantic_release-9.19.0.dist-info/AUTHORS.rst,sha256=XOReVvpymEFUPsS2QPH97jlfJBVrxwS2eu8-jVAe4gk,230
-python_semantic_release-9.19.0.dist-info/LICENSE,sha256=NE85nszX252sdQdu0xgS9qwfYES0k8qS6gW3uO4jRGE,1083
-python_semantic_release-9.19.0.dist-info/METADATA,sha256=fpNQ4-lx5yz8INyq7I4wZr0m6hTN76h9kctnkHWAiRc,3812
-python_semantic_release-9.19.0.dist-info/WHEEL,sha256=P9jw-gEje8ByB7_hXoICnHtVCrEwMQh-630tKvQWehc,91
-python_semantic_release-9.19.0.dist-info/entry_points.txt,sha256=r2Jql3GTQyugQnvf34l2eXk1O_Qx6llR_xixG1ZWgD0,105
-python_semantic_release-9.19.0.dist-info/top_level.txt,sha256=qYA24nyg3eP-ti5UW7Vuj2aXVmM0wqVHx4mREdRZNAA,17
-python_semantic_release-9.19.0.dist-info/RECORD,,
+semantic_release/version/declarations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+semantic_release/version/declarations/enum.py,sha256=3n5Py9DoFkmItIdsmtQrJgmAhepTv_1EnogzSdXu1Wg,244
+semantic_release/version/declarations/i_version_replacer.py,sha256=oP6BxJuxwI44roI6448tomShv1sMoy9ry8TlhhIQtfc,2416
+semantic_release/version/declarations/pattern.py,sha256=Hv2TBdWdS6d00FYOs-Ja_tfafzEw3OS4Wn5atS1z9Z0,8295
+semantic_release/version/declarations/toml.py,sha256=IKAwG2iu5OWUOytCW0CqKgskU4VifsnD7I6Dkm2EKjo,4945
+python_semantic_release-9.20.0.dist-info/AUTHORS.rst,sha256=XOReVvpymEFUPsS2QPH97jlfJBVrxwS2eu8-jVAe4gk,230
+python_semantic_release-9.20.0.dist-info/LICENSE,sha256=NE85nszX252sdQdu0xgS9qwfYES0k8qS6gW3uO4jRGE,1083
+python_semantic_release-9.20.0.dist-info/METADATA,sha256=hTj0AawcG8vb-Wo-b6NuLtDVA8RcwQzeb3ULXHL3dho,3897
+python_semantic_release-9.20.0.dist-info/WHEEL,sha256=P9jw-gEje8ByB7_hXoICnHtVCrEwMQh-630tKvQWehc,91
+python_semantic_release-9.20.0.dist-info/entry_points.txt,sha256=r2Jql3GTQyugQnvf34l2eXk1O_Qx6llR_xixG1ZWgD0,105
+python_semantic_release-9.20.0.dist-info/top_level.txt,sha256=qYA24nyg3eP-ti5UW7Vuj2aXVmM0wqVHx4mREdRZNAA,17
+python_semantic_release-9.20.0.dist-info/RECORD,,

semantic_release/__init__.py

@@ -24,7 +24,7 @@ from semantic_release.version import (
     tags_and_versions,
 )
 
-__version__ = "9.19.0"
+__version__ = "9.20.0"
 
 __all__ = [
     "CommitParser",

semantic_release/__main__.py

@@ -8,6 +8,7 @@ from traceback import format_exception
 
 from semantic_release import globals
 from semantic_release.cli.commands.main import main as cli_main
+from semantic_release.enums import SemanticReleaseLogLevels
 
 
 def main() -> None:
@@ -18,7 +19,7 @@ def main() -> None:
         print("\n-- User Abort! --", file=sys.stderr)
         sys.exit(127)
     except Exception as err:  # noqa: BLE001, graceful error handling across application
-        if globals.debug:
+        if globals.log_level <= SemanticReleaseLogLevels.DEBUG:
             print(f"{err.__class__.__name__}: {err}\n", file=sys.stderr)
             etype, value, traceback = sys.exc_info()
             print(
@@ -35,9 +36,12 @@ def main() -> None:
                 file=sys.stderr,
             )
 
-        print(f"::ERROR:: {err}", file=sys.stderr)
+        print(
+            str.join("\n", [f"::ERROR:: {line}" for line in str(err).splitlines()]),
+            file=sys.stderr,
+        )
 
-        if not globals.debug:
+        if globals.log_level > SemanticReleaseLogLevels.DEBUG:
             print(
                 "Run semantic-release in very verbose mode (-vv) to see the full traceback.",
                 file=sys.stderr,

semantic_release/cli/commands/main.py

@@ -116,10 +116,10 @@ def main(
         SemanticReleaseLogLevels.SILLY,
     ]
 
-    log_level = log_levels[verbosity]
+    globals.log_level = log_levels[verbosity]
 
     logging.basicConfig(
-        level=log_level,
+        level=globals.log_level,
         format=FORMAT,
         datefmt="[%X]",
         handlers=[
@@ -130,10 +130,7 @@ def main(
     )
 
     logger = logging.getLogger(__name__)
-    logger.debug("logging level set to: %s", logging.getLevelName(log_level))
-
-    if log_level <= logging.DEBUG:
-        globals.debug = True
+    logger.debug("logging level set to: %s", logging.getLevelName(globals.log_level))
 
     if noop:
         rprint(

semantic_release/cli/commands/version.py

@@ -39,12 +39,12 @@ from semantic_release.version.translator import VersionTranslator
 
 if TYPE_CHECKING:  # pragma: no cover
     from pathlib import Path
-    from typing import Iterable, Mapping
+    from typing import Mapping, Sequence
 
     from git.refs.tag import Tag
 
     from semantic_release.cli.cli_context import CliContextObj
-    from semantic_release.version.declaration import VersionDeclarationABC
+    from semantic_release.version.declaration import IVersionReplacer
     from semantic_release.version.version import Version
 
 
@@ -135,28 +135,43 @@ def version_from_forced_level(
 
 def apply_version_to_source_files(
     repo_dir: Path,
-    version_declarations: Iterable[VersionDeclarationABC],
+    version_declarations: Sequence[IVersionReplacer],
     version: Version,
     noop: bool = False,
 ) -> list[str]:
-    paths = [
-        str(declaration.path.resolve().relative_to(repo_dir))
-        for declaration in version_declarations
+    if len(version_declarations) < 1:
+        return []
+
+    if not noop:
+        log.debug("Updating version %s in repository files...", version)
+
+    paths = list(
+        map(
+            lambda decl, new_version=version, noop=noop: (  # type: ignore[misc]
+                decl.update_file_w_version(new_version=new_version, noop=noop)
+            ),
+            version_declarations,
+        )
+    )
+
+    repo_filepaths = [
+        str(updated_file.relative_to(repo_dir))
+        for updated_file in paths
+        if updated_file is not None
     ]
 
     if noop:
         noop_report(
-            "would have updated versions in the following paths:"
-            + "".join(f"\n    {path}" for path in paths)
+            str.join(
+                "",
+                [
+                    "would have updated versions in the following paths:",
+                    *[f"\n    {filepath}" for filepath in repo_filepaths],
+                ],
+            )
         )
-        return paths
-
-    log.debug("writing version %s to source paths %s", version, paths)
-    for declaration in version_declarations:
-        new_content = declaration.replace(new_version=version)
-        declaration.path.write_text(new_content)
 
-    return paths
+    return repo_filepaths
 
 
 def shell(

semantic_release/cli/config.py

@@ -46,7 +46,7 @@ from semantic_release.commit_parser import (
     ScipyCommitParser,
     TagCommitParser,
 )
-from semantic_release.const import COMMIT_MESSAGE, DEFAULT_COMMIT_AUTHOR, SEMVER_REGEX
+from semantic_release.const import COMMIT_MESSAGE, DEFAULT_COMMIT_AUTHOR
 from semantic_release.errors import (
     DetachedHeadGitError,
     InvalidConfiguration,
@@ -55,11 +55,9 @@ from semantic_release.errors import (
     ParserLoadError,
 )
 from semantic_release.helpers import dynamic_import
-from semantic_release.version.declaration import (
-    PatternVersionDeclaration,
-    TomlVersionDeclaration,
-    VersionDeclarationABC,
-)
+from semantic_release.version.declarations.i_version_replacer import IVersionReplacer
+from semantic_release.version.declarations.pattern import PatternVersionDeclaration
+from semantic_release.version.declarations.toml import TomlVersionDeclaration
 from semantic_release.version.translator import VersionTranslator
 
 log = logging.getLogger(__name__)
@@ -555,7 +553,7 @@ class RuntimeContext:
     commit_author: Actor
     commit_message: str
     changelog_excluded_commit_patterns: Tuple[Pattern[str], ...]
-    version_declarations: Tuple[VersionDeclarationABC, ...]
+    version_declarations: Tuple[IVersionReplacer, ...]
     hvcs_client: hvcs.HvcsBase
     changelog_insertion_flag: str
     changelog_mask_initial_release: bool
@@ -665,6 +663,17 @@ class RuntimeContext:
                 if raw.commit_parser in _known_commit_parsers
                 else dynamic_import(raw.commit_parser)
             )
+        except ValueError as err:
+            raise ParserLoadError(
+                str.join(
+                    "\n",
+                    [
+                        f"Unrecognized commit parser value: {raw.commit_parser!r}.",
+                        str(err),
+                        "Unable to load the given parser! Check your configuration!",
+                    ],
+                )
+            ) from err
         except ModuleNotFoundError as err:
             raise ParserLoadError(
                 str.join(
@@ -727,44 +736,41 @@ class RuntimeContext:
 
         commit_author = Actor(*_commit_author_valid.groups())
 
-        version_declarations: list[VersionDeclarationABC] = []
-        for decl in () if raw.version_toml is None else raw.version_toml:
-            try:
-                path, search_text = decl.split(":", maxsplit=1)
-                # VersionDeclarationABC handles path existence check
-                vd = TomlVersionDeclaration(path, search_text)
-            except ValueError as exc:
-                log.exception("Invalid TOML declaration %r", decl)
-                raise InvalidConfiguration(
-                    f"Invalid TOML declaration {decl!r}"
-                ) from exc
-
-            version_declarations.append(vd)
-
-        for decl in () if raw.version_variables is None else raw.version_variables:
-            try:
-                path, variable = decl.split(":", maxsplit=1)
-                # VersionDeclarationABC handles path existence check
-                search_text = str.join(
-                    "",
+        version_declarations: list[IVersionReplacer] = []
+
+        try:
+            version_declarations.extend(
+                TomlVersionDeclaration.from_string_definition(definition)
+                for definition in iter(raw.version_toml or ())
+            )
+        except ValueError as err:
+            raise InvalidConfiguration(
+                str.join(
+                    "\n",
                     [
-                        # Supports optional matching quotations around variable name
-                        # Negative lookbehind to ensure we don't match part of a variable name
-                        f"""(?x)(?P<quote1>['"])?(?<![\\w.-]){variable}(?P=quote1)?""",
-                        # Supports walrus, equals sign, or colon as assignment operator ignoring whitespace separation
-                        r"\s*(:=|[:=])\s*",
-                        # Supports optional matching quotations around version number of a SEMVER pattern
-                        f"""(?P<quote2>['"])?(?P<version>{SEMVER_REGEX.pattern})(?P=quote2)?""",
+                        "Invalid 'version_toml' configuration",
+                        str(err),
                     ],
                 )
-                pd = PatternVersionDeclaration(path, search_text)
-            except ValueError as exc:
-                log.exception("Invalid variable declaration %r", decl)
-                raise InvalidConfiguration(
-                    f"Invalid variable declaration {decl!r}"
-                ) from exc
-
-            version_declarations.append(pd)
+            ) from err
+
+        try:
+            version_declarations.extend(
+                PatternVersionDeclaration.from_string_definition(
+                    definition, raw.tag_format
+                )
+                for definition in iter(raw.version_variables or ())
+            )
+        except ValueError as err:
+            raise InvalidConfiguration(
+                str.join(
+                    "\n",
+                    [
+                        "Invalid 'version_variables' configuration",
+                        str(err),
+                    ],
+                )
+            ) from err
 
         # Provide warnings if the token is missing
         if not raw.remote.token:

semantic_release/cli/util.py

@@ -28,7 +28,7 @@ def noop_report(msg: str) -> None:
     Rich-prints a msg with a standard prefix to report when an action is not being
     taken due to a "noop" flag
     """
-    fullmsg = "[bold cyan]:shield: semantic-release 'noop' mode is enabled! " + msg
+    fullmsg = "[bold cyan][:shield: NOP] " + msg
     rprint(fullmsg)
 
 

semantic_release/data/templates/angular/md/.components/changes.md.j2

@@ -18,7 +18,7 @@ EXAMPLE:
 - Fix bug ([#11](https://domain.com/namespace/repo/pull/11),
   [`abcdef1`](https://domain.com/namespace/repo/commit/HASH))
 
-### BREAKING CHANGES
+### Breaking Changes
 
 - With the change _____, the change causes ___ effect. Ultimately, this section
   it is a more detailed description of the breaking change. With an optional
@@ -27,7 +27,7 @@ EXAMPLE:
 - **scope**: this breaking change has a scope to identify the part of the code that
   this breaking change applies to for better context.
 
-### ADDITIONAL RELEASE INFORMATION
+### Additional Release Information
 
 - This is a release note that provides additional information about the release
   that is not a breaking change or a feature/bug fix.
@@ -96,7 +96,7 @@ EXAMPLE:
 %}{#
    #    # PRINT BREAKING CHANGE DESCRIPTIONS (header & descriptions)
 #}{{    "\n"
-}}{{    "### BREAKING CHANGES\n"
+}}{{    "### Breaking Changes\n"
 }}{{
         "\n%s\n" | format(brking_descriptions | unique | join("\n\n"))
 }}{#
@@ -129,7 +129,7 @@ EXAMPLE:
 %}{#
    #    # PRINT RELEASE NOTICE INFORMATION (header & descriptions)
 #}{{    "\n"
-}}{{    "### ADDITIONAL RELEASE INFORMATION\n"
+}}{{    "### Additional Release Information\n"
 }}{{
         "\n%s\n" | format(release_notices | unique | join("\n\n"))
 }}{#

semantic_release/data/templates/angular/md/.release_notes.md.j2

@@ -14,13 +14,13 @@ _This release is published under the MIT License._
 
 - Fix bug (#11, [`abcdef1`](https://domain.com/namespace/repo/commit/HASH))
 
-### BREAKING CHANGES
+### Breaking Changes
 
 - With the change _____, the change causes ___ effect. Ultimately, this section it is a more detailed description of the breaking change. With an optional scope prefix like the commit messages above.
 
 - **scope**: this breaking change has a scope to identify the part of the code that this breaking change applies to for better context.
 
-### ADDITIONAL RELEASE INFORMATION
+### Additional Release Information
 
 - This is a release note that provides additional information about the release that is not a breaking change or a feature/bug fix.
 

semantic_release/data/templates/angular/rst/.components/changes.rst.j2

@@ -18,7 +18,7 @@ Bug Fixes
 
 * Fix bug (`#11`_, `8a7b8ec`_)
 
-BREAKING CHANGES
+Breaking Changes
 ----------------
 
 * With the change _____, the change causes ___ effect. Ultimately, this section
@@ -28,7 +28,7 @@ BREAKING CHANGES
 * **scope**: this breaking change has a scope to identify the part of the code that
   this breaking change applies to for better context.
 
-ADDITIONAL RELEASE INFORMATION
+Additional Release Information
 ------------------------------
 
 * This is a release note that provides additional information about the release
@@ -124,7 +124,7 @@ ADDITIONAL RELEASE INFORMATION
 %}{#
    #    # PRINT BREAKING CHANGE DESCRIPTIONS (header & descriptions)
 #}{{    "\n"
-}}{{    "BREAKING CHANGES\n"
+}}{{    "Breaking Changes\n"
 }}{{    '----------------\n'
 }}{{
         "\n%s\n" | format(brking_descriptions | unique | join("\n\n"))
@@ -158,7 +158,7 @@ ADDITIONAL RELEASE INFORMATION
 %}{#
    #    # PRINT RELEASE NOTICE INFORMATION (header & descriptions)
 #}{{    "\n"
-}}{{    "ADDITIONAL RELEASE INFORMATION\n"
+}}{{    "Additional Release Information\n"
 }}{{    "------------------------------\n"
 }}{{
         "\n%s\n" | format(release_notices | unique | join("\n\n"))

semantic_release/globals.py

@@ -2,5 +2,7 @@
 
 from __future__ import annotations
 
-debug: bool = False
-"""bool: Enable debug level logging and runtime actions."""
+from semantic_release.enums import SemanticReleaseLogLevels
+
+log_level: SemanticReleaseLogLevels = SemanticReleaseLogLevels.WARNING
+"""int: Logging level for semantic-release"""

semantic_release/helpers.py

@@ -157,6 +157,12 @@ def dynamic_import(import_path: str) -> Any:
     Dynamically import an object from a conventionally formatted "module:attribute"
     string
     """
+    if ":" not in import_path:
+        raise ValueError(
+            f"Invalid import path {import_path!r}, must use 'module:Class' format"
+        )
+
+    # Split the import path into module and attribute
     module_name, attr = import_path.split(":", maxsplit=1)
 
     # Check if the module is a file path, if it can be resolved and exists on disk then import as a file

semantic_release/version/declaration.py

@@ -1,19 +1,43 @@
 from __future__ import annotations
 
-import logging
-import re
+# TODO: Remove v10
 from abc import ABC, abstractmethod
+from logging import getLogger
 from pathlib import Path
-from typing import Any, Dict, cast
-
-import tomlkit
-from dotty_dict import Dotty  # type: ignore[import]
-
-from semantic_release.version.version import Version
-
-log = logging.getLogger(__name__)
-
-
+from typing import TYPE_CHECKING
+
+from deprecated.sphinx import deprecated
+
+from semantic_release.version.declarations.enum import VersionStampType
+from semantic_release.version.declarations.i_version_replacer import IVersionReplacer
+from semantic_release.version.declarations.pattern import PatternVersionDeclaration
+from semantic_release.version.declarations.toml import TomlVersionDeclaration
+
+if TYPE_CHECKING:  # pragma: no cover
+    from semantic_release.version.version import Version
+
+
+# Globals
+__all__ = [
+    "IVersionReplacer",
+    "VersionStampType",
+    "PatternVersionDeclaration",
+    "TomlVersionDeclaration",
+    "VersionDeclarationABC",
+]
+log = getLogger(__name__)
+
+
+@deprecated(
+    version="9.20.0",
+    reason=str.join(
+        " ",
+        [
+            "Refactored to composition paradigm using the new IVersionReplacer interface.",
+            "This class will be removed in a future release",
+        ],
+    ),
+)
 class VersionDeclarationABC(ABC):
     """
     ABC for classes representing a location in which a version is declared somewhere
@@ -40,13 +64,8 @@ class VersionDeclarationABC(ABC):
             self._content = self.path.read_text()
         return self._content
 
-    # mypy doesn't like properties?
-    @content.setter  # type: ignore[attr-defined]
-    def _(self, _: Any) -> None:
-        raise AttributeError("'content' cannot be set directly")
-
-    @content.deleter  # type: ignore[attr-defined]
-    def _(self) -> None:
+    @content.deleter
+    def content(self) -> None:
         log.debug("resetting instance-stored source file contents")
         self._content = None
 
@@ -86,116 +105,3 @@ class VersionDeclarationABC(ABC):
         log.debug("writing content to %r", self.path.resolve())
         self.path.write_text(content)
         self._content = None
-
-
-class TomlVersionDeclaration(VersionDeclarationABC):
-    """VersionDeclarationABC implementation which manages toml-format source files."""
-
-    def _load(self) -> Dotty:
-        """Load the content of the source file into a Dotty for easier searching"""
-        loaded = tomlkit.loads(self.content)
-        return Dotty(loaded)
-
-    def parse(self) -> set[Version]:
-        """Look for the version in the source content"""
-        content = self._load()
-        maybe_version: str = content.get(self.search_text)  # type: ignore[return-value]
-        if maybe_version is not None:
-            log.debug(
-                "Found a key %r that looks like a version (%r)",
-                self.search_text,
-                maybe_version,
-            )
-            valid_version = Version.parse(maybe_version)
-            return {valid_version} if valid_version else set()
-        # Maybe in future raise error if not found?
-        return set()
-
-    def replace(self, new_version: Version) -> str:
-        """
-        Replace the version in the source content with `new_version`, and return the
-        updated content.
-        """
-        content = self._load()
-        if self.search_text in content:
-            log.info(
-                "found %r in source file contents, replacing with %s",
-                self.search_text,
-                new_version,
-            )
-            content[self.search_text] = str(new_version)
-
-        return tomlkit.dumps(cast(Dict[str, Any], content))
-
-
-class PatternVersionDeclaration(VersionDeclarationABC):
-    """
-    VersionDeclarationABC implementation representing a version number in a particular
-    file. The version number is identified by a regular expression, which should be
-    provided in `search_text`.
-    """
-
-    _VERSION_GROUP_NAME = "version"
-
-    def __init__(self, path: Path | str, search_text: str) -> None:
-        super().__init__(path, search_text)
-        self.search_re = re.compile(self.search_text, flags=re.MULTILINE)
-        if self._VERSION_GROUP_NAME not in self.search_re.groupindex:
-            raise ValueError(
-                f"Invalid search text {self.search_text!r}; must use 'version' as a "
-                "named group, for example (?P<version>...) . For more info on named "
-                "groups see https://docs.python.org/3/library/re.html"
-            )
-
-    # The pattern should be a regular expression with a single group,
-    # containing the version to replace.
-    def parse(self) -> set[Version]:
-        """
-        Return the versions matching this pattern.
-        Because a pattern can match in multiple places, this method returns a
-        set of matches.  Generally, there should only be one element in this
-        set (i.e. even if the version is specified in multiple places, it
-        should be the same version in each place), but it falls on the caller
-        to check for this condition.
-        """
-        versions = {
-            Version.parse(m.group(self._VERSION_GROUP_NAME))
-            for m in self.search_re.finditer(self.content, re.MULTILINE)
-        }
-
-        log.debug(
-            "Parsing current version: path=%r pattern=%r num_matches=%s",
-            self.path.resolve(),
-            self.search_text,
-            len(versions),
-        )
-        return versions
-
-    def replace(self, new_version: Version) -> str:
-        """
-        Update the versions.
-        This method reads the underlying file, replaces each occurrence of the
-        matched pattern, then writes the updated file.
-        :param new_version: The new version number as a `Version` instance
-        """
-        n = 0
-
-        def swap_version(m: re.Match[str]) -> str:
-            nonlocal n
-            n += 1
-            s = m.string
-            i, j = m.span()
-            log.debug("match spans characters %s:%s", i, j)
-            ii, jj = m.span(self._VERSION_GROUP_NAME)
-            log.debug("version group spans characters %s:%s", ii, jj)
-            return s[i:ii] + str(new_version) + s[jj:j]
-
-        new_content, n_matches = self.search_re.subn(
-            swap_version, self.content, re.MULTILINE
-        )
-
-        log.debug(
-            "path=%r pattern=%r num_matches=%r", self.path, self.search_text, n_matches
-        )
-
-        return new_content

semantic_release/version/declarations/enum.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from enum import Enum
+
+
+class VersionStampType(str, Enum):
+    """Enum for the type of version declaration"""
+
+    # The version is a number format, e.g. 1.2.3
+    NUMBER_FORMAT = "nf"
+
+    TAG_FORMAT = "tf"

semantic_release/version/declarations/i_version_replacer.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from abc import ABCMeta, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:  # pragma: no cover
+    from pathlib import Path
+
+    from semantic_release.version.version import Version
+
+
+class IVersionReplacer(metaclass=ABCMeta):
+    """
+    Interface for subclasses that replace a version string in a source file.
+
+    Methods generally have a base implementation are implemented here but
+    likely just provide a not-supported message but return gracefully
+
+    This class cannot be instantiated directly but must be inherited from
+    and implement the designated abstract methods.
+    """
+
+    @classmethod
+    def __subclasshook__(cls, subclass: type) -> bool:
+        # Validate that the subclass implements all of the abstract methods.
+        # This supports isinstance and issubclass checks.
+        return bool(
+            cls is IVersionReplacer
+            and all(
+                bool(hasattr(subclass, method) and callable(getattr(subclass, method)))
+                for method in IVersionReplacer.__abstractmethods__
+            )
+        )
+
+    @abstractmethod
+    def parse(self) -> set[Version]:
+        """
+        Return a set of the versions which can be parsed from the file.
+        Because a source can match in multiple places, this method returns a
+        set of matches. Generally, there should only be one element in this
+        set (i.e. even if the version is specified in multiple places, it
+        should be the same version in each place), but enforcing that condition
+        is not mandatory or expected.
+        """
+        raise NotImplementedError  # pragma: no cover
+
+    @abstractmethod
+    def replace(self, new_version: Version) -> str:
+        """
+        Replace the version in the source content with `new_version`, and return
+        the updated content.
+
+        :param new_version: The new version number as a `Version` instance
+        """
+        raise NotImplementedError  # pragma: no cover
+
+    @abstractmethod
+    def update_file_w_version(
+        self, new_version: Version, noop: bool = False
+    ) -> Path | None:
+        """
+        This method reads the underlying file, replaces each occurrence of the
+        matched pattern, then writes the updated file.
+
+        :param new_version: The new version number as a `Version` instance
+        """
+        raise NotImplementedError  # pragma: no cover

semantic_release/version/declarations/pattern.py

@@ -0,0 +1,241 @@
+from __future__ import annotations
+
+from logging import getLogger
+from pathlib import Path
+from re import (
+    MULTILINE,
+    compile as regexp,
+    error as RegExpError,  # noqa: N812
+    escape as regex_escape,
+)
+from typing import TYPE_CHECKING
+
+from deprecated.sphinx import deprecated
+
+from semantic_release.cli.util import noop_report
+from semantic_release.const import SEMVER_REGEX
+from semantic_release.version.declarations.enum import VersionStampType
+from semantic_release.version.declarations.i_version_replacer import IVersionReplacer
+from semantic_release.version.version import Version
+
+if TYPE_CHECKING:  # pragma: no cover
+    from re import Match
+
+
+log = getLogger(__name__)
+
+
+class VersionSwapper:
+    """Callable to replace a version number in a string with a new version number."""
+
+    def __init__(self, new_version_str: str, group_match_name: str) -> None:
+        self.version_str = new_version_str
+        self.group_match_name = group_match_name
+
+    def __call__(self, match: Match[str]) -> str:
+        i, j = match.span()
+        ii, jj = match.span(self.group_match_name)
+        return f"{match.string[i:ii]}{self.version_str}{match.string[jj:j]}"
+
+
+class PatternVersionDeclaration(IVersionReplacer):
+    """
+    VersionDeclarationABC implementation representing a version number in a particular
+    file. The version number is identified by a regular expression, which should be
+    provided in `search_text`.
+    """
+
+    _VERSION_GROUP_NAME = "version"
+
+    def __init__(
+        self, path: Path | str, search_text: str, stamp_format: VersionStampType
+    ) -> None:
+        self._content: str | None = None
+        self._path = Path(path).resolve()
+        self._stamp_format = stamp_format
+
+        try:
+            self._search_pattern = regexp(search_text, flags=MULTILINE)
+        except RegExpError as err:
+            raise ValueError(
+                f"Invalid regular expression for search text: {search_text!r}"
+            ) from err
+
+        if self._VERSION_GROUP_NAME not in self._search_pattern.groupindex:
+            raise ValueError(
+                str.join(
+                    " ",
+                    [
+                        f"Invalid search text {search_text!r}; must use",
+                        f"'{self._VERSION_GROUP_NAME}' as a named group, for example",
+                        f"(?P<{self._VERSION_GROUP_NAME}>...) . For more info on named",
+                        "groups see https://docs.python.org/3/library/re.html",
+                    ],
+                )
+            )
+
+    @property
+    def content(self) -> str:
+        """A cached property that stores the content of the configured source file."""
+        if self._content is None:
+            log.debug("No content stored, reading from source file %s", self._path)
+
+            if not self._path.exists():
+                raise FileNotFoundError(f"path {self._path!r} does not exist")
+
+            self._content = self._path.read_text()
+
+        return self._content
+
+    @content.deleter
+    def content(self) -> None:
+        self._content = None
+
+    @deprecated(
+        version="9.20.0",
+        reason="Function is unused and will be removed in a future release",
+    )
+    def parse(self) -> set[Version]:  # pragma: no cover
+        """
+        Return the versions matching this pattern.
+        Because a pattern can match in multiple places, this method returns a
+        set of matches.  Generally, there should only be one element in this
+        set (i.e. even if the version is specified in multiple places, it
+        should be the same version in each place), but it falls on the caller
+        to check for this condition.
+        """
+        versions = {
+            Version.parse(m.group(self._VERSION_GROUP_NAME))
+            for m in self._search_pattern.finditer(self.content)
+        }
+
+        log.debug(
+            "Parsing current version: path=%r pattern=%r num_matches=%s",
+            self._path.resolve(),
+            self._search_pattern,
+            len(versions),
+        )
+        return versions
+
+    def replace(self, new_version: Version) -> str:
+        """
+        Replace the version in the source content with `new_version`, and return
+        the updated content.
+
+        :param new_version: The new version number as a `Version` instance
+        """
+        new_content, n_matches = self._search_pattern.subn(
+            VersionSwapper(
+                new_version_str=(
+                    new_version.as_tag()
+                    if self._stamp_format == VersionStampType.TAG_FORMAT
+                    else str(new_version)
+                ),
+                group_match_name=self._VERSION_GROUP_NAME,
+            ),
+            self.content,
+        )
+
+        log.debug(
+            "path=%r pattern=%r num_matches=%r",
+            self._path,
+            self._search_pattern,
+            n_matches,
+        )
+
+        return new_content
+
+    def update_file_w_version(
+        self, new_version: Version, noop: bool = False
+    ) -> Path | None:
+        if noop:
+            if not self._path.exists():
+                noop_report(
+                    f"FILE NOT FOUND: cannot stamp version in non-existent file {self._path}",
+                )
+                return None
+
+            if len(self._search_pattern.findall(self.content)) < 1:
+                noop_report(
+                    f"VERSION PATTERN NOT FOUND: no version to stamp in file {self._path}",
+                )
+                return None
+
+            return self._path
+
+        new_content = self.replace(new_version)
+        if new_content == self.content:
+            return None
+
+        self._path.write_text(new_content)
+        del self.content
+
+        return self._path
+
+    @classmethod
+    def from_string_definition(
+        cls, replacement_def: str, tag_format: str
+    ) -> PatternVersionDeclaration:
+        """
+        create an instance of self from a string representing one item
+        of the "version_variables" list in the configuration
+        """
+        parts = replacement_def.split(":", maxsplit=2)
+
+        if len(parts) <= 1:
+            raise ValueError(
+                f"Invalid replacement definition {replacement_def!r}, missing ':'"
+            )
+
+        if len(parts) == 2:
+            # apply default version_type of "number_format" (ie. "1.2.3")
+            parts = [*parts, VersionStampType.NUMBER_FORMAT.value]
+
+        path, variable, version_type = parts
+
+        try:
+            stamp_type = VersionStampType(version_type)
+        except ValueError as err:
+            raise ValueError(
+                str.join(
+                    " ",
+                    [
+                        "Invalid stamp type, must be one of:",
+                        str.join(", ", [e.value for e in VersionStampType]),
+                    ],
+                )
+            ) from err
+
+        # DEFAULT: naked (no v-prefixed) semver version
+        value_replace_pattern_str = (
+            f"(?P<{cls._VERSION_GROUP_NAME}>{SEMVER_REGEX.pattern})"
+        )
+
+        if version_type == VersionStampType.TAG_FORMAT.value:
+            tag_parts = tag_format.strip().split(r"{version}", maxsplit=1)
+            value_replace_pattern_str = str.join(
+                "",
+                [
+                    f"(?P<{cls._VERSION_GROUP_NAME}>",
+                    regex_escape(tag_parts[0]),
+                    SEMVER_REGEX.pattern,
+                    (regex_escape(tag_parts[1]) if len(tag_parts) > 1 else ""),
+                    ")",
+                ],
+            )
+
+        search_text = str.join(
+            "",
+            [
+                # Supports optional matching quotations around variable name
+                # Negative lookbehind to ensure we don't match part of a variable name
+                f"""(?x)(?P<quote1>['"])?(?<![\\w.-]){regex_escape(variable)}(?P=quote1)?""",
+                # Supports walrus, equals sign, colon, or @ as assignment operator
+                # ignoring whitespace separation
+                r"\s*(:=|[:=@])\s*",
+                # Supports optional matching quotations around a version pattern (tag or raw format)
+                f"""(?P<quote2>['"])?{value_replace_pattern_str}(?P=quote2)?""",
+            ],
+        )
+
+        return cls(path, search_text, stamp_type)

semantic_release/version/declarations/toml.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+from logging import getLogger
+from pathlib import Path
+from typing import Any, Dict, cast
+
+import tomlkit
+from deprecated.sphinx import deprecated
+from dotty_dict import Dotty
+
+from semantic_release.cli.util import noop_report
+from semantic_release.version.declarations.enum import VersionStampType
+from semantic_release.version.declarations.i_version_replacer import IVersionReplacer
+from semantic_release.version.version import Version
+
+# globals
+log = getLogger(__name__)
+
+
+class TomlVersionDeclaration(IVersionReplacer):
+    def __init__(
+        self, path: Path | str, search_text: str, stamp_format: VersionStampType
+    ) -> None:
+        self._content: str | None = None
+        self._path = Path(path).resolve()
+        self._stamp_format = stamp_format
+        self._search_text = search_text
+
+    @property
+    def content(self) -> str:
+        """A cached property that stores the content of the configured source file."""
+        if self._content is None:
+            log.debug("No content stored, reading from source file %s", self._path)
+
+            if not self._path.exists():
+                raise FileNotFoundError(f"path {self._path!r} does not exist")
+
+            self._content = self._path.read_text()
+
+        return self._content
+
+    @content.deleter
+    def content(self) -> None:
+        self._content = None
+
+    @deprecated(
+        version="9.20.0",
+        reason="Function is unused and will be removed in a future release",
+    )
+    def parse(self) -> set[Version]:  # pragma: no cover
+        """Look for the version in the source content"""
+        content = self._load()
+        maybe_version: str = content.get(self._search_text)  # type: ignore[return-value]
+        if maybe_version is not None:
+            log.debug(
+                "Found a key %r that looks like a version (%r)",
+                self._search_text,
+                maybe_version,
+            )
+            valid_version = Version.parse(maybe_version)
+            return {valid_version} if valid_version else set()
+        # Maybe in future raise error if not found?
+        return set()
+
+    def replace(self, new_version: Version) -> str:
+        """
+        Replace the version in the source content with `new_version`, and return the
+        updated content.
+        """
+        content = self._load()
+        if self._search_text in content:
+            log.info(
+                "found %r in source file contents, replacing with %s",
+                self._search_text,
+                new_version,
+            )
+            content[self._search_text] = (
+                new_version.as_tag()
+                if self._stamp_format == VersionStampType.TAG_FORMAT
+                else str(new_version)
+            )
+
+        return tomlkit.dumps(cast(Dict[str, Any], content))
+
+    def _load(self) -> Dotty:
+        """Load the content of the source file into a Dotty for easier searching"""
+        return Dotty(tomlkit.loads(self.content))
+
+    def update_file_w_version(
+        self, new_version: Version, noop: bool = False
+    ) -> Path | None:
+        if noop:
+            if not self._path.exists():
+                noop_report(
+                    f"FILE NOT FOUND: cannot stamp version in non-existent file {self._path!r}",
+                )
+                return None
+
+            if self._search_text not in self._load():
+                noop_report(
+                    f"VERSION PATTERN NOT FOUND: no version to stamp in file {self._path!r}",
+                )
+                return None
+
+            return self._path
+
+        new_content = self.replace(new_version)
+        if new_content == self.content:
+            return None
+
+        self._path.write_text(new_content)
+        del self.content
+
+        return self._path
+
+    @classmethod
+    def from_string_definition(cls, replacement_def: str) -> TomlVersionDeclaration:
+        """
+        create an instance of self from a string representing one item
+        of the "version_toml" list in the configuration
+        """
+        parts = replacement_def.split(":", maxsplit=2)
+
+        if len(parts) <= 1:
+            raise ValueError(
+                f"Invalid TOML replacement definition {replacement_def!r}, missing ':'"
+            )
+
+        if len(parts) == 2:
+            # apply default version_type of "number_format" (ie. "1.2.3")
+            parts = [*parts, VersionStampType.NUMBER_FORMAT.value]
+
+        path, search_text, version_type = parts
+
+        try:
+            stamp_type = VersionStampType(version_type)
+        except ValueError as err:
+            raise ValueError(
+                str.join(
+                    " ",
+                    [
+                        "Invalid stamp type, must be one of:",
+                        str.join(", ", [e.value for e in VersionStampType]),
+                    ],
+                )
+            ) from err
+
+        return cls(path, search_text, stamp_type)