python-semantic-release 10.5.3__py3-none-any.whl → 10.6.0__py3-none-any.whl

{python_semantic_release-10.5.3.dist-info → python_semantic_release-10.6.0.dist-info}/METADATA

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: python-semantic-release
-Version: 10.5.3
+Version: 10.6.0
 Summary: Automatic Semantic Versioning for Python projects
 Author-email: Rolf Erik Lekang <me@rolflekang.com>, codejedi365 <codejedi365@gmail.com>
 License: MIT
-Project-URL: changelog, https://github.com/python-semantic-release/python-semantic-release/blob/master/CHANGELOG.md
+Project-URL: changelog, https://python-semantic-release.readthedocs.io/en/stable/misc/psr_changelog.html
 Project-URL: documentation, https://python-semantic-release.readthedocs.io
 Project-URL: homepage, https://python-semantic-release.readthedocs.io
 Project-URL: issues, https://github.com/python-semantic-release/python-semantic-release/issues

{python_semantic_release-10.5.3.dist-info → python_semantic_release-10.6.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-python_semantic_release-10.5.3.dist-info/licenses/LICENSE,sha256=NE85nszX252sdQdu0xgS9qwfYES0k8qS6gW3uO4jRGE,1083
+python_semantic_release-10.6.0.dist-info/licenses/LICENSE,sha256=NE85nszX252sdQdu0xgS9qwfYES0k8qS6gW3uO4jRGE,1083
 semantic_release/__init__.py,sha256=tRJWhrn_dUt0QycXD2DoJSfEP5uwmxngH7jvbG2i-hA,1317
 semantic_release/__main__.py,sha256=pksxr6g1vkKq98Q1lShsxG8tk55IMiSMHzAHKyFU5x0,1704
 semantic_release/const.py,sha256=wInJR7vcOgT1ysm5VuJQ6lD_ZGYnCwRVKz7Uz3htQc4,861
@@ -6,7 +6,7 @@ semantic_release/enums.py,sha256=vrEw1UNRcNrFjPqOFnuUzfeoqKj0ChixVVlyk5fqbng,174
 semantic_release/errors.py,sha256=FyocaqHbRhux-iNmCf9nI7awyUaGKjG9_5C_QDvhEas,3399
 semantic_release/gitproject.py,sha256=18jsD8YFsaKKqt_l5a0ccygIE_sOqvqf9FoEkJjyCkk,18584
 semantic_release/globals.py,sha256=IBhBbhZr2jx8dmpySnnu9m9jOGYu9Yu-vqHvAGQxgnw,464
-semantic_release/helpers.py,sha256=2uQXOiuiemiviVD52SH2FF6cn14p_gqvREeHvP7dexw,10012
+semantic_release/helpers.py,sha256=3munzjFYx_wxi97tRjCoP7EhcMtbgnO7G0ENlShCm8w,10334
 semantic_release/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 semantic_release/changelog/__init__.py,sha256=Bg6Xe5Vt32rWoMscW-hd4sUwiZqzWmsg4CD1EhMesMY,262
 semantic_release/changelog/context.py,sha256=234LLcB_uuGaQ5N_zTbcQYF27ZwYIBmicIWkhFs7-aQ,5993
@@ -15,21 +15,21 @@ semantic_release/changelog/template.py,sha256=eqOjtVfBbksgTK4CAZOajfkaAcKueJ-FhF
 semantic_release/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 semantic_release/cli/changelog_writer.py,sha256=2jP5b0LK61Y2tb22GQSFFmwHwXd2WjbopgsMAmsQsfY,9284
 semantic_release/cli/cli_context.py,sha256=Nop71LdVCJOeSUHgTXunMyK3xAu_QKQC2cRp1QBVkX0,4134
-semantic_release/cli/config.py,sha256=zNXlJHZBnFk2GEemgCg2Yw42EWihtFMot1twI7bEN-g,33668
+semantic_release/cli/config.py,sha256=jfG_N4rUo9pMpoC1eHNku_fK47eQXPrzRENu2g8CwWg,34297
 semantic_release/cli/const.py,sha256=h7XE2D0D__TAZSrUUtVszwvzpkHTMOiQCf97XQNbEvA,163
 semantic_release/cli/github_actions_output.py,sha256=yC0nsMvEFGACjDwB8DdmGKwNGI8aIIhDxRHrmcS7tzA,5410
 semantic_release/cli/masking_filter.py,sha256=7t7XFL7Iy4QTvaYevZ-jnTkJBz15GoBw1vjW3hihe38,3159
-semantic_release/cli/util.py,sha256=4rf4xDHb7l-XpdcFNtslFz1xHslnBu6cTgWHXVnQXQs,3746
+semantic_release/cli/util.py,sha256=6TAbHgDZU6T-rm5yzg2TdGP_-ueHQhfbAkghP1q6we0,3750
 semantic_release/cli/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 semantic_release/cli/commands/changelog.py,sha256=wJfd4VVfrGnu2jnIpG25cdVcbXIX-ElKl3b2jdtPPa0,5391
-semantic_release/cli/commands/generate_config.py,sha256=2xZOu3NpyhBp0pWr7d8ugKl_kjqQgpSsSMHq5wHTfrE,1699
+semantic_release/cli/commands/generate_config.py,sha256=sKTO2V_XGRFc6M5KaTEPS4UOmqDuQOyTm64IYLr1VBc,2452
 semantic_release/cli/commands/main.py,sha256=u1zhkkvKCZ2TtUqjzvdFTe5UZsvfws_pjqqo6CY0bBo,4351
-semantic_release/cli/commands/publish.py,sha256=CE_LJTxFnc337MfpsfdJopi7QCwwE13GqGNQ-dNgWis,2871
+semantic_release/cli/commands/publish.py,sha256=q9sNYCqlIjbT8RjJvHPVYzDdAjtnXe4_IdT0_h4S9MA,3047
 semantic_release/cli/commands/version.py,sha256=8pn21AskKRMg1WJJXNNTZzlS1bNZefHKOPDRe-3NF5M,29502
 semantic_release/commit_parser/__init__.py,sha256=uCC2YI-EDPUAa6TwWYJA8TS7baWE2bXrLEGcrhJKofI,1323
 semantic_release/commit_parser/_base.py,sha256=DLsHnbXG-39JkUbcnsBCSV2GmV35w1rasyoMhK8G0UE,3058
 semantic_release/commit_parser/angular.py,sha256=MY_fo9F4EZ-ac8wYzBR0uD94O5Li2D-8zEMR01wss4c,18534
-semantic_release/commit_parser/emoji.py,sha256=0VecUMMcj43UaKDZ2GaFFUG26zOJAvXsEobTHaXNkk0,17749
+semantic_release/commit_parser/emoji.py,sha256=IMRq0sUat-cU7aNIg38M0kAmZ376p7zuRy3XSOgsrOM,17826
 semantic_release/commit_parser/scipy.py,sha256=gA9TfmrxGVvtv6kki6N_9abJx-_WlpBsSX2TBh0YgPw,19463
 semantic_release/commit_parser/tag.py,sha256=bVO2XghM0G_eW2rG9Xc2q5TPsjtxr-xcHK5RpE1u_HM,3537
 semantic_release/commit_parser/token.py,sha256=1_q8mJ4SRu7kNfa-Nxr8fEyuvCfjPgiPEitqSP1KR5g,7904
@@ -62,23 +62,24 @@ semantic_release/hvcs/__init__.py,sha256=JwoaLOF-12L-OBo_9-tOXXhdiHKeVungA9865to
 semantic_release/hvcs/_base.py,sha256=gUCAbSHidhB6ou1oOP--wqEaVc4X2NPLjZQ5P_g3Bwc,2600
 semantic_release/hvcs/bitbucket.py,sha256=dbWvqf79ACN42srhfVRtJ8m5WNI-_d7NE1cxZPwtCLs,10148
 semantic_release/hvcs/gitea.py,sha256=PWK3URTuiWvx0SwSlSIGCbtVmD7XjaYo051fiTUYsJY,13463
-semantic_release/hvcs/github.py,sha256=guXx7Zc2o3z2eOs8KzYt3BifO5cNWuti1ZmZdL7bN3Q,20695
+semantic_release/hvcs/github.py,sha256=taaoLs1khLlpJp3IjyRiNBk_c_bQim8goYSistnL_Xk,21157
 semantic_release/hvcs/gitlab.py,sha256=uUnTKq9Kpqc83ppXA3NXfVYnz4O1ej2noz68jCYzg68,10606
 semantic_release/hvcs/remote_hvcs_base.py,sha256=QtkjdMy9l-c7UOtyPz25cqVOkCk4IU-EOw6A8lP8l-U,6327
 semantic_release/hvcs/token_auth.py,sha256=ZjT56-NIPB4OKIt1qwHCu1TavXnrWFIBl9ARlg56hgU,663
 semantic_release/hvcs/util.py,sha256=PUNV4yUlpzDtNCFmh2joaPdU4JyfUBnVp0zaQsT9EDQ,2871
 semantic_release/version/__init__.py,sha256=CLhtGQry9dLIij5XyRa9ZevxU_1p8tjMTSQ-K_GMpWM,270
 semantic_release/version/algorithm.py,sha256=IxgYNF78W7qdMzdV4WsoljwfJgB-sn2XdfkevD0aZlo,16254
-semantic_release/version/declaration.py,sha256=eot_lUyFaEhzK4bPncfv9tahf51LdxZP6EaS54h3aAs,3635
+semantic_release/version/declaration.py,sha256=qWHnDm8xakX_dXcPDhKk_3J5Zuu7HUYKmbqm5Iv68uQ,3743
 semantic_release/version/translator.py,sha256=iIfu3WreB9qqPHgqJLILbBluVQQNcpP0DEsnn_WzAaM,3689
 semantic_release/version/version.py,sha256=Y3Qqqv7CypirikT7jNqqFMNAvR2UjV-VQx-c2G0mZc0,14519
 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/file.py,sha256=m-MohBTN69T3unoPcSBgwA76ftwPr2WXfGgVjSvf1vY,4683
+semantic_release/version/declarations/i_version_replacer.py,sha256=YktOY_7cfguZHEyV5f_R-ldMznj140mcS0BXdoa9zf8,2584
 semantic_release/version/declarations/pattern.py,sha256=sKk0uQpJjWVZc8RJUjxQoEPUvFLxXNGGBow5h1IqCTM,8378
 semantic_release/version/declarations/toml.py,sha256=2K4DtX5Qq1iHT8cG8mISPTMmp50w6Av0KmLAKZPYqq8,4931
-python_semantic_release-10.5.3.dist-info/METADATA,sha256=XFvZTTkpyX9iO4fzsBv6XBqN-_qxjLf3eC3Rr9ZFbGQ,4064
-python_semantic_release-10.5.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-python_semantic_release-10.5.3.dist-info/entry_points.txt,sha256=kzkCyDJsMOwgpFwEWKE9wxN1tXaUP6g6GIO4xtc0QuE,162
-python_semantic_release-10.5.3.dist-info/top_level.txt,sha256=qYA24nyg3eP-ti5UW7Vuj2aXVmM0wqVHx4mREdRZNAA,17
-python_semantic_release-10.5.3.dist-info/RECORD,,
+python_semantic_release-10.6.0.dist-info/METADATA,sha256=loZ9-00JeyoQIE0DUn9O3JlLMhbpDVX8AHW6ULb_G6c,4053
+python_semantic_release-10.6.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+python_semantic_release-10.6.0.dist-info/entry_points.txt,sha256=kzkCyDJsMOwgpFwEWKE9wxN1tXaUP6g6GIO4xtc0QuE,162
+python_semantic_release-10.6.0.dist-info/top_level.txt,sha256=qYA24nyg3eP-ti5UW7Vuj2aXVmM0wqVHx4mREdRZNAA,17
+python_semantic_release-10.6.0.dist-info/RECORD,,

{python_semantic_release-10.5.3.dist-info → python_semantic_release-10.6.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (80.10.2)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

semantic_release/cli/commands/generate_config.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
 import json
+import sys
+from typing import Literal
 
 import click
 import tomlkit
@@ -31,7 +33,9 @@ from semantic_release.cli.config import RawConfig
         "'semantic_release'"
     ),
 )
