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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-semantic-release
-Version: 9.5.0
+Version: 9.7.0
 Summary: Automatic Semantic Versioning for Python projects
 Author-email: Rolf Erik Lekang <me@rolflekang.com>
 License: MIT
@@ -53,9 +53,9 @@ Requires-Dist: types-pytest-lazy-fixture~=0.6.3; extra == "test"
 Provides-Extra: dev
 Requires-Dist: pre-commit~=3.5; extra == "dev"
 Requires-Dist: tox~=4.11; extra == "dev"
-Requires-Dist: ruff==0.4.1; extra == "dev"
+Requires-Dist: ruff==0.4.2; extra == "dev"
 Provides-Extra: mypy
-Requires-Dist: mypy==1.9.0; extra == "mypy"
+Requires-Dist: mypy==1.10.0; extra == "mypy"
 Requires-Dist: types-requests~=2.31.0; extra == "mypy"
 
 Python Semantic Release

{python_semantic_release-9.5.0 → python_semantic_release-9.7.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.7.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.7.0}/docs/configuration.rst

@@ -141,10 +141,34 @@ This setting is discussed in more detail at :ref:`multibranch-releases`
 
 .. _config-build-command:
 
-``build_command (Optional[str])``
-"""""""""""""""""""""""""""""""""
-
-Command to use when building the current project during :ref:`cmd-version`
+``build_command``
+"""""""""""""""""
+
+**Type:** ``Optional[str]``
+
+Command to use to build the current project during :ref:`cmd-version`.
+
+Python Semantic Release will execute the build command in the OS default
+shell with a subset of environment variables. PSR provides the variable
+``NEW_VERSION`` in the environment with the value of the next determined
+version. The following table summarizes all the environment variables that
+are passed on to the ``build_command`` runtime if they exist in the parent
+process.
+
+========================  ======================================================================
+Variable Name             Description
+========================  ======================================================================
+CI                        Pass-through ``true`` if exists in process env, unset otherwise
+BITBUCKET_CI              ``true`` if Bitbucket CI variables exist in env, unset otherwise
+GITHUB_ACTIONS            Pass-through ``true`` if exists in process env, unset otherwise
+GITEA_ACTIONS             Pass-through ``true`` if exists in process env, unset otherwise
+GITLAB_CI                 Pass-through ``true`` if exists in process env, unset otherwise
+HOME                      Pass-through ``HOME`` of parent process
+NEW_VERSION               Semantically determined next version (ex. ``1.2.3``)
+PATH                      Pass-through ``PATH`` of parent process
+PSR_DOCKER_GITHUB_ACTION  Pass-through ``true`` if exists in process env, unset otherwise
+VIRTUAL_ENV               Pass-through ``VIRTUAL_ENV`` if exists in process env, unset otherwise
+========================  ======================================================================
 
 **Default:** ``None`` (not specified)
 

{python_semantic_release-9.5.0 → python_semantic_release-9.7.0}/docs/github-action.rst

@@ -106,8 +106,8 @@ defaults as their corresponding command line option.
 In general, the input for an action corresponding to a command line option has the same
 name, with dashes (``-``) replaced by underscores.
 
-The command line arguments ``--patch``, ``--minor`` and ``--major`` are mutually
-exclusive, and are supplied via the ``force`` input.
+The command line arguments ``--prerelease``, ``--patch``, ``--minor`` and ``--major``
+are mutually exclusive, and are supplied via the ``force`` input.
 
 Flags, which require either ``--<option>`` or ``--no-<option>`` to be passed on the
 command-line, should be specified using the option name (with dashes replaced by
@@ -115,6 +115,9 @@ underscores), and set to the value ``"true"`` to supply ``--<option>`` on the
 command-line, and ``"false"`` to specify ``--no-<option>``.
 Any other values are not accepted.
 
+The flag ``--as-prerelease`` is uniquely provided as just the ``prerelease`` flag value.
+This is for compatibility reasons.
+
 For command line options requiring a value, set the input to the required value.
 
 For example, to specify ``--patch --no-push --build-metadata abc123``, you should

{python_semantic_release-9.5.0 → python_semantic_release-9.7.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.7.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-semantic-release"
-version = "9.5.0"
+version = "9.7.0"
 description = "Automatic Semantic Versioning for Python projects"
 requires-python = ">=3.8"
 license = { text = "MIT" }
@@ -71,10 +71,10 @@ test = [
 dev = [
   "pre-commit ~= 3.5",
   "tox ~= 4.11",
-  "ruff == 0.4.1"
+  "ruff == 0.4.2"
 ]
 mypy = [
-  "mypy == 1.9.0",
+  "mypy == 1.10.0",
   "types-requests ~= 2.31.0"
 ]
 
@@ -83,18 +83,21 @@ env = [
   "PYTHONHASHSEED = 123456"
 ]
 addopts = [
+  # TO DEBUG in single process, swap auto to 0
   "-nauto",
+  # "-n0",
   "-ra",
   "--diff-symbols",
   "--cache-clear",
-  "--cov=semantic_release",
-  "--cov-context=test",
-  "--cov-report",
-  "html:coverage-html",
-  "--cov-report",
-  "term",
+  # No default coverage - causes problems with debuggers
+  # "--cov=semantic_release",
+  # "--cov-context=test",
+  # "--cov-report=html:coverage-html",
+  # "--cov-report=term-missing",
+]
+testpaths = [
+  "tests"
 ]
-python_files = ["tests/test_*.py", "tests/**/test_*.py"]
 
 [tool.coverage.html]
 show_contexts = true

{python_semantic_release-9.5.0 → python_semantic_release-9.7.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.7.0
 Summary: Automatic Semantic Versioning for Python projects
 Author-email: Rolf Erik Lekang <me@rolflekang.com>
 License: MIT
@@ -53,9 +53,9 @@ Requires-Dist: types-pytest-lazy-fixture~=0.6.3; extra == "test"
 Provides-Extra: dev
 Requires-Dist: pre-commit~=3.5; extra == "dev"
 Requires-Dist: tox~=4.11; extra == "dev"
-Requires-Dist: ruff==0.4.1; extra == "dev"
+Requires-Dist: ruff==0.4.2; extra == "dev"
 Provides-Extra: mypy
-Requires-Dist: mypy==1.9.0; extra == "mypy"
+Requires-Dist: mypy==1.10.0; extra == "mypy"
 Requires-Dist: types-requests~=2.31.0; extra == "mypy"
 
 Python Semantic Release

{python_semantic_release-9.5.0 → python_semantic_release-9.7.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.7.0}/python_semantic_release.egg-info/requires.txt

@@ -14,7 +14,7 @@ shellingham~=1.5
 [dev]
 pre-commit~=3.5
 tox~=4.11
-ruff==0.4.1
+ruff==0.4.2
 
 [docs]
 Sphinx~=6.0
@@ -23,7 +23,7 @@ sphinx-autobuild==2024.2.4
 furo~=2024.1
 
 [mypy]
-mypy==1.9.0
+mypy==1.10.0
 types-requests~=2.31.0
 
 [test]

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

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

{python_semantic_release-9.5.0 → python_semantic_release-9.7.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.7.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.7.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 "