diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 28a401e2..11b08e06 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -21,7 +21,7 @@ This section covers the changes between major version 2 and version 3. Version 3.0.0 ============= -:Released: 2023-03-19 +:Released: 2023-04-02 :Maintainer: Tom Schraitle @@ -95,6 +95,14 @@ Deprecations didn't cast many votes, the majority agreed to remove support for Python 3.6. +* :pr:`402`: Keep :func:`semver.compare `. + Although it breaks consistency with module level functions, it seems it's + a much needed/used function. It's still unclear if we should deprecate + this function or not (that's why we use :py:exc:`PendingDeprecationWarning`). + + As we don't have a uniform initializer yet, this function stays in the + :file:`_deprecated.py` file for the time being until we find a better solution. See :gh:`258` for details. + Features -------- diff --git a/docs/api.rst b/docs/api.rst index 279df408..f545ebc5 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -17,6 +17,8 @@ Deprecated Functions in :mod:`semver._deprecated` .. automodule:: semver._deprecated +.. autofunction:: semver._deprecated.compare + .. autofunction:: semver._deprecated.bump_build .. autofunction:: semver._deprecated.bump_major @@ -27,8 +29,6 @@ Deprecated Functions in :mod:`semver._deprecated` .. autofunction:: semver._deprecated.bump_prerelease -.. autofunction:: semver._deprecated.compare - .. autofunction:: semver._deprecated.deprecated .. autofunction:: semver._deprecated.finalize_version diff --git a/docs/changelog-semver2.rst b/docs/changelog-semver2.rst deleted file mode 100644 index dca94413..00000000 --- a/docs/changelog-semver2.rst +++ /dev/null @@ -1,670 +0,0 @@ -################## -Change Log semver2 -################## - -This changelog contains older entries for semver2. - ----- - - -Version 2.13.0 -============== - -:Released: 2020-10-20 -:Maintainer: Tom Schraitle - - -Features --------- - -* :pr:`287`: Document how to create subclass from ``VersionInfo`` - - -Bug Fixes ---------- - -* :pr:`283`: Ensure equal versions have equal hashes. - Version equality means for semver, that ``major``, - ``minor``, ``patch``, and ``prerelease`` parts are - equal in both versions you compare. The ``build`` part - is ignored. - - -Additions ---------- - -n/a - - -Deprecations ------------- - -n/a - - ----- - - -Version 2.12.0 -============== - -:Released: 2020-10-19 -:Maintainer: Tom Schraitle - - -Bug Fixes ---------- - -* :gh:`291` (:pr:`292`): Disallow negative numbers of - ``major``, ``minor``, and ``patch`` for :class:`semver.VersionInfo` - - ----- - - -Version 2.11.0 -============== - -:Released: 2020-10-17 -:Maintainer: Tom Schraitle - - -Bug Fixes ---------- - -* :gh:`276` (:pr:`277`): ``VersionInfo.parse`` should be a class method - Also add authors and update changelog in :gh:`286` -* :gh:`274` (:pr:`275`): Py2 vs. Py3 incompatibility TypeError - - ----- - - -Version 2.10.2 -============== - -:Released: 2020-06-15 -:Maintainer: Tom Schraitle - -Features --------- - -:gh:`268`: Increase coverage - - -Bug Fixes ---------- - -* :gh:`260` (:pr:`261`): Fixed ``__getitem__`` returning None on wrong parts -* :pr:`263`: Doc: Add missing "install" subcommand for openSUSE - - -Deprecations ------------- - -* :gh:`160` (:pr:`264`): - * :func:`semver.max_ver` - * :func:`semver.min_ver` - - ----- - - -Version 2.10.1 -============== - -:Released: 2020-05-13 -:Maintainer: Tom Schraitle - - -Features --------- - -* :pr:`249`: Added release policy and version restriction in documentation to - help our users which would like to stay on the major 2 release. -* :pr:`250`: Simplified installation semver on openSUSE with ``obs://``. -* :pr:`256`: Made docstrings consistent - - - -Bug Fixes ---------- - -* :gh:`251` (:pr:`254`): Fixed return type of ``semver.VersionInfo.next_version`` - to always return a ``VersionInfo`` instance. - - ----- - - - -Version 2.10.0 -============== - -:Released: 2020-05-05 -:Maintainer: Tom Schraitle - -Features --------- - -* :pr:`138`: Added ``__getitem__`` magic method to ``semver.VersionInfo`` class. - Allows to access a version like ``version[1]``. -* :pr:`235`: Improved documentation and shift focus on ``semver.VersionInfo`` instead of advertising - the old and deprecated module-level functions. -* :pr:`230`: Add version information in some functions: - - * Use ``.. versionadded::`` RST directive in docstrings to - make it more visible when something was added - * Minor wording fix in docstrings (versions -> version strings) - - -Bug Fixes ---------- - -* :gh:`224` (:pr:`226`): In ``setup.py``, replaced in class ``clean``, - ``super(CleanCommand, self).run()`` with ``CleanCommand.run(self)`` -* :gh:`244` (:pr:`245`): Allow comparison with ``VersionInfo``, tuple/list, dict, and string. - - -Additions ---------- - -* :pr:`228`: Added better doctest integration - - -Deprecations ------------- -* :gh:`225` (:pr:`229`): Output a DeprecationWarning for the following functions: - - - ``semver.parse`` - - ``semver.parse_version_info`` - - ``semver.format_version`` - - ``semver.bump_{major,minor,patch,prerelease,build}`` - - ``semver.finalize_version`` - - ``semver.replace`` - - ``semver.VersionInfo._asdict`` (use the new, public available - function ``semver.VersionInfo.to_dict()``) - - ``semver.VersionInfo._astuple`` (use the new, public available - function ``semver.VersionInfo.to_tuple()``) - - These deprecated functions will be removed in semver 3. - - ----- - - -Version 2.9.1 -============= -:Released: 2020-02-16 -:Maintainer: Tom Schraitle - -Features --------- - -* :gh:`177` (:pr:`178`): Fixed repository and CI links (moved https://github.com/k-bx/python-semver/ repository to https://github.com/python-semver/python-semver/) -* :pr:`179`: Added note about moving this project to the new python-semver organization on GitHub -* :gh:`187` (:pr:`188`): Added logo for python-semver organization and documentation -* :gh:`191` (:pr:`194`): Created manpage for pysemver -* :gh:`196` (:pr:`197`): Added distribution specific installation instructions -* :gh:`201` (:pr:`202`): Reformatted source code with black -* :gh:`208` (:pr:`209`): Introduce new function :func:`semver.VersionInfo.isvalid` - and extend :command:`pysemver` with :command:`check` subcommand -* :gh:`210` (:pr:`215`): Document how to deal with invalid versions -* :pr:`212`: Improve docstrings according to PEP257 - -Bug Fixes ---------- - -* :gh:`192` (:pr:`193`): Fixed "pysemver" and "pysemver bump" when called without arguments - - ----- - -Version 2.9.0 -============= -:Released: 2019-10-30 -:Maintainer: Sébastien Celles - -Features --------- - -* :gh:`59` (:pr:`164`): Implemented a command line interface -* :gh:`85` (:pr:`147`, :pr:`154`): Improved contribution section -* :gh:`104` (:pr:`125`): Added iterator to :func:`semver.VersionInfo` -* :gh:`112`, :gh:`113`: Added Python 3.7 support -* :pr:`120`: Improved test_immutable function with properties -* :pr:`125`: Created :file:`setup.cfg` for pytest and tox -* :gh:`126` (:pr:`127`): Added target for documentation in :file:`tox.ini` -* :gh:`142` (:pr:`143`): Improved usage section -* :gh:`144` (:pr:`156`): Added :func:`semver.replace` and :func:`semver.VersionInfo.replace` - functions -* :gh:`145` (:pr:`146`): Added posargs in :file:`tox.ini` -* :pr:`157`: Introduce :file:`conftest.py` to improve doctests -* :pr:`165`: Improved code coverage -* :pr:`166`: Reworked :file:`.gitignore` file -* :gh:`167` (:pr:`168`): Introduced global constant :data:`SEMVER_SPEC_VERSION` - -Bug Fixes ---------- - -* :gh:`102`: Fixed comparison between VersionInfo and tuple -* :gh:`103`: Disallow comparison between VersionInfo and string (and int) -* :gh:`121` (:pr:`122`): Use python3 instead of python3.4 in :file:`tox.ini` -* :pr:`123`: Improved :func:`__repr__` and derive class name from :func:`type` -* :gh:`128` (:pr:`129`): Fixed wrong datatypes in docstring for :func:`semver.format_version` -* :gh:`135` (:pr:`140`): Converted prerelease and build to string -* :gh:`136` (:pr:`151`): Added testsuite to tarball -* :gh:`154` (:pr:`155`): Improved README description - -Removals --------- - -* :gh:`111` (:pr:`110`): Dropped Python 3.3 -* :gh:`148` (:pr:`149`): Removed and replaced ``python setup.py test`` - - ----- - -Version 2.8.2 -============= -:Released: 2019-05-19 -:Maintainer: Sébastien Celles - -Skipped, not released. - ----- - -Version 2.8.1 -============= -:Released: 2018-07-09 -:Maintainer: Sébastien Celles - -Features --------- - -* :gh:`40` (:pr:`88`): Added a static parse method to VersionInfo -* :gh:`77` (:pr:`47`): Converted multiple tests into pytest.mark.parametrize -* :gh:`87`, :gh:`94` (:pr:`93`): Removed named tuple inheritance. -* :gh:`89` (:pr:`90`): Added doctests. - -Bug Fixes ---------- - -* :gh:`98` (:pr:`99`): Set prerelease and build to None by default -* :gh:`96` (:pr:`97`): Made VersionInfo immutable - - ----- - -Version 2.8.0 -============= -:Released: 2018-05-16 -:Maintainer: Sébastien Celles - - -Changes -------- - -* :gh:`82` (:pr:`83`): Renamed :file:`test.py` to :file:`test_semver.py` so - py.test can autodiscover test file - -Additions ---------- - -* :gh:`79` (:pr:`81`, :pr:`84`): Defined and improve a release procedure file -* :gh:`72`, :gh:`73` (:pr:`75`): Implemented :func:`__str__` and :func:`__hash__` - -Removals --------- - -* :gh:`76` (:pr:`80`): Removed Python 2.6 compatibility - ----- - - -Version 2.7.9 -============= - -:Released: 2017-09-23 -:Maintainer: Kostiantyn Rybnikov - - -Additions ---------- - -* :gh:`65` (:pr:`66`): Added :func:`semver.finalize_version` function. - - ----- - -Version 2.7.8 -============= - -:Released: 2017-08-25 -:Maintainer: Kostiantyn Rybnikov - -* :gh:`62`: Support custom default names for pre and build - - ----- - -Version 2.7.7 -============= - -:Released: 2017-05-25 -:Maintainer: Kostiantyn Rybnikov - -* :gh:`54` (:pr:`55`): Added comparision between VersionInfo objects -* :pr:`56`: Added support for Python 3.6 - - ----- - -Version 2.7.2 -============= - -:Released: 2016-11-08 -:Maintainer: Kostiantyn Rybnikov - -Additions ---------- - -* Added :func:`semver.parse_version_info` to parse a version string to a - version info tuple. - -Bug Fixes ---------- - -* :gh:`37`: Removed trailing zeros from prelease doesn't allow to - parse 0 pre-release version - -* Refine parsing to conform more strictly to SemVer 2.0.0. - - SemVer 2.0.0 specification §9 forbids leading zero on identifiers in - the prerelease version. - - ----- - -Version 2.6.0 -============= - -:Released: 2016-06-08 -:Maintainer: Kostiantyn Rybnikov - -Removals --------- - -* Remove comparison of build component. - - SemVer 2.0.0 specification recommends that build component is - ignored in comparisons. - - ----- - -Version 2.5.0 -============= - -:Released: 2016-05-25 -:Maintainer: Kostiantyn Rybnikov - -Additions ---------- - -* Support matching 'not equal' with “!=”. - -Changes -------- - -* Made separate builds for tests on Travis CI. - - ----- - -Version 2.4.2 -============= - -:Released: 2016-05-16 -:Maintainer: Kostiantyn Rybnikov - -Changes -------- - -* Migrated README document to reStructuredText format. - -* Used Setuptools for distribution management. - -* Migrated test cases to Py.test. - -* Added configuration for Tox test runner. - - ----- - -Version 2.4.1 -============= - -:Released: 2016-03-04 -:Maintainer: Kostiantyn Rybnikov - -Additions ---------- - -* :gh:`23`: Compared build component of a version. - - ----- - -Version 2.4.0 -============= - -:Released: 2016-02-12 -:Maintainer: Kostiantyn Rybnikov - -Bug Fixes ---------- - -* :gh:`21`: Compared alphanumeric components correctly. - - ----- - -Version 2.3.1 -============= - -:Released: 2016-01-30 -:Maintainer: Kostiantyn Rybnikov - -Additions ---------- - -* Declared granted license name in distribution metadata. - - ----- - -Version 2.3.0 -============= - -:Released: 2016-01-29 -:Maintainer: Kostiantyn Rybnikov - -Additions ---------- - -* Added functions to increment prerelease and build components in a - version. - - ----- - -Version 2.2.1 -============= - -:Released: 2015-08-04 -:Maintainer: Kostiantyn Rybnikov - -Bug Fixes ---------- - -* Corrected comparison when any component includes zero. - - ----- - -Version 2.2.0 -============= - -:Released: 2015-06-21 -:Maintainer: Kostiantyn Rybnikov - -Additions ---------- - -* Add functions to determined minimum and maximum version. - -* Add code examples for recently-added functions. - - ----- - -Version 2.1.2 -============= - -:Released: 2015-05-23 -:Maintainer: Kostiantyn Rybnikov - -Bug Fixes ---------- - -* Restored current README document to distribution manifest. - - ----- - -Version 2.1.1 -============= - -:Released: 2015-05-23 -:Maintainer: Kostiantyn Rybnikov - -Bug Fixes ---------- - -* Removed absent document from distribution manifest. - - ----- - -Version 2.1.0 -============= - -:Released: 2015-05-22 -:Maintainer: Kostiantyn Rybnikov - -Additions ---------- - -* Documented installation instructions. - -* Documented project home page. - -* Added function to format a version string from components. - -* Added functions to increment specific components in a version. - -Changes -------- - -* Migrated README document to Markdown format. - -Bug Fixes ---------- - -* Corrected code examples in README document. - - ----- - -Version 2.0.2 -============= - -:Released: 2015-04-14 -:Maintainer: Konstantine Rybnikov - -Additions ---------- - -* Added configuration for Travis continuous integration. - -* Explicitly declared supported Python versions. - - ----- - -Version 2.0.1 -============= - -:Released: 2014-09-24 -:Maintainer: Konstantine Rybnikov - -Bug Fixes ---------- - -* :gh:`9`: Fixed comparison of equal version strings. - - ----- - -Version 2.0.0 -============= - -:Released: 2014-05-24 -:Maintainer: Konstantine Rybnikov - -Additions ---------- - -* Grant license in this code base under BSD 3-clause license terms. - -Changes -------- - -* Update parser to SemVer standard 2.0.0. - -* Ignore build component for comparison. - - ----- - -Version 0.0.2 -============= - -:Released: 2012-05-10 -:Maintainer: Konstantine Rybnikov - -Changes -------- - -* Use standard library Distutils for distribution management. - - ----- - -Version 0.0.1 -============= - -:Released: 2012-04-28 -:Maintainer: Konstantine Rybnikov - -* Initial release. - - -.. - Local variables: - coding: utf-8 - mode: text - mode: rst - End: - vim: fileencoding=utf-8 filetype=rst : diff --git a/docs/conf.py b/docs/conf.py index 9edfda4d..eab3248d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -122,6 +122,17 @@ def find_version(*file_paths): "pr": ("https://github.com/python-semver/python-semver/pull/%s", "PR #%s"), } +# Link to other projects’ documentation +# See https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html +intersphinx_mapping = { + # Download it from the root with: + # wget -O docs/python-objects.inv https://docs.python.org/3/objects.inv + "python": ("https://docs.python.org/3", (None, "inventories/python-objects.inv")), +} +# Avoid side-effects (namely that documentations local references can +# suddenly resolve to an external location.) +intersphinx_disabled_reftypes = ["*"] + # -- Options for HTML output ---------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for diff --git a/docs/index.rst b/docs/index.rst index 4c9ccff7..1054c225 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -32,7 +32,7 @@ Semver |version| -- Semantic Versioning :hidden: changelog - changelog-semver2 + changelog-semver3-devel Indices and Tables diff --git a/docs/inventories/python-objects.inv b/docs/inventories/python-objects.inv new file mode 100644 index 00000000..6f01e284 Binary files /dev/null and b/docs/inventories/python-objects.inv differ diff --git a/docs/usage/compare-versions.rst b/docs/usage/compare-versions.rst index cf55eae3..ddd03b68 100644 --- a/docs/usage/compare-versions.rst +++ b/docs/usage/compare-versions.rst @@ -5,7 +5,7 @@ To compare two versions depends on your type: * **Two strings** - Use :func:`semver.compare`:: + Use :func:`semver.compare `:: >>> semver.compare("1.0.0", "2.0.0") -1 diff --git a/docs/usage/semver-version.rst b/docs/usage/semver-version.rst index e8cc92b3..b7d5ed9e 100644 --- a/docs/usage/semver-version.rst +++ b/docs/usage/semver-version.rst @@ -4,4 +4,4 @@ Getting the Version of semver To know the version of semver itself, use the following construct:: >>> semver.__version__ - '3.0.0-rc.1' + '3.0.0' diff --git a/src/semver/__about__.py b/src/semver/__about__.py index dd671d02..89c6412e 100644 --- a/src/semver/__about__.py +++ b/src/semver/__about__.py @@ -16,7 +16,7 @@ """ #: Semver version -__version__ = "3.0.0-rc.1" +__version__ = "3.0.0" #: Original semver author __author__ = "Kostiantyn Rybnikov" diff --git a/src/semver/__init__.py b/src/semver/__init__.py index c6726f2e..433e5d5d 100644 --- a/src/semver/__init__.py +++ b/src/semver/__init__.py @@ -9,8 +9,8 @@ bump_major, bump_minor, bump_patch, - bump_prerelease, compare, + bump_prerelease, finalize_version, format_version, match, diff --git a/src/semver/_deprecated.py b/src/semver/_deprecated.py index 8dfb1933..efbdf439 100644 --- a/src/semver/_deprecated.py +++ b/src/semver/_deprecated.py @@ -11,13 +11,15 @@ from . import cli from .version import Version -from ._types import Decorator, F, String +from ._types import Decorator, F def deprecated( func: Optional[F] = None, + *, replace: Optional[str] = None, version: Optional[str] = None, + remove: Optional[str] = None, category: Type[Warning] = DeprecationWarning, ) -> Decorator: """ @@ -34,7 +36,13 @@ def deprecated( """ if func is None: - return partial(deprecated, replace=replace, version=version, category=category) + return partial( + deprecated, + replace=replace, + version=version, + remove=remove, + category=category, + ) @wraps(func) def wrapper(*args, **kwargs) -> Callable[..., F]: @@ -42,7 +50,12 @@ def wrapper(*args, **kwargs) -> Callable[..., F]: if version: msg_list.append("Deprecated since version {v}. ") - msg_list.append("This function will be removed in semver 3.") + + if not remove: + msg_list.append("This function will be removed in semver 3.") + else: + msg_list.append(str(remove)) + if replace: msg_list.append("Use {r!r} instead.") else: @@ -69,6 +82,36 @@ def wrapper(*args, **kwargs) -> Callable[..., F]: return wrapper +@deprecated( + version="3.0.0", + remove="Still under investigation, see #258.", + category=PendingDeprecationWarning, +) +def compare(ver1: str, ver2: str) -> int: + """ + Compare two versions strings. + + .. deprecated:: 3.0.0 + The situation of this function is unclear and it might + disappear in the future. + If possible, use :meth:`semver.version.Version.compare`. + See :gh:`258` for details. + + :param ver1: first version string + :param ver2: second version string + :return: The return value is negative if ver1 < ver2, + zero if ver1 == ver2 and strictly positive if ver1 > ver2 + + >>> semver.compare("1.0.0", "2.0.0") + -1 + >>> semver.compare("2.0.0", "1.0.0") + 1 + >>> semver.compare("2.0.0", "2.0.0") + 0 + """ + return Version.parse(ver1).compare(ver2) + + @deprecated(version="2.10.0") def parse(version): """ @@ -126,28 +169,6 @@ def parse_version_info(version): return Version.parse(version) -@deprecated(version="2.10.0") -def compare(ver1, ver2): - """ - Compare two versions strings. - - :param ver1: version string 1 - :param ver2: version string 2 - :return: The return value is negative if ver1 < ver2, - zero if ver1 == ver2 and strictly positive if ver1 > ver2 - :rtype: int - - >>> semver.compare("1.0.0", "2.0.0") - -1 - >>> semver.compare("2.0.0", "1.0.0") - 1 - >>> semver.compare("2.0.0", "2.0.0") - 0 - """ - v1 = Version.parse(ver1) - return v1.compare(ver2) - - @deprecated(version="2.10.0") def match(version, match_expr): """ @@ -192,15 +213,7 @@ def max_ver(ver1, ver2): >>> semver.max_ver("1.0.0", "2.0.0") '2.0.0' """ - if isinstance(ver1, String.__args__): # type: ignore - ver1 = Version.parse(ver1) - elif not isinstance(ver1, Version): - raise TypeError() - cmp_res = ver1.compare(ver2) - if cmp_res >= 0: - return str(ver1) - else: - return ver2 + return str(max(ver1, ver2, key=Version.parse)) @deprecated(replace="min", version="2.10.2") @@ -219,12 +232,7 @@ def min_ver(ver1, ver2): >>> semver.min_ver("1.0.0", "2.0.0") '1.0.0' """ - ver1 = Version.parse(ver1) - cmp_res = ver1.compare(ver2) - if cmp_res <= 0: - return str(ver1) - else: - return ver2 + return str(min(ver1, ver2, key=Version.parse)) @deprecated(replace="str(versionobject)", version="2.10.0") @@ -387,10 +395,16 @@ def replace(version, **parts): # CLI -cmd_bump = deprecated(cli.cmd_bump, "semver.cli.cmd_bump", "3.0.0") -cmd_check = deprecated(cli.cmd_check, "semver.cli.cmd_check", "3.0.0") -cmd_compare = deprecated(cli.cmd_compare, "semver.cli.cmd_compare", "3.0.0") -cmd_nextver = deprecated(cli.cmd_nextver, "semver.cli.cmd_nextver", "3.0.0") -createparser = deprecated(cli.createparser, "semver.cli.createparser", "3.0.0") -process = deprecated(cli.process, "semver.cli.process", "3.0.0") -main = deprecated(cli.main, "semver.cli.main", "3.0.0") +cmd_bump = deprecated(cli.cmd_bump, replace="semver.cli.cmd_bump", version="3.0.0") +cmd_check = deprecated(cli.cmd_check, replace="semver.cli.cmd_check", version="3.0.0") +cmd_compare = deprecated( + cli.cmd_compare, replace="semver.cli.cmd_compare", version="3.0.0" +) +cmd_nextver = deprecated( + cli.cmd_nextver, replace="semver.cli.cmd_nextver", version="3.0.0" +) +createparser = deprecated( + cli.createparser, replace="semver.cli.createparser", version="3.0.0" +) +process = deprecated(cli.process, replace="semver.cli.process", version="3.0.0") +main = deprecated(cli.main, replace="semver.cli.main", version="3.0.0") diff --git a/tests/test_deprecated_functions.py b/tests/test_deprecated_functions.py index 0b5123cc..88862689 100644 --- a/tests/test_deprecated_functions.py +++ b/tests/test_deprecated_functions.py @@ -5,7 +5,6 @@ from semver import ( parse, parse_version_info, - compare, match, max_ver, min_ver, @@ -36,7 +35,6 @@ (bump_minor, ("1.2.3",), {}), (bump_patch, ("1.2.3",), {}), (bump_prerelease, ("1.2.3",), {}), - (compare, ("1.2.1", "1.2.2"), {}), (format_version, (3, 4, 5), {}), (finalize_version, ("1.2.3-rc.5",), {}), (match, ("1.0.0", ">=1.0.0"), {}),