python-semantic-release 9.19.1__tar.gz → 9.21.0__tar.gz

{python_semantic_release-9.19.1/src/python_semantic_release.egg-info → python_semantic_release-9.21.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-semantic-release
-Version: 9.19.1
+Version: 9.21.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: docs
@@ -63,6 +64,7 @@ Requires-Dist: tox~=4.11; extra == "dev"
 Requires-Dist: ruff==0.6.1; extra == "dev"
 Provides-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"
 

{python_semantic_release-9.19.1 → python_semantic_release-9.21.0}/docs/automatic-releases/github-actions.rst

@@ -337,7 +337,7 @@ before the :ref:`version <cmd-version>` subcommand.
 
   .. code:: yaml
 
-    - uses: python-semantic-release/python-semantic-release@v9.19.0
+    - uses: python-semantic-release/python-semantic-release@v9.20.0
       with:
         root_options: "-vv --noop"
 
@@ -576,7 +576,7 @@ before the :ref:`publish <cmd-publish>` subcommand.
 
   .. code:: yaml
 
-    - uses: python-semantic-release/publish-action@v9.19.0
+    - uses: python-semantic-release/publish-action@v9.20.0
       with:
         root_options: "-vv --noop"
 
@@ -643,7 +643,7 @@ Examples
 Common Workflow Example
 -----------------------
 
-The following is a common workflow example that uses both the Python Semantic Release Action
+The following is a simple common workflow example that uses both the Python Semantic Release Action
 and the Python Semantic Release Publish Action. This workflow will run on every push to the
 ``main`` branch and will create a new release upon a successful version determination. If a
 version is released, the workflow will then publish the package to PyPI and upload the package
@@ -661,30 +661,74 @@ to the GitHub Release Assets as well.
     jobs:
       release:
         runs-on: ubuntu-latest
-        concurrency: release
+        concurrency:
+          group: ${{ github.workflow }}-release-${{ github.ref_name }}
+          cancel-in-progress: false
 
         permissions:
           id-token: write
           contents: write
 
         steps:
-          # Note: we need to checkout the repository at the workflow sha in case during the workflow
-          # the branch was updated. To keep PSR working with the configured release branches,
-          # we force a checkout of the desired release branch but at the workflow sha HEAD.
-          - name: Setup | Checkout Repository at workflow sha
+          # Note: We checkout the repository at the branch that triggered the workflow
+          # with the entire history to ensure to match PSR's release branch detection
+          # and history evaluation.
+          # However, we forcefully reset the branch to the workflow sha because it is
+          # possible that the branch was updated while the workflow was running. This
+          # prevents accidentally releasing un-evaluated changes.
+          - name: Setup | Checkout Repository on Release Branch
             uses: actions/checkout@v4
             with:
+              ref: ${{ github.ref_name }}
               fetch-depth: 0
-              ref: ${{ github.sha }}
 
-          - name: Setup | Force correct release branch on workflow sha
+          - name: Setup | Force release branch to be at workflow sha
             run: |
-              git checkout -B ${{ github.ref_name }} ${{ github.sha }}
+              git reset --hard ${{ github.sha }}
+
+          - name: Evaluate | Verify upstream has NOT changed
+            # Last chance to abort before causing an error as another PR/push was applied to
+            # the upstream branch while this workflow was running. This is important
+            # because we are committing a version change (--commit). You may omit this step
+            # if you have 'commit: false' in your configuration.
+            #
+            # You may consider moving this to a repo script and call it from this step instead
+            # of writing it in-line.
+            shell: bash
+            run: |
+              set +o pipefail
+
+              UPSTREAM_BRANCH_NAME="$(git status -sb | head -n 1 | cut -d' ' -f2 | grep -E '\.{3}' | cut -d'.' -f4)"
+              printf '%s\n' "Upstream branch name: $UPSTREAM_BRANCH_NAME"
+
+              set -o pipefail
+
+              if [ -z "$UPSTREAM_BRANCH_NAME" ]; then
+                  printf >&2 '%s\n' "::error::Unable to determine upstream branch name!"
+                  exit 1
+              fi
+
+              git fetch "${UPSTREAM_BRANCH_NAME%%/*}"
+
+              if ! UPSTREAM_SHA="$(git rev-parse "$UPSTREAM_BRANCH_NAME")"; then
+                  printf >&2 '%s\n' "::error::Unable to determine upstream branch sha!"
+                  exit 1
+              fi
+
+              HEAD_SHA="$(git rev-parse HEAD)"
+
+              if [ "$HEAD_SHA" != "$UPSTREAM_SHA" ]; then
+                  printf >&2 '%s\n' "[HEAD SHA] $HEAD_SHA != $UPSTREAM_SHA [UPSTREAM SHA]"
+                  printf >&2 '%s\n' "::error::Upstream has changed, aborting release..."
+                  exit 1
+              fi
+
+              printf '%s\n' "Verified upstream branch has not changed, continuing with release..."
 
           - name: Action | Semantic Version Release
             id: release
             # Adjust tag with desired version if applicable.
-            uses: python-semantic-release/python-semantic-release@v9.19.0
+            uses: python-semantic-release/python-semantic-release@v9.20.0
             with:
               github_token: ${{ secrets.GITHUB_TOKEN }}
               git_committer_name: "github-actions"
@@ -695,7 +739,7 @@ to the GitHub Release Assets as well.
             if: steps.release.outputs.released == 'true'
 
           - name: Publish | Upload to GitHub Release Assets
-            uses: python-semantic-release/publish-action@v9.19.0
+            uses: python-semantic-release/publish-action@v9.20.0
             if: steps.release.outputs.released == 'true'
             with:
               github_token: ${{ secrets.GITHUB_TOKEN }}
@@ -706,6 +750,11 @@ to the GitHub Release Assets as well.
   one release job in the case if there are multiple pushes to ``main`` in a short period
   of time.
 
+  Secondly the *Evaluate | Verify upstream has NOT changed* step is used to ensure that the
+  upstream branch has not changed while the workflow was running. This is important because
+  we are committing a version change (``commit: true``) and there might be a push collision
+  that would cause undesired behavior. Review Issue `#1201`_ for more detailed information.
+
 .. warning::
   You must set ``fetch-depth`` to 0 when using ``actions/checkout@v4``, since
   Python Semantic Release needs access to the full history to build a changelog
@@ -721,6 +770,7 @@ to the GitHub Release Assets as well.
   case, you will also need to pass the new token to ``actions/checkout`` (as
   the ``token`` input) in order to gain push access.
 
+.. _#1201: https://github.com/python-semantic-release/python-semantic-release/issues/1201
 .. _concurrency: https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idconcurrency
 
 Version Overrides Example
@@ -744,7 +794,7 @@ The equivalent GitHub Action configuration would be:
 
   - name: Action | Semantic Version Release
     # Adjust tag with desired version if applicable.
-    uses: python-semantic-release/python-semantic-release@v9.19.0
+    uses: python-semantic-release/python-semantic-release@v9.20.0
     with:
       github_token: ${{ secrets.GITHUB_TOKEN }}
       force: patch
@@ -772,13 +822,13 @@ Publish Action.
 .. code:: yaml
 
    - name: Release Project 1
-     uses: python-semantic-release/python-semantic-release@v9.19.0
+     uses: python-semantic-release/python-semantic-release@v9.20.0
      with:
        directory: ./project1
        github_token: ${{ secrets.GITHUB_TOKEN }}
 
    - name: Release Project 2
-     uses: python-semantic-release/python-semantic-release@v9.19.0
+     uses: python-semantic-release/python-semantic-release@v9.20.0
      with:
        directory: ./project2
        github_token: ${{ secrets.GITHUB_TOKEN }}

{python_semantic_release-9.19.1 → python_semantic_release-9.21.0}/docs/configuration.rst

@@ -1201,17 +1201,61 @@ Tags which do not match this format will not be considered as versions of your p
 
 **Type:** ``list[str]``
 
-Similar to :ref:`config-version_variables`, but allows the version number to be
-identified safely in a toml file like ``pyproject.toml``, with each entry using
-dotted notation to indicate the key for which the value represents the version:
+This configuration option is similar to :ref:`config-version_variables`, but it uses
+a TOML parser to interpret the data structure before, inserting the version. This
+allows users to use dot-notation to specify the version via the logical structure
+within the TOML file, which is more accurate than a pattern replace.
+
+The ``version_toml`` option is commonly used to update the version number in the project
+definition file: ``pyproject.toml`` as seen in the example below.
+
+As of v9.20.0, the ``version_toml`` option accepts a colon-separated definition
+with either 2 or 3 parts. The 2-part definition includes the file path and the version
+parameter (in dot-notation). Newly with v9.20.0, it also accepts an optional
+3rd part to allow configuration of the format type.
+
+**Available Format Types**
+
+- ``nf``: Number format (ex. ``1.2.3``)
+- ``tf``: :ref:`Tag Format <config-tag_format>` (ex. ``v1.2.3``)
+
+If the format type is not specified, it will default to the number format.
+
+**Example**
 
 .. code-block:: toml
 
     [semantic_release]
     version_toml = [
-        "pyproject.toml:tool.poetry.version",
+        # "file:variable:[format_type]"
+        "pyproject.toml:tool.poetry.version",  # Implied Default: Number format
+        "definition.toml:project.version:nf",  # Number format
+        "definition.toml:project.release:tf",  # Tag format
     ]
 
+This configuration will result in the following changes:
+
+.. code-block:: diff
+
+    diff a/pyproject.toml b/pyproject.toml
+
+      [tool.poetry]
+    - version = "0.1.0"
+    + version = "0.2.0"
+
+.. code-block:: diff
+
+    diff a/definition.toml b/definition.toml
+
+      [project]
+      name = "example"
+
+    - version = "0.1.0"
+    + version = "0.1.0"
+
+    - release = "v0.1.0"
+    + release = "v0.2.0"
+
 **Default:** ``[]``
 
 ----
@@ -1223,44 +1267,153 @@ dotted notation to indicate the key for which the value represents the version:
 
 **Type:** ``list[str]``
 
-Each entry represents a location where the version is stored in the source code,
-specified in ``file:variable`` format. For example:
+The ``version_variables`` configuration option is a list of string definitions
+that defines where the version number should be updated in the repository, when
+a new version is released.
+
+As of v9.20.0, the ``version_variables`` option accepts a
+colon-separated definition with either 2 or 3 parts. The 2-part definition includes
+the file path and the variable name. Newly with v9.20.0, it also accepts
+an optional 3rd part to allow configuration of the format type.
+
+**Available Format Types**
+
+- ``nf``: Number format (ex. ``1.2.3``)
+- ``tf``: :ref:`Tag Format <config-tag_format>` (ex. ``v1.2.3``)
+
+If the format type is not specified, it will default to the number format.
+
+Prior to v9.20.0, PSR only supports entries with the first 2-parts
+as the tag format type was not available and would only replace numeric
+version numbers.
+
+**Example**
 
 .. code-block:: toml
 
     [semantic_release]
+    tag_format = "v{version}"
     version_variables = [
-        "src/semantic_release/__init__.py:__version__",
-        "docs/conf.py:version",
+        # "file:variable:format_type"
+        "src/semantic_release/__init__.py:__version__",  # Implied Default: Number format
+        "docs/conf.py:version:nf",                       # Number format for sphinx docs
+        "kustomization.yml:newTag:tf",                   # Tag format
     ]
 
+First, the ``__version__`` variable in ``src/semantic_release/__init__.py`` will be updated
+with the next version using the `SemVer`_ number format.
+
+.. code-block:: diff
+
+    diff a/src/semantic_release/__init__.py b/src/semantic_release/__init__.py
+
+    - __version__ = "0.1.0"
+    + __version__ = "0.2.0"
+
+Then, the ``version`` variable in ``docs/conf.py`` will be updated with the next version
+with the next version using the `SemVer`_ number format because of the explicit ``nf``.
+
+.. code-block:: diff
+
+    diff a/docs/conf.py b/docs/conf.py
+
+    - version = "0.1.0"
+    + version = "0.2.0"
+
+Lastly, the ``newTag`` variable in ``kustomization.yml`` will be updated with the next version
+with the next version using the configured :ref:`config-tag_format` because the definition
+included ``tf``.
+
+.. code-block:: diff
+
+    diff a/kustomization.yml b/kustomization.yml
+
+      images:
+        - name: repo/image
+    -     newTag: v0.1.0
+    +     newTag: v0.2.0
+
+**How It works**
+
 Each version variable will be transformed into a Regular Expression that will be used
 to substitute the version number in the file. The replacement algorithm is **ONLY** a
 pattern match and replace. It will **NOT** evaluate the code nor will PSR understand
 any internal object structures (ie. ``file:object.version`` will not work).
 
-.. important::
-    The Regular Expression expects a version value to exist in the file to be replaced.
-    It cannot be an empty string or a non-semver compliant string. If this is the very
-    first time you are using PSR, we recommend you set the version to ``0.0.0``. This
-    may become more flexible in the future with resolution of issue `#941`_.
+The regular expression generated from the ``version_variables`` definition will:
 
-.. _#941: https://github.com/python-semantic-release/python-semantic-release/issues/941
+1. Look for the specified ``variable`` name in the ``file``. The variable name can be
+   enclosed by single (``'``) or double (``"``) quotation marks but they must match.
+
+2. The variable name defined by ``variable`` and the version must be separated by
+   an operand symbol (``=``, ``:``, ``:=``, or ``@``). Whitespace is optional around
+   the symbol.
+
+3. The value of the variable must match a `SemVer`_ regular expression and can be
+   enclosed by single (``'``) or double (``"``) quotation marks but they must match. However,
+   the enclosing quotes of the value do not have to match the quotes surrounding the variable
+   name.
+
+4. If the format type is set to ``tf`` then the variable value must have the matching prefix
+   and suffix of the :ref:`config-tag_format` setting around the `SemVer`_ version number.
 
 Given the pattern matching nature of this feature, the Regular Expression is able to
-support most file formats as a variable declaration in most languages is very similar.
-We specifically support Python, YAML, and JSON as these have been the most common
-requests. This configuration option will also work regardless of file extension
-because its only a pattern match.
+support most file formats because of the similarity of variable declaration across
+programming languages. PSR specifically supports Python, YAML, and JSON as these have
+been the most commonly requested formats. This configuration option will also work
+regardless of file extension because it looks for a matching pattern string.
 
 .. note::
     This will also work for TOML but we recommend using :ref:`config-version_toml` for
     TOML files as it actually will interpret the TOML file and replace the version
     number before writing the file back to disk.
 
+This is a comprehensive list (but not all variations) of examples where the following versions
+will be matched and replaced by the new version:
+
+.. code-block::
+
+    # Common variable declaration formats
+    version='1.2.3'
+    version = "1.2.3"
+    release = "v1.2.3"     # if tag_format is set
+
+    # YAML
+    version: 1.2.3
+
+    # JSON
+    "version": "1.2.3"
+
+    # NPM & GitHub Actions YAML
+    version@1.2.3
+    version@v1.2.3        # if tag_format is set
+
+    # Walrus Operator
+    version := "1.2.3"
+
+    # Excessive whitespace
+    version        =    '1.2.3'
+
+    # Mixed Quotes
+    "version" = '1.2.3'
+
+    # Custom Tag Format with tag_format set (monorepos)
+    __release__ = "module-v1.2.3"
+
+.. important::
+    The Regular Expression expects a version value to exist in the file to be replaced.
+    It cannot be an empty string or a non-semver compliant string. If this is the very
+    first time you are using PSR, we recommend you set the version to ``0.0.0``.
+
+    This may become more flexible in the future with resolution of issue `#941`_.
+
+.. _#941: https://github.com/python-semantic-release/python-semantic-release/issues/941
+
 .. warning::
     If the file (ex. JSON) you are replacing has two of the same variable name in it,
     this pattern match will not be able to differentiate between the two and will replace
     both. This is a limitation of the pattern matching and not a bug.
 
 **Default:** ``[]``
+
+.. _SemVer: https://semver.org/

{python_semantic_release-9.19.1 → python_semantic_release-9.21.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-semantic-release"
-version = "9.19.1"
+version = "9.21.0"
 description = "Automatic Semantic Versioning for Python projects"
 requires-python = ">=3.8"
 license = { text = "MIT" }
@@ -35,9 +35,11 @@ dependencies = [
   "pydantic ~= 2.0",
   "rich ~= 13.0",
   "shellingham ~= 1.5",
+  "Deprecated ~= 1.2",  # Backport of deprecated decorator for python 3.8
 ]
 
 [project.scripts]
+python-semantic-release = "semantic_release.__main__:main"
 semantic-release = "semantic_release.__main__:main"
 psr = "semantic_release.__main__:main"
 
@@ -83,6 +85,7 @@ dev = [
 ]
 mypy = [
   "mypy == 1.15.0",
+  "types-Deprecated ~= 1.2",
   "types-requests ~= 2.32.0",
   "types-pyyaml ~= 6.0",
 ]
@@ -201,6 +204,10 @@ ignore_missing_imports = true
 module = "shellingham"
 ignore_missing_imports = true
 
+[[tool.mypy.overrides]]
+module = "dotty_dict"
+ignore_missing_imports = true
+
 [tool.ruff]
 line-length = 88
 target-version = "py38"

{python_semantic_release-9.19.1 → python_semantic_release-9.21.0/src/python_semantic_release.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-semantic-release
-Version: 9.19.1
+Version: 9.21.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: docs
@@ -63,6 +64,7 @@ Requires-Dist: tox~=4.11; extra == "dev"
 Requires-Dist: ruff==0.6.1; extra == "dev"
 Provides-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"
 

{python_semantic_release-9.19.1 → python_semantic_release-9.21.0}/src/python_semantic_release.egg-info/SOURCES.txt

@@ -98,6 +98,11 @@ src/semantic_release/version/algorithm.py
 src/semantic_release/version/declaration.py
 src/semantic_release/version/translator.py
 src/semantic_release/version/version.py
+src/semantic_release/version/declarations/__init__.py
+src/semantic_release/version/declarations/enum.py
+src/semantic_release/version/declarations/i_version_replacer.py
+src/semantic_release/version/declarations/pattern.py
+src/semantic_release/version/declarations/toml.py
 tests/__init__.py
 tests/conftest.py
 tests/const.py
@@ -196,6 +201,8 @@ tests/unit/semantic_release/hvcs/test_token_auth.py
 tests/unit/semantic_release/hvcs/test_util.py
 tests/unit/semantic_release/version/__init__.py
 tests/unit/semantic_release/version/test_algorithm.py
-tests/unit/semantic_release/version/test_declaration.py
 tests/unit/semantic_release/version/test_translator.py
-tests/unit/semantic_release/version/test_version.py
+tests/unit/semantic_release/version/test_version.py
+tests/unit/semantic_release/version/declarations/__init__.py
+tests/unit/semantic_release/version/declarations/test_pattern_declaration.py
+tests/unit/semantic_release/version/declarations/test_toml_declaration.py

{python_semantic_release-9.19.1 → python_semantic_release-9.21.0}/src/python_semantic_release.egg-info/entry_points.txt

@@ -1,3 +1,4 @@
 [console_scripts]
 psr = semantic_release.__main__:main
+python-semantic-release = semantic_release.__main__:main
 semantic-release = semantic_release.__main__:main

{python_semantic_release-9.19.1 → python_semantic_release-9.21.0}/src/python_semantic_release.egg-info/requires.txt

@@ -10,6 +10,7 @@ importlib-resources~=6.0
 pydantic~=2.0
 rich~=13.0
 shellingham~=1.5
+Deprecated~=1.2
 
 [build]
 build~=1.2
@@ -27,6 +28,7 @@ furo~=2024.1
 
 [mypy]
 mypy==1.15.0
+types-Deprecated~=1.2
 types-requests~=2.32.0
 types-pyyaml~=6.0
 

{python_semantic_release-9.19.1 → python_semantic_release-9.21.0}/src/semantic_release/__init__.py

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

{python_semantic_release-9.19.1 → python_semantic_release-9.21.0}/src/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(