-def generate_config(fmt: str = "toml", is_pyproject_toml: bool = False) -> None:
+def generate_config(
+    fmt: Literal["toml", "json"], is_pyproject_toml: bool = False
+) -> None:
     """
     Generate default configuration for semantic-release, to help you get started
     quickly. You can inspect the defaults, write to a file and then edit according to
@@ -42,14 +46,29 @@ def generate_config(fmt: str = "toml", is_pyproject_toml: bool = False) -> None:
     """
     # due to possible IntEnum values (which are not supported by tomlkit.dumps, see sdispater/tomlkit#237),
     # we must ensure the transformation of the model to a dict uses json serializable values
-    config = RawConfig().model_dump(mode="json", exclude_none=True)
+    config_dct = {
+        "semantic_release": RawConfig().model_dump(mode="json", exclude_none=True)
+    }
 
-    config_dct = {"semantic_release": config}
-    if is_pyproject_toml and fmt == "toml":
-        config_dct = {"tool": config_dct}
+    if is_pyproject_toml:
+        output = tomlkit.dumps({"tool": config_dct})
 
-    if fmt == "toml":
-        click.echo(tomlkit.dumps(config_dct))
+    elif fmt == "toml":
+        output = tomlkit.dumps(config_dct)
 
     elif fmt == "json":
