python-semantic-release 9.5.0__tar.gz → 9.6.0__tar.gz

{python_semantic_release-9.5.0/python_semantic_release.egg-info → python_semantic_release-9.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-semantic-release
-Version: 9.5.0
+Version: 9.6.0
 Summary: Automatic Semantic Versioning for Python projects
 Author-email: Rolf Erik Lekang <me@rolflekang.com>
 License: MIT

{python_semantic_release-9.5.0 → python_semantic_release-9.6.0}/docs/changelog_templates.rst

@@ -144,8 +144,8 @@ project.
 
 .. _changelog-templates-template-rendering-template-context:
 
-Template Context:
-^^^^^^^^^^^^^^^^^
+Template Context
+^^^^^^^^^^^^^^^^
 
 Alongside the rendering of a directory tree, Python Semantic Release makes information
 about the history of the project available within the templating environment in order
@@ -156,19 +156,57 @@ Python terms, ``context`` is a `dataclass`_ with the following attributes:
 
 * ``repo_name: str``: the name of the current repository parsed from the Git url.
 * ``repo_owner: str``: the owner of the current repository parsed from the Git url.
+* ``hvcs_type: str``: the name of the VCS server type currently configured.
 * ``history: ReleaseHistory``: a :py:class:`semantic_release.changelog.ReleaseHistory` instance.
   (See :ref:`changelog-templates-template-rendering-template-context-release-history`)
 * ``filters: Tuple[Callable[..., Any], ...]``: a tuple of filters for the template environment.
   These are added to the environment's ``filters``, and therefore there should be no need to
   access these from the ``context`` object inside the template.
 
-Currently, two filters are defined:
+The filters provided vary based on the VCS configured and available features:
+
+* ``create_server_url: Callable[[str, str | None, str | None, str | None], str]``: when given
+  a path, prepend the configured vcs server host and url scheme.  Optionally you can provide,
+  a auth string, a query string or a url fragment to be normalized into the resulting url.
+  Parameter order is as described above respectively.
+
+* ``create_repo_url: Callable[[str, str | None, str | None], str]``: when given a repository
+  path, prepend the configured vcs server host, and repo namespace.  Optionally you can provide,
+  an additional query string and/or a url fragment to also put in the url. Parameter order is
+  as described above respectively. This is similar to ``create_server_url`` but includes the repo
+  namespace and owner automatically.
 
-* ``pull_request_url: Callable[[str], str]``: given a pull request number, return a URL
-  to the pull request in the remote.
 * ``commit_hash_url: Callable[[str], str]``: given a commit hash, return a URL to the
   commit in the remote.
 
+* ``compare_url: Callable[[str, str], str]``: given a starting git reference and a ending git
+  reference create a comparison url between the two references that can be opened on the remote
+
+* ``issue_url: Callable[[str | int], str]``: given an issue number, return a URL to the issue
+  on the remote vcs.
+
+* ``merge_request_url: Callable[[str | int], str]``: given a merge request number, return a URL
+  to the merge request in the remote. This is an alias to the ``pull_request_url`` but only
+  available for the VCS that uses the merge request terminology.
+
+* ``pull_request_url: Callable[[str | int], str]``: given a pull request number, return a URL
+  to the pull request in the remote. For remote vcs' that use merge request terminology, this
+  filter is an alias to the ``merge_request_url`` filter function.
+
+Availability of the documented filters can be found in the table below:
+
+======================  =========  =====  ======  ======
+**filter - hvcs_type**  bitbucket  gitea  github  gitlab
+======================  =========  =====  ======  ======
+create_server_url          ✅       ✅      ✅      ✅
+create_repo_url            ✅       ✅      ✅      ✅
+commit_hash_url            ✅       ✅      ✅      ✅
+compare_url                ✅       ❌      ✅      ✅
+issue_url                  ❌       ✅      ✅      ✅
+merge_request_url          ❌       ❌      ❌      ✅
+pull_request_url           ✅       ✅      ✅      ✅
+======================  =========  =====  ======  ======
+
 .. seealso::
    * `Filters <https://jinja.palletsprojects.com/en/3.1.x/templates/#filters>`_
 

{python_semantic_release-9.5.0 → python_semantic_release-9.6.0}/docs/commands.rst

@@ -173,39 +173,110 @@ number (``1.0.0``).
 
 .. _cmd-version-option-force-level:
 
-``--major/--minor/--patch``
-***************************
+``--major/--minor/--patch/--prerelease``
+****************************************
 
-Force the next version to increment the major, minor or patch digit, respectively.
-These flags are optional but mutually exclusive, so only one may be supplied, or none at all.
-Using these flags overrides the usual calculation for the next version; this can be useful, say,
-when a project wants to release its initial 1.0.0 version.
+Force the next version to increment the major, minor or patch digits, or the prerelease revision,
+respectively. These flags are optional but mutually exclusive, so only one may be supplied, or
+none at all. Using these flags overrides the usual calculation for the next version; this can
+be useful, say, when a project wants to release its initial 1.0.0 version.
 
 .. warning::
-    Using these flags will override the value of prerelease, **regardless of your configuration or the
-    current version**. To produce a prerelease with the appropriate digit incremented you should also
-    supply the :ref:`cmd-version-option-prerelease` flag. If you do not, using these flags will force
+
+    Using these flags will override the configured value of ``prerelease`` (configured
+    in your :ref:`Release Group<multibranch-releases-configuring>`),
+    **regardless of your configuration or the current version**.
+
+    To produce a prerelease with the appropriate digit incremented you should also
+    supply the :ref:`cmd-version-option-as-prerelease` flag. If you do not, using these flags will force
     a full (non-prerelease) version to be created.
 
+For example, suppose your project's current version is ``0.2.1-rc.1``. The following
+shows how these options can be combined with ``--as-prerelease`` to force different
+versions:
+
+.. code-block:: bash
+
+   semantic-release version --prerelease --print
+   # 0.2.1-rc.2
+
+   semantic-release version --patch --print
+   # 0.2.2
+
+   semantic-release version --minor --print
+   # 0.3.0
+
+   semantic-release version --major --print
+   # 1.0.0
+
+   semantic-release version --minor --as-prerelease --print
+   # 0.3.0-rc.1
+
+   semantic-release version --prerelease --as-prerelease --print
+   # 0.2.1-rc.2
+
 These options are forceful overrides, but there is no action required for subsequent releases
 performed using the usual calculation algorithm.
 
+Supplying ``--prerelease`` will cause Python Semantic Release to scan your project history
+for any previous prereleases with the same major, minor and patch versions as the latest
+version and the same :ref:`prerelease token<cmd-version-option-prerelease-token>` as the
+one passed by command-line or configuration. If one is not found, ``--prerelease`` will
+produce the next version according to the following format:
+
+.. code-block:: python
+
+    f"{latest_version.major}.{latest_version.minor}.{latest_version.patch}-{prerelease_token}.1"
+
+However, if Python Semantic Release identifies a previous *prerelease* version with the same
+major, minor and patch digits as the latest version, *and* the same prerelease token as the
+one supplied by command-line or configuration, then Python Semantic Release will increment
+the revision found on that previous prerelease version in its new version.
+
+For example, if ``"0.2.1-rc.1"`` and already exists as a previous version, and the latest version
+is ``"0.2.1"``, invoking the following command will produce ``"0.2.1-rc.2"``:
+
+.. code-block:: bash
+
+   semantic-release version --prerelease --prerelease-token "rc" --print
+
+.. warning::
+
+   This is true irrespective of the branch from which ``"0.2.1-rc.1"`` was released from.
+   The check for previous prereleases "leading up to" this normal version is intended to
+   help prevent collisions in git tags to an extent, but isn't foolproof. As the example
+   shows it is possible to release a prerelease for a normal version that's already been
+   released when using this flag, which would in turn be ignored by tools selecting
+   versions by `SemVer precedence rules`_.
+
+
+.. _SemVer precedence rules: https://semver.org/#spec-item-11
+
+
 .. seealso::
     - :ref:`configuration`
     - :ref:`config-branches`
 
-.. _cmd-version-option-prerelease:
+.. _cmd-version-option-as-prerelease:
 
-``--prerelease``
-****************
+``--as-prerelease``
+*******************
 
-Force the next version to be a prerelease. As with :ref:`cmd-version-option-force-level`, this option
+After performing the normal calculation of the next version, convert the resulting next version
+to a prerelease before applying it. As with :ref:`cmd-version-option-force-level`, this option
 is a forceful override, but no action is required to resume calculating versions as normal on the
-subsequent releases.
+subsequent releases. The main distinction between ``--prerelease`` and ``--as-prerelease`` is that
+the latter will not *force* a new version if one would not have been released without supplying
+the flag.
+
+This can be useful when making a single prerelease on a branch that would typically release
+normal versions.
 
 If not specified in :ref:`cmd-version-option-prerelease-token`, the prerelease token is idenitified using the
 :ref:`Multibranch Release Configuration <multibranch-releases-configuring>`
 
+See the examples alongside :ref:`cmd-version-option-force-level` for how to use this flag.
+
 .. _cmd-version-option-prerelease-token:
 
 ``--prerelease-token [VALUE]``

{python_semantic_release-9.5.0 → python_semantic_release-9.6.0}/docs/multibranch_releases.rst

@@ -163,5 +163,5 @@ This would lead to versions such as ``1.1.1+main.20221127`` or ``2.0.0-rc.4+2.x.
 
 .. note::
    Remember that is always possible to override the release rules configured by using
-   the :ref:`cmd-version-option-force-level` and :ref:`cmd-version-option-prerelease`
+   the :ref:`cmd-version-option-force-level` and :ref:`cmd-version-option-as-prerelease`
    flags.

{python_semantic_release-9.5.0 → python_semantic_release-9.6.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-semantic-release"
-version = "9.5.0"
+version = "9.6.0"
 description = "Automatic Semantic Versioning for Python projects"
 requires-python = ">=3.8"
 license = { text = "MIT" }

{python_semantic_release-9.5.0 → python_semantic_release-9.6.0/python_semantic_release.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-semantic-release
-Version: 9.5.0
+Version: 9.6.0
 Summary: Automatic Semantic Versioning for Python projects
 Author-email: Rolf Erik Lekang <me@rolflekang.com>
 License: MIT

{python_semantic_release-9.5.0 → python_semantic_release-9.6.0}/python_semantic_release.egg-info/SOURCES.txt

@@ -71,6 +71,7 @@ semantic_release/hvcs/bitbucket.py
 semantic_release/hvcs/gitea.py
 semantic_release/hvcs/github.py
 semantic_release/hvcs/gitlab.py
+semantic_release/hvcs/remote_hvcs_base.py
 semantic_release/hvcs/token_auth.py
 semantic_release/hvcs/util.py
 semantic_release/version/__init__.py
@@ -113,6 +114,7 @@ tests/unit/__init__.py
 tests/unit/semantic_release/__init__.py
 tests/unit/semantic_release/test_helpers.py
 tests/unit/semantic_release/changelog/__init__.py
+tests/unit/semantic_release/changelog/test_changelog_context.py
 tests/unit/semantic_release/changelog/test_default_changelog.py
 tests/unit/semantic_release/changelog/test_release_notes.py
 tests/unit/semantic_release/changelog/test_template.py
@@ -123,12 +125,11 @@ tests/unit/semantic_release/cli/test_masking_filter.py
 tests/unit/semantic_release/cli/test_util.py
 tests/unit/semantic_release/cli/test_version.py
 tests/unit/semantic_release/commit_parser/__init__.py
-tests/unit/semantic_release/commit_parser/helper.py
 tests/unit/semantic_release/commit_parser/test_angular.py
 tests/unit/semantic_release/commit_parser/test_emoji.py
+tests/unit/semantic_release/commit_parser/test_parsed_commit.py
 tests/unit/semantic_release/commit_parser/test_scipy.py
 tests/unit/semantic_release/commit_parser/test_tag.py
-tests/unit/semantic_release/commit_parser/test_token.py
 tests/unit/semantic_release/commit_parser/test_util.py
 tests/unit/semantic_release/hvcs/__init__.py
 tests/unit/semantic_release/hvcs/test__base.py

{python_semantic_release-9.5.0 → python_semantic_release-9.6.0}/semantic_release/__init__.py

@@ -24,7 +24,7 @@ from semantic_release.version import (
     tags_and_versions,
 )
 
-__version__ = "9.5.0"
+__version__ = "9.6.0"
 
 
 def setup_hook(argv: list[str]) -> None:

{python_semantic_release-9.5.0 → python_semantic_release-9.6.0}/semantic_release/changelog/context.py

@@ -14,6 +14,7 @@ if TYPE_CHECKING:
 class ChangelogContext:
     repo_name: str
     repo_owner: str
+    hvcs_type: str
     history: ReleaseHistory
     filters: tuple[Callable[..., Any], ...] = ()
 
@@ -31,5 +32,6 @@ def make_changelog_context(
         repo_name=hvcs_client.repo_name,
         repo_owner=hvcs_client.owner,
         history=release_history,
-        filters=(hvcs_client.pull_request_url, hvcs_client.commit_hash_url),
+        hvcs_type=hvcs_client.__class__.__name__.lower(),
+        filters=(*hvcs_client.get_changelog_context_filters(),),
     )

{python_semantic_release-9.5.0 → python_semantic_release-9.6.0}/semantic_release/cli/commands/changelog.py

@@ -14,6 +14,7 @@ from semantic_release.cli.common import (
     render_release_notes,
 )
 from semantic_release.cli.util import noop_report
+from semantic_release.hvcs.remote_hvcs_base import RemoteHvcsBase
 
 if TYPE_CHECKING:
     from semantic_release.cli.commands.cli_context import CliContextObj
@@ -79,7 +80,7 @@ def changelog(cli_ctx: CliContextObj, release_tag: str | None = None) -> None:
         else:
             recursive_render(template_dir, environment=env, _root_dir=repo.working_dir)
 
-    if release_tag:
+    if release_tag and isinstance(hvcs_client, RemoteHvcsBase):
         if runtime.global_cli_options.noop:
             noop_report(
                 f"would have posted changelog to the release for tag {release_tag}"

{python_semantic_release-9.5.0 → python_semantic_release-9.6.0}/semantic_release/cli/commands/publish.py

@@ -6,6 +6,7 @@ from typing import TYPE_CHECKING
 import click
 
 from semantic_release.cli.util import noop_report
+from semantic_release.hvcs.remote_hvcs_base import RemoteHvcsBase
 from semantic_release.version import tags_and_versions
 
 if TYPE_CHECKING:
@@ -45,6 +46,13 @@ def publish(cli_ctx: CliContextObj, tag: str = "latest") -> None:
                 f"No tags found with format {translator.tag_format!r}, couldn't "
                 "identify latest version"
             )
+
+    if not isinstance(hvcs_client, RemoteHvcsBase):
+        log.info(
+            "Remote does not support artifact upload. Exiting with no action taken..."
+        )
+        ctx.exit(0)
+
     if runtime.global_cli_options.noop:
         noop_report(
             "would have uploaded files matching any of the globs "

{python_semantic_release-9.5.0 → python_semantic_release-9.6.0}/semantic_release/cli/commands/version.py

@@ -25,6 +25,7 @@ from semantic_release.cli.util import indented, noop_report, rprint
 from semantic_release.const import DEFAULT_SHELL, DEFAULT_VERSION
 from semantic_release.enums import LevelBump
 from semantic_release.errors import UnexpectedResponse
+from semantic_release.hvcs.remote_hvcs_base import RemoteHvcsBase
 from semantic_release.version import Version, next_version, tags_and_versions
 
 log = logging.getLogger(__name__)
@@ -41,7 +42,7 @@ if TYPE_CHECKING:  # pragma: no cover
 
 
 def is_forced_prerelease(
-    force_prerelease: bool, force_level: str | None, prerelease: bool
+    as_prerelease: bool, forced_level_bump: LevelBump | None, prerelease: bool
 ) -> bool:
     """
     Determine if this release is forced to have prerelease on/off.
@@ -50,8 +51,17 @@ def is_forced_prerelease(
     it's False.
     Otherwise (``force_level is None``) use the value of ``prerelease``
     """
-    log.debug(", ".join(f"{k} = {v}" for k, v in locals().items()))
-    return force_prerelease or ((force_level is None) and prerelease)
+    local_vars = list(locals().items())
+    log.debug(
+        "%s: %s",
+        is_forced_prerelease.__name__,
+        ", ".join(f"{k} = {v}" for k, v in local_vars),
+    )
+    return (
+        as_prerelease
+        or forced_level_bump is LevelBump.PRERELEASE_REVISION
+        or ((forced_level_bump is None) and prerelease)
+    )
 
 
 def last_released(
@@ -62,16 +72,41 @@ def last_released(
 
 
 def version_from_forced_level(
-    repo: Repo, level_bump: LevelBump, translator: VersionTranslator
+    repo: Repo, forced_level_bump: LevelBump, translator: VersionTranslator
 ) -> Version:
     ts_and_vs = tags_and_versions(repo.tags, translator)
 
     # If we have no tags, return the default version
     if not ts_and_vs:
-        return Version.parse(DEFAULT_VERSION).bump(level_bump)
+        return Version.parse(DEFAULT_VERSION).bump(forced_level_bump)
 
     _, latest_version = ts_and_vs[0]
-    return latest_version.bump(level_bump)
+    if forced_level_bump is not LevelBump.PRERELEASE_REVISION:
+        return latest_version.bump(forced_level_bump)
+
+    # We need to find the latest version with the prerelease token
+    # we're looking for, and return that version + an increment to
+    # the prerelease revision.
+
+    # NOTE this can probably be cleaned up.
+    # ts_and_vs are in order, so check if we're looking at prereleases
+    # for the same (major, minor, patch) as the latest version.
+    # If we are, we can increment the revision and we're done. If
+    # we don't find a prerelease targeting this version with the same
+    # token as the one we're looking to prerelease, we can use revision 1.
+    for _, version in ts_and_vs:
+        if not (
+            version.major == latest_version.major
+            and version.minor == latest_version.minor
+            and version.patch == latest_version.patch
+        ):
+            break
+        if (
+            version.is_prerelease
+            and version.prerelease_token == translator.prerelease_token
+        ):
+            return version.bump(LevelBump.PRERELEASE_REVISION)
+    return latest_version.to_prerelease(token=translator.prerelease_token, revision=1)
 
 
 def apply_version_to_source_files(
@@ -145,10 +180,10 @@ def shell(cmd: str, *, check: bool = True) -> subprocess.CompletedProcess:
     help="Print the last released version tag and exit",
 )
 @click.option(
-    "--prerelease",
-    "force_prerelease",
+    "--as-prerelease",
+    "as_prerelease",
     is_flag=True,
-    help="Force the next version to be a prerelease",
+    help="Ensure the next version to be released is a prerelease version",
 )
 @click.option(
     "--prerelease-token",
@@ -160,19 +195,25 @@ def shell(cmd: str, *, check: bool = True) -> subprocess.CompletedProcess:
     "--major",
     "force_level",
     flag_value="major",
-    help="force the next version to be a major release",
+    help="Force the next version to be a major release",
 )
 @click.option(
     "--minor",
     "force_level",
     flag_value="minor",
-    help="force the next version to be a minor release",
+    help="Force the next version to be a minor release",
 )
 @click.option(
     "--patch",
     "force_level",
     flag_value="patch",
-    help="force the next version to be a patch release",
+    help="Force the next version to be a patch release",
+)
+@click.option(
+    "--prerelease",
+    "force_level",
+    flag_value="prerelease_revision",
+    help="Force the next version to be a prerelease",
 )
 @click.option(
     "--commit/--no-commit",
@@ -224,7 +265,7 @@ def version(  # noqa: C901
     print_only_tag: bool = False,
     print_last_released: bool = False,
     print_last_released_tag: bool = False,
-    force_prerelease: bool = False,
+    as_prerelease: bool = False,
     prerelease_token: str | None = None,
     force_level: str | None = None,
     commit_changes: bool = True,
@@ -271,9 +312,10 @@ def version(  # noqa: C901
         ctx.exit(0)
 
     parser = runtime.commit_parser
+    forced_level_bump = None if not force_level else LevelBump.from_string(force_level)
     prerelease = is_forced_prerelease(
-        force_prerelease=force_prerelease,
-        force_level=force_level,
+        as_prerelease=as_prerelease,
+        forced_level_bump=forced_level_bump,
         prerelease=runtime.prerelease,
     )
     hvcs_client = runtime.hvcs_client
@@ -306,23 +348,19 @@ def version(  # noqa: C901
         log.info("No vcs release will be created because pushing changes is disabled")
         make_vcs_release &= push_changes
 
-    if force_prerelease:
-        log.warning("Forcing prerelease due to '--prerelease' command-line flag")
-    elif force_level:
+    if forced_level_bump:
         log.warning(
-            "Forcing prerelease=False due to '--%s' command-line flag and no "
-            "'--prerelease' flag",
+            "Forcing a '%s' release due to '--%s' command-line flag",
             force_level,
-        )
-
-    if force_level:
-        level_bump = LevelBump.from_string(force_level)
-        log.warning(
-            "Forcing a %s level bump due to '--force' command-line option", force_level
+            (
+                force_level
+                if forced_level_bump is not LevelBump.PRERELEASE_REVISION
+                else "prerelease"
+            ),
         )
 
         new_version = version_from_forced_level(
-            repo=repo, level_bump=level_bump, translator=translator
+            repo=repo, forced_level_bump=forced_level_bump, translator=translator
         )
 
         # We only turn the forced version into a prerelease if the user has specified
@@ -347,6 +385,17 @@ def version(  # noqa: C901
     if build_metadata:
         new_version.build_metadata = build_metadata
 
+    if as_prerelease:
+        before_conversion, new_version = (
+            new_version,
+            new_version.to_prerelease(token=translator.prerelease_token),
+        )
+        log.info(
+            "Converting %s to %s due to '--as-prerelease' command-line option",
+            before_conversion,
+            new_version,
+        )
+
     gha_output.released = False
     gha_output.version = new_version
     ctx.call_on_close(gha_output.write_if_possible)
@@ -601,7 +650,7 @@ def version(  # noqa: C901
 
     gha_output.released = True
 
-    if make_vcs_release:
+    if make_vcs_release and isinstance(hvcs_client, RemoteHvcsBase):
         if opts.noop:
             noop_report(
                 f"would have created a release for the tag {new_version.as_tag()!r}"
@@ -630,10 +679,11 @@ def version(  # noqa: C901
             noop_report(f"would have uploaded the following assets: {runtime.assets}")
         else:
             try:
-                release_id = hvcs_client.create_or_update_release(
+                hvcs_client.create_release(
                     tag=new_version.as_tag(),
                     release_notes=release_notes,
                     prerelease=new_version.is_prerelease,
+                    assets=assets,
                 )
             except HTTPError as err:
                 log.exception(err)
@@ -654,15 +704,4 @@ def version(  # noqa: C901
                 log.exception(e)
                 ctx.fail(str(e))
 
-            for asset in assets:
-                log.info("Uploading asset %s", asset)
-                try:
-                    hvcs_client.upload_asset(release_id, asset)
-                except HTTPError as err:
-                    log.exception(err)
-                    ctx.fail(str.join("\n", [str(err), "Failed to upload asset!"]))
-                except Exception as e:
-                    log.exception(e)
-                    ctx.fail(str(e))
-
     return str(new_version)