-        click.echo(json.dumps(config_dct, indent=4))
+        output = json.dumps(config_dct, indent=4)
+
+    else:
+        raise ValueError(f"Unsupported format: {fmt}")
+
+    # Write output directly to stdout buffer as UTF-8 bytes
+    # This ensures consistent UTF-8 output on all platforms, especially Windows where
+    # shell redirection (>, >>) defaults to the system encoding (e.g., UTF-16LE or cp1252)
+    # By writing to sys.stdout.buffer, we bypass the encoding layer and guarantee UTF-8.
+    try:
+        sys.stdout.buffer.write(f"{output.strip()}\n".encode("utf-8"))  # noqa: UP012; allow explicit encoding declaration
+        sys.stdout.buffer.flush()
+    except (AttributeError, TypeError):
+        # Fallback for environments without buffer (shouldn't happen in standard Python)
+        click.echo(output)

semantic_release/cli/commands/publish.py

@@ -6,6 +6,7 @@ import click
 from git import Repo
 
 from semantic_release.cli.util import noop_report
+from semantic_release.errors import AssetUploadError
 from semantic_release.globals import logger
 from semantic_release.hvcs.remote_hvcs_base import RemoteHvcsBase
 from semantic_release.version.algorithm import tags_and_versions
@@ -90,9 +91,13 @@ def publish(cli_ctx: CliContextObj, tag: str) -> None:
         )
         return
 
-    publish_distributions(
-        tag=tag,
-        hvcs_client=hvcs_client,
-        dist_glob_patterns=dist_glob_patterns,
-        noop=runtime.global_cli_options.noop,
-    )
+    try:
+        publish_distributions(
+            tag=tag,
+            hvcs_client=hvcs_client,
+            dist_glob_patterns=dist_glob_patterns,
+            noop=runtime.global_cli_options.noop,
+        )
+    except AssetUploadError as err:
+        click.echo(err, err=True)
+        ctx.exit(1)

semantic_release/cli/config.py

@@ -57,6 +57,7 @@ from semantic_release.errors import (
 )
 from semantic_release.globals import logger
 from semantic_release.helpers import dynamic_import
+from semantic_release.version.declarations.file import FileVersionDeclaration
 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
@@ -757,12 +758,22 @@ class RuntimeContext:
             ) from err
 
         try:
-            version_declarations.extend(
-                PatternVersionDeclaration.from_string_definition(
-                    definition, raw.tag_format
+            for definition in iter(raw.version_variables or ()):
+                # Check if this is a file replacement definition (pattern is "*")
+                parts = definition.split(":", maxsplit=2)
+                if len(parts) >= 2 and parts[1] == "*":
+                    # Use FileVersionDeclaration for entire file replacement
+                    version_declarations.append(
+                        FileVersionDeclaration.from_string_definition(definition)
+                    )
+                    continue
+
+                # Use PatternVersionDeclaration for pattern-based replacement
+                version_declarations.append(
+                    PatternVersionDeclaration.from_string_definition(
+                        definition, raw.tag_format
+                    )
                 )
-                for definition in iter(raw.version_variables or ())
-            )
         except ValueError as err:
             raise InvalidConfiguration(
                 str.join(

semantic_release/cli/util.py

@@ -75,7 +75,7 @@ def load_raw_config_file(config_file: Path | str) -> dict[Any, Any]:
     while trying to read the specified configuration file
     """
     logger.info("Loading configuration from %s", config_file)
-    raw_text = (Path() / config_file).resolve().read_text(encoding="utf-8")
+    raw_text = (Path() / config_file).resolve().read_text(encoding="utf-8-sig")
     try:
         logger.debug("Trying to parse configuration %s in TOML format", config_file)
         return parse_toml(raw_text)

semantic_release/commit_parser/emoji.py

@@ -65,7 +65,12 @@ class EmojiParserOptions(ParserOptions):
     )
     """Commit-type prefixes that should result in a patch release bump."""
 
-    other_allowed_tags: Tuple[str, ...] = (":memo:", ":checkmark:")
+    other_allowed_tags: Tuple[str, ...] = (
+        ":checkmark:",
+        ":construction_worker:",
+        ":memo:",
+        ":recycle:",
+    )
     """Commit-type prefixes that are allowed but do not result in a version bump."""
 
     allowed_tags: Tuple[str, ...] = (

semantic_release/helpers.py

@@ -9,7 +9,7 @@ from functools import lru_cache, reduce, wraps
 from pathlib import Path, PurePosixPath
 from re import IGNORECASE, compile as regexp
 from typing import TYPE_CHECKING, Any, Callable, NamedTuple, Sequence, TypeVar
-from urllib.parse import urlsplit
+from urllib.parse import urlsplit, urlunsplit
 
 from semantic_release.globals import logger
 
@@ -215,6 +215,16 @@ class ParsedGitUrl(NamedTuple):
     repo_name: str
 
 
+def _hide_credentials_in_url(url: str) -> str:
+    url_parts = urlsplit(url)
+
+    if not url_parts.scheme or "@" not in url_parts.netloc:
+        return url
+
+    _, _, host = url_parts.netloc.rpartition("@")
+    return urlunsplit(url_parts._replace(netloc=f"<credentials>@{host}"))
+
+
 @lru_cache(maxsize=512)
 def parse_git_url(url: str) -> ParsedGitUrl:
     """
@@ -242,7 +252,7 @@ def parse_git_url(url: str) -> ParsedGitUrl:
 
     Raises ValueError if the url can't be parsed.
     """
-    logger.debug("Parsing git url %r", url)
+    logger.debug("Parsing git url %r", _hide_credentials_in_url(url))
 
     # Normalizers are a list of tuples of (pattern, replacement)
     normalizers = [

semantic_release/hvcs/github.py

@@ -463,14 +463,25 @@ class Github(RemoteHvcsBase):
 
         # Upload assets
         n_succeeded = 0
+        errors = []
         for file_path in (
             f for f in glob.glob(dist_glob, recursive=True) if os.path.isfile(f)
         ):
             try:
                 self.upload_release_asset(release_id, file_path)
                 n_succeeded += 1
-            except HTTPError:  # noqa: PERF203
+            except HTTPError as err:  # noqa: PERF203
                 logger.exception("error uploading asset %s", file_path)
+                status_code = (
+                    err.response.status_code if err.response is not None else "unknown"
+                )
+                error_msg = f"Failed to upload asset '{file_path}' to release"
+                if status_code != "unknown":
+                    error_msg += f" (HTTP {status_code})"
+                errors.append(error_msg)
+
+        if errors:
+            raise AssetUploadError("\n".join(errors))
 
         return n_succeeded
 

semantic_release/version/declaration.py

@@ -9,6 +9,7 @@ from deprecated.sphinx import deprecated
 
 from semantic_release.globals import logger
 from semantic_release.version.declarations.enum import VersionStampType
+from semantic_release.version.declarations.file import FileVersionDeclaration
 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
@@ -19,11 +20,12 @@ if TYPE_CHECKING:  # pragma: no cover
 
 # Globals
 __all__ = [
+    "FileVersionDeclaration",
     "IVersionReplacer",
-    "VersionStampType",
     "PatternVersionDeclaration",
     "TomlVersionDeclaration",
     "VersionDeclarationABC",
+    "VersionStampType",
 ]
 
 

semantic_release/version/declarations/file.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from deprecated.sphinx import deprecated
+
+from semantic_release.globals import logger
+from semantic_release.version.declarations.enum import VersionStampType
+from semantic_release.version.declarations.i_version_replacer import IVersionReplacer
+
+if TYPE_CHECKING:  # pragma: no cover
+    from semantic_release.version.version import Version
+
+
+class FileVersionDeclaration(IVersionReplacer):
+    """
+    IVersionReplacer implementation that replaces the entire file content
+    with the version string.
+
+    This is useful for files that contain only a version number, such as
+    VERSION files or similar single-line version storage files.
+    """
+
+    def __init__(self, path: Path | str, stamp_format: VersionStampType) -> None:
+        self._content: str | None = None
+        self._path = Path(path).resolve()
+        self._stamp_format = stamp_format
+
+    @property
+    def content(self) -> str:
+        """A cached property that stores the content of the configured source file."""
+        if self._content is None:
+            logger.debug("No content stored, reading from source file %s", self._path)
+
+            if not self._path.exists():
+                logger.debug(
+                    f"path {self._path!r} does not exist, assuming empty content"
+                )
+                self._content = ""
+            else:
+                self._content = self._path.read_text()
+
+        return self._content
+
+    @content.deleter
+    def content(self) -> None:
+        self._content = None
+
+    @deprecated(
+        version="10.6.0",
+        reason="Function is unused and will be removed in a future release",
+    )
+    def parse(self) -> set[Version]:
+        raise NotImplementedError  # pragma: no cover
+
+    def replace(self, new_version: Version) -> str:
+        """
+        Replace the file content with the new version string.
+
+        :param new_version: The new version number as a `Version` instance
+        :return: The new content (just the version string)
+        """
+        new_content = (
+            new_version.as_tag()
+            if self._stamp_format == VersionStampType.TAG_FORMAT
+            else str(new_version)
+        )
+
+        logger.debug(
+            "Replacing entire file content: path=%r old_content=%r new_content=%r",
+            self._path,
+            self.content.strip(),
+            new_content,
+        )
+
+        return new_content
+
+    def update_file_w_version(
+        self, new_version: Version, noop: bool = False
+    ) -> Path | None:
+        if noop:
+            if not self._path.exists():
+                logger.warning(
+                    f"FILE NOT FOUND: file '{self._path}' does not exist but it will be created"
+                )
+
+            return self._path
+
+        new_content = self.replace(new_version)
+        if new_content == self.content.strip():
+            return None
+
+        self._path.write_text(f"{new_content}\n")
+        del self.content
+
+        return self._path
+
+    @classmethod
+    def from_string_definition(cls, replacement_def: str) -> FileVersionDeclaration:
+        """
+        Create an instance of self from a string representing one item
+        of the "version_variables" list in the configuration.
+
+        This method expects a definition in the format:
+        "file:*:format_type"
+
+        where:
+        - file is the path to the file
+        - * is the literal asterisk character indicating file replacement
+        - format_type is either "nf" (number format) or "tf" (tag format)
+        """
+        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, pattern, version_type = parts
+
+        # Validate that the pattern is exactly "*"
+        if pattern != "*":
+            raise ValueError(
+                f"Invalid pattern {pattern!r} for FileVersionDeclaration, expected '*'"
+            )
+
+        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, stamp_type)

semantic_release/version/declarations/i_version_replacer.py

@@ -3,6 +3,8 @@ from __future__ import annotations
 from abc import ABCMeta, abstractmethod
 from typing import TYPE_CHECKING
 
+from deprecated.sphinx import deprecated
+
 if TYPE_CHECKING:  # pragma: no cover
     from pathlib import Path
 
@@ -32,6 +34,10 @@ class IVersionReplacer(metaclass=ABCMeta):
             )
         )
 
+    @deprecated(
+        version="9.20.0",
+        reason="Function is unused and will be removed in a future release",
+    )
     @abstractmethod
     def parse(self) -> set[Version]:
         """