diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml index dc16848..2fe3b5e 100644 --- a/.github/workflows/check.yml +++ b/.github/workflows/check.yml @@ -19,10 +19,10 @@ jobs: TOXENV: ${{ matrix.tox-environment }} steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 - name: Set up Python - uses: actions/setup-python@v2 + uses: actions/setup-python@v3 - name: Install dependencies run: python -m pip install tox diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 67e1fbf..50eee10 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -13,44 +13,30 @@ jobs: fail-fast: false matrix: include: - # Django 1.11: 3.4, 3.7 - - python-version: 2.7 - django-family: 111 - - python-version: 3.4 - django-family: 111 - - python-version: 3.7 - django-family: 111 - - python-version: pypy3 - django-family: 111 - - # Django 2.2: 3.5, 3.7, 3.8 - - python-version: 3.5 - django-family: 22 - - python-version: 3.7 - django-family: 22 - - python-version: 3.8 - django-family: 22 - - python-version: pypy3 - django-family: 22 - - # Django 3.1: Python 3.6, 3.8, 3.9 - - python-version: 3.6 - django-family: 31 - - python-version: 3.8 - django-family: 31 - - python-version: 3.9 - django-family: 31 - - python-version: pypy3 - django-family: 31 + # Django 3.2: Python 3.8, 3.9, 3.10 + - python-version: "3.8" + django-family: 32 + - python-version: "3.9" + django-family: 32 + - python-version: "3.10" + django-family: 32 + + # Django 4.1: Python 3.9, 3.10, 3.11 + - python-version: "3.9" + django-family: 41 + - python-version: "3.10" + django-family: 41 + - python-version: "3.11" + django-family: 41 env: TOXENV: django${{ matrix.django-family }} steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 - name: Set up Python ${{ matrix.python-version }} - uses: actions/setup-python@v2 + uses: actions/setup-python@v3 with: python-version: ${{ matrix.python-version }} diff --git a/ChangeLog b/ChangeLog index c8453e5..2bf2e2c 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,13 +1,38 @@ ChangeLog ========= -2.8.6 (unreleased) +2.10.1 (unreleased) +------------------- + +*Minor:* + + * `112 `_: + Functions returning a new ``Version`` instance reuse the current class, + helping with subclassing. + +*Bugfix:* + + * `141 `_: + Ensure we return a new instance for ``Version.truncate("build")``. + + +2.10.0 (2022-05-26) +------------------- + +*New:* + + * `132 `_: + Ensure sorting a collection of versions is always stable, even with + build metadata. + + +2.9.0 (2022-02-06) ------------------ *New:* - * Add support for Django 3.1 - * Add support for Python 3.7 / 3.8 / 3.9 + * Add support for Django 3.1, 3.2, 4.0 + * Add support for Python 3.7 / 3.8 / 3.9 / 3.10 2.8.5 (2020-04-29) @@ -94,7 +119,7 @@ Backwards compatibility has been kept, but users should adjust their code for th * Allow creation of a ``Version`` directly from parsed components, as keyword arguments (``Version(major=1, minor=2, patch=3)``) * Add ``Version.truncate()`` to build a truncated copy of a ``Version`` - * Add ``NpmSpec(...)``, following strict NPM matching rules (https://docs.npmjs.com/misc/semver) + * Add ``NpmSpec(...)``, following strict NPM matching rules (https://github.com/npm/node-semver#ranges) * Add ``Spec.parse('xxx', syntax='')`` for simpler multi-syntax support * Add ``Version().precedence_key``, for use in ``sort(versions, key=lambda v: v.precedence_key)`` calls. The contents of this attribute is an implementation detail. diff --git a/README.rst b/README.rst index 03d1691..c50163a 100644 --- a/README.rst +++ b/README.rst @@ -1,5 +1,5 @@ -python-semanticversion -====================== +Introduction +============ This small python library provides a few tools to handle `SemVer`_ in Python. It follows strictly the 2.0.0 version of the SemVer scheme. @@ -26,10 +26,10 @@ It follows strictly the 2.0.0 version of the SemVer scheme. Links ----- -- Package on `PyPI`_: http://pypi.python.org/pypi/semantic_version/ +- Package on `PyPI`_: https://pypi.org/project/semantic-version/ - Doc on `ReadTheDocs `_: https://python-semanticversion.readthedocs.io/ - Source on `GitHub `_: http://github.com/rbarrois/python-semanticversion/ -- Build on `Travis CI `_: http://travis-ci.org/rbarrois/python-semanticversion/ +- Build on Github Actions: https://github.com/rbarrois/python-semanticversion/actions - Semantic Version specification: `SemVer`_ @@ -40,7 +40,7 @@ Install the package from `PyPI`_, using pip: .. code-block:: sh - pip install semantic_version + pip install semantic-version Or from GitHub: @@ -57,20 +57,18 @@ Import it in your code: import semantic_version -.. currentmodule:: semantic_version - This module provides classes to handle semantic versions: -- :class:`Version` represents a version number (``0.1.1-alpha+build.2012-05-15``) -- :class:`BaseSpec`-derived classes represent requirement specifications (``>=0.1.1,<0.3.0``): +- ``Version`` represents a version number (``0.1.1-alpha+build.2012-05-15``) +- ``BaseSpec``-derived classes represent requirement specifications (``>=0.1.1,<0.3.0``): - - :class:`SimpleSpec` describes a natural description syntax - - :class:`NpmSpec` is used for NPM-style range descriptions. + - ``SimpleSpec`` describes a natural description syntax + - ``NpmSpec`` is used for NPM-style range descriptions. Versions -------- -Defining a :class:`Version` is quite simple: +Defining a ``Version`` is quite simple: .. code-block:: pycon @@ -90,7 +88,7 @@ Defining a :class:`Version` is quite simple: >>> list(v) [0, 1, 1, [], []] -If the provided version string is invalid, a :exc:`ValueError` will be raised: +If the provided version string is invalid, a ``ValueError`` will be raised: .. code-block:: pycon @@ -104,7 +102,39 @@ If the provided version string is invalid, a :exc:`ValueError` will be raised: ValueError: Invalid version string: '0.1' -Obviously, :class:`Versions ` can be compared: +One may also create a ``Version`` with named components: + +.. code-block:: pycon + + >>> semantic_version.Version(major=0, minor=1, patch=2) + Version('0.1.2') + +In that case, ``major``, ``minor`` and ``patch`` are mandatory, and must be integers. +``prerelease`` and ``build``, if provided, must be tuples of strings: + +.. code-block:: pycon + + >>> semantic_version.Version(major=0, minor=1, patch=2, prerelease=('alpha', '2')) + Version('0.1.2-alpha.2') + + +Some user-supplied input might not match the semantic version scheme. +For such cases, the ``Version.coerce`` method will try to convert any +version-like string into a valid semver version: + +.. code-block:: pycon + + >>> Version.coerce('0') + Version('0.0.0') + >>> Version.coerce('0.1.2.3.4') + Version('0.1.2+3.4') + >>> Version.coerce('0.1.2a3') + Version('0.1.2-a3') + +Working with versions +""""""""""""""""""""" + +Obviously, versions can be compared: .. code-block:: pycon @@ -133,38 +163,31 @@ You can also get a new version that represents a bump in one of the version leve >>> str(new_v) '1.1.2' -It is also possible to check whether a given string is a proper semantic version string: - - -.. code-block:: pycon - - >>> semantic_version.validate('0.1.3') - True - >>> semantic_version.validate('0a2') - False -Finally, one may create a :class:`Version` with named components instead: - -.. code-block:: pycon - - >>> semantic_version.Version(major=0, minor=1, patch=2) - Version('0.1.2') - -In that case, ``major``, ``minor`` and ``patch`` are mandatory, and must be integers. -``prerelease`` and ``build``, if provided, must be tuples of strings: +Requirement specification +------------------------- -.. code-block:: pycon +python-semanticversion provides a couple of ways to describe a range of accepted +versions: - >>> semantic_version.Version(major=0, minor=1, patch=2, prerelease=('alpha', '2')) - Version('0.1.2-alpha.2') +- The ``SimpleSpec`` class provides a simple, easily understood scheme -- + somewhat inspired from PyPI range notations; +- The ``NpmSpec`` class supports the whole NPM range specification scheme: + .. code-block:: pycon -Requirement specification -------------------------- + >>> Version('0.1.2') in NpmSpec('0.1.0-alpha.2 .. 0.2.4') + True + >>> Version('0.1.2') in NpmSpec('>=0.1.1 <0.1.3 || 2.x') + True + >>> Version('2.3.4') in NpmSpec('>=0.1.1 <0.1.3 || 2.x') + True -The :class:`SimpleSpec` object describes a range of accepted versions: +The ``SimpleSpec`` scheme +""""""""""""""""""""""""" +Basic usage is simply a comparator and a base version: .. code-block:: pycon @@ -176,6 +199,12 @@ The :class:`SimpleSpec` object describes a range of accepted versions: >>> s.match(Version('0.1.0')) False +Combining specifications can be expressed as follows: + + .. code-block:: pycon + + >>> SimpleSpec('>=0.1.1,<0.3.0') + Simpler test syntax is also available using the ``in`` keyword: .. code-block:: pycon @@ -189,17 +218,16 @@ Simpler test syntax is also available using the ``in`` keyword: False -Combining specifications can be expressed as follows: - - .. code-block:: pycon +Refer to the full documentation at +https://python-semanticversion.readthedocs.io/en/latest/ for more details on the +``SimpleSpec`` scheme. - >>> SimpleSpec('>=0.1.1,<0.3.0') Using a specification """"""""""""""""""""" -The :func:`SimpleSpec.filter` method filters an iterable of :class:`Version`: +The ``SimpleSpec.filter`` method filters an iterable of ``Version``: .. code-block:: pycon @@ -222,82 +250,6 @@ It is also possible to select the 'best' version from such iterables: Version('0.3.0') -Coercing an arbitrary version string -"""""""""""""""""""""""""""""""""""" - -Some user-supplied input might not match the semantic version scheme. -For such cases, the :meth:`Version.coerce` method will try to convert any -version-like string into a valid semver version: - -.. code-block:: pycon - - >>> Version.coerce('0') - Version('0.0.0') - >>> Version.coerce('0.1.2.3.4') - Version('0.1.2+3.4') - >>> Version.coerce('0.1.2a3') - Version('0.1.2-a3') - - -Including pre-release identifiers in specifications -""""""""""""""""""""""""""""""""""""""""""""""""""" - -When testing a :class:`Version` against a :class:`SimpleSpec`, comparisons are -adjusted for common user expectations; thus, a pre-release version (``1.0.0-alpha``) -will not satisfy the ``==1.0.0`` :class:`SimpleSpec`. - -Pre-release identifiers will only be compared if included in the :class:`BaseSpec` -definition or (for the empty pre-release number) if a single dash is appended -(``1.0.0-``): - - -.. code-block:: pycon - - >>> Version('0.1.0-alpha') in SimpleSpec('<0.1.0') # No pre-release identifier - False - >>> Version('0.1.0-alpha') in SimpleSpec('<0.1.0-') # Include pre-release in checks - True - - -Including build metadata in specifications -"""""""""""""""""""""""""""""""""""""""""" - -Build metadata has no ordering; thus, the only meaningful comparison including -build metadata is equality. - - -.. code-block:: pycon - - >>> Version('1.0.0+build2') in SimpleSpec('<=1.0.0') # Build metadata ignored - True - >>> Version('1.0.0+build1') in SimpleSpec('==1.0.0+build2') # Include build in checks - False - - -NPM-based ranges ----------------- - -The :class:`NpmSpec` class handles NPM-style ranges: - -.. code-block:: pycon - - >>> Version('1.2.3') in NpmSpec('1.2.2 - 1.4') - True - >>> Version('1.2.3') in NpmSpec('<1.x || >=1.2.3') - True - -Refer to https://docs.npmjs.com/misc/semver.html for a detailed description of NPM -range syntax. - - -Using with Django -================= - -The :mod:`semantic_version.django_fields` module provides django fields to -store :class:`Version` or :class:`BaseSpec` objects. - -More documentation is available in the :doc:`django` section. - Contributing ============ @@ -314,35 +266,14 @@ When submitting patches or pull requests, you should respect the following rules - Coding conventions are based on :pep:`8` - The whole test suite must pass after adding the changes - The test coverage for a new feature must be 100% -- New features and methods should be documented in the :doc:`reference` section - and included in the :doc:`changelog` -- Include your name in the :ref:`contributors` section +- New features and methods should be documented in the ``reference`` section + and included in the ``changelog`` +- Include your name in the ``contributors`` section .. note:: All files should contain the following header:: # -*- encoding: utf-8 -*- # Copyright (c) The python-semanticversion project - -Contents -======== - -.. toctree:: - :maxdepth: 2 - - reference - django - changelog - credits - - .. _SemVer: http://semver.org/ .. _PyPI: http://pypi.python.org/ - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - diff --git a/docs/django.rst b/docs/django.rst index 34a0fe3..befa50a 100644 --- a/docs/django.rst +++ b/docs/django.rst @@ -37,4 +37,4 @@ with their :attr:`~django.db.models.CharField.max_length` defaulting to 200. The syntax to use for the field; defaults to ``'simple'``. - .. versionaddedd:: 2.7 + .. versionadded:: 2.7 diff --git a/docs/guide.rst b/docs/guide.rst new file mode 100644 index 0000000..9a7c5cd --- /dev/null +++ b/docs/guide.rst @@ -0,0 +1,346 @@ +Guide +===== + +.. currentmodule:: semantic_version + +This module covers the 2.0.0 version of the SemVer scheme, with additional +extensions: + +- Coercing any version string into a SemVer version, through + :meth:`Version.coerce`; +- Comparing versions; +- Computing next versions; +- Modelling version range specifcations, and choosing the best match -- for both + its custom logic, and NPM semantics (custom range specification schemes can + be added). + + +Version basics +-------------- + +Building :class:`Version` instances +""""""""""""""""""""""""""""""""""" + +The core of the module is the :class:`Version` class; it is usually instantiated +from a version string: + +.. code-block:: pycon + + >>> import semantic_version as semver + >>> v = semver.Version("0.1.1") + +The version's components are available through its attributes: + +* :attr:`~Version.major`, :attr:`~Version.minor`, :attr:`~Version.patch` are + integers: + + .. code-block:: pycon + + >>> v.major + 0 + >>> v.minor + 1 + >>> v.patch + 1 + + +* The :attr:`~Version.prerelease` and :attr:`~Version.build` attributes are + iterables of text elements: + + .. code-block:: pycon + + >>> v2 = semver.Version("0.1.1-dev+23.git2") + >>> v2.prerelease + ["dev"] + >>> v2.build + ["23", "git2"] + + +One may also build a :class:`Version` from named components directly: + +.. code-block:: pycon + + >>> semantic_version.Version(major=0, minor=1, patch=2) + Version('0.1.2') + + +In that case, ``major``, ``minor`` and ``patch`` are mandatory, and must be integers. +``prerelease`` and ``build``, if provided, must be tuples of strings: + +.. code-block:: pycon + + >>> semantic_version.Version(major=0, minor=1, patch=2, prerelease=('alpha', '2')) + Version('0.1.2-alpha.2') + + +If the provided version string is invalid, a :exc:`ValueError` will be raised: + +.. code-block:: pycon + + >>> semver.Version('0.1') + Traceback (most recent call last): + File "", line 1, in + File "/Users/rbarrois/dev/semantic_version/src/semantic_version/base.py", line 64, in __init__ + major, minor, patch, prerelease, build = self.parse(version_string, partial) + File "/Users/rbarrois/dev/semantic_version/src/semantic_version/base.py", line 86, in parse + raise ValueError('Invalid version string: %r' % version_string) + ValueError: Invalid version string: '0.1' + + +Working with non-SemVer version strings +""""""""""""""""""""""""""""""""""""""" + +Some user-supplied input might not match the semantic version scheme. +For such cases, the ``Version.coerce`` method will try to convert any +version-like string into a valid semver version: + +.. code-block:: pycon + + >>> semver.Version.coerce('0') + Version('0.0.0') + >>> semver.Version.coerce('0.1.2.3.4') + Version('0.1.2+3.4') + >>> semver.Version.coerce('0.1.2a3') + Version('0.1.2-a3') + + +Comparing versions +"""""""""""""""""" + +Versions can be compared, following the SemVer scheme: + +.. code-block:: pycon + + >>> semver.Version("0.1.0") < semver.Version("0.1.1") + True + >>> max( + ... semver.Version("0.1.0"), + ... semver.Version("0.2.2"), + ... semver.Version("0.1.1"), + ... semver.Version("0.2.2-rc1"), + ... ) + Version("0.2.2") + + +.. note:: + + As defined in SemVer, build metadata is ignored in comparisons, + but not in equalities: + + .. code-block:: pycon + + >>> semver.Version("0.1.2") <= semver.Version("0.1.2+git2") + True + >>> semver.Version("0.1.2") >= semver.Version("0.1.2+git2") + True + >>> semver.Version("0.1.2") == semver.Version("0.1.2+git2") + False + + +Iterating versions +"""""""""""""""""" + +One can get a new version that represents a bump in one of the version levels +through the :meth:`Version.next_major`, :meth:`Version.next_minor` or +:meth:`Version.next_patch` functions: + +.. code-block:: pycon + + >>> v = semver.Version('0.1.1+build') + >>> new_v = v.next_major() + >>> str(new_v) + '1.0.0' + >>> v = semver.Version('1.1.1+build') + >>> new_v = v.next_minor() + >>> str(new_v) + '1.2.0' + >>> v = semver.Version('1.1.1+build') + >>> new_v = v.next_patch() + >>> str(new_v) + '1.1.2' + +.. note:: + + * If the version includes :attr:`~Version.build` or + :attr:`~Version.prerelease` metadata, that value will be empty in the + next version; + * The next patch following a version with a pre-release identifier + is the same version with its prerelease and build identifiers removed: + ``Version("0.1.1-rc1").next_patch() == Version("0.1.1")`` + * Pre-release and build naming schemes are often custom and specific + to a project's internal design; thus, the library can't provide a + ``next_xxx`` method for those fields. + +One may also truncate versions through the :meth:`Version.truncate` method, +removing components beyond the selected level: + +.. code-block:: pycon + + >>> v = semver.Version("0.1.2-dev+git3") + >>> v.truncate("prerelease") + Version("0.1.2-dev") + >>> v.truncate("minor") + Version("0.1.0") + + +Range specifications +-------------------- + +Comparing version numbers isn't always enough; in many situations, one needs to +define a *range of acceptable versions*. + +That notion is not defined in SemVer; moreover, several systems exists, with +their own notations. + +The ``semantic_version`` package provides a couple of implementations for these +notions: + +- :class:`SimpleSpec` is a simple implementation, with reasonable expectations; +- :class:`NpmSpec` sticks to the NPM specification. + +Further schemes can be built in a similar manner, relying on the :class:`BaseSpec` +class for basics. + +Core API +"""""""" + +The core API is provided by the :class:`BaseSpec` class. + +.. note:: + + These examples use :class:`SimpleSpec` in order to be easily reproduced + by users, but only exhibit the standard parts of the interface. + +It is possible to check whether a given :class:`Version` matches a +:class:`BaseSpec` through :meth:`~BaseSpec.match`: + +.. code-block:: pycon + + >>> s = semver.SimpleSpec(">=0.1.1") + >>> s.match(Version("0.1.1")) + True + >>> s.match(Version("0.1.0")) + False + +This feature is also available through the ``in`` keyword: + +.. code-block:: pycon + + >>> s = semver.SimpleSpec(">=0.1.1") + >>> Version("0.1.1") in s + True + >>> Version("0.1.0") in s + False + +A specification can filter compatible values from an iterable of versions +with :meth:`~BaseSpec.filter`: + +.. code-block:: pycon + + >>> s = semver.SimpleSpec(">=0.2.1") + >>> versions = [ + ... Version("0.1.0"), + ... Version("0.2.0"), + ... Version("0.3.0"), + ... Version("0.4.0"), + ... ] + >>> list(s.filter(versions)) + [Version("0.3.0"), Version("0.4.0")] + +It can also select the "best" version from such an iterable through +:meth:`~BaseSpec.select`: + +.. code-block:: pycon + + >>> s = semver.SimpleSpec(">=0.2.1") + >>> versions = [ + ... Version("0.1.0"), + ... Version("0.2.0"), + ... Version("0.3.0"), + ... Version("0.4.0"), + ... ] + >>> s.select(versions) + Version("0.4.0") + + +The :class:`SimpleSpec` scheme +"""""""""""""""""""""""""""""" + +The :class:`SimpleSpec` provides a hopefully intuitive version range +specification scheme: + +- A specification expression is composed of comma-separated clauses; +- Each clause can be: + + - An equality match (``==`` or ``!=``); + - A comparison (``>``, ``>=``, ``<`` , ``<=``); + - A compatible release clause, PyPI style (``~=2.2`` for ``>=2.2.0,<3.0.0``); + - An NPM style clause: + + - ``~1.2.3`` for ``>=1.2.3,<1.3.0``; + - ``^1.3.4`` for ``>=1.3.4,<2.0.0``; + +- The range in each clause may include a wildcard: + + * ``==0.1.*`` maps to ``>=0.1.0,<0.2.0``; + * ``==1.*`` or ``==1.*.*`` map to ``>=1.0.0,<2.0.0`` + + +.. rubric:: Special matching rules + +When testing a :class:`Version` against a :class:`SimpleSpec`, comparisons are +adjusted for common user expectations; thus, a pre-release version (``1.0.0-alpha``) +will not satisfy the ``==1.0.0`` :class:`SimpleSpec`. + +Pre-release identifiers will only be compared if included in the :class:`BaseSpec` +definition or (for the empty pre-release number) if a single dash is appended +(``1.0.0-``): + + +.. code-block:: pycon + + >>> Version('0.1.0-alpha') in SimpleSpec('<0.1.0') # No pre-release identifier + False + >>> Version('0.1.0-alpha') in SimpleSpec('<0.1.0-') # Include pre-release in checks + True + + +Build metadata has no ordering; thus, the only meaningful comparison including +build metadata is equality: + + +.. code-block:: pycon + + >>> Version('1.0.0+build2') in SimpleSpec('<=1.0.0') # Build metadata ignored + True + >>> Version('1.0.0+build1') in SimpleSpec('==1.0.0+build2') # Include build in checks + False + +.. note:: + + The full documentation is provided in the reference section + for the :class:`SimpleSpec` class. + + +The :class:`NpmSpec` scheme +""""""""""""""""""""""""""" + +The :class:`NpmSpec` class implements the full NPM specification (from +https://github.com/npm/node-semver#ranges): + +.. code-block:: pycon + + >>> semver.Version("0.1.2") in semver.NpmSpec("0.1.0-alpha.2 .. 0.2.4") + True + >>> semver.Version('0.1.2') in semver.NpmSpec('>=0.1.1 <0.1.3 || 2.x') + True + >>> semver.Version('2.3.4') in semver.NpmSpec('>=0.1.1 <0.1.3 || 2.x') + True + +Using with Django +----------------- + +The :mod:`semantic_version.django_fields` module provides django fields to +store :class:`Version` or :class:`BaseSpec` objects. + +More documentation is available in the :doc:`django` section. diff --git a/docs/index.rst b/docs/index.rst deleted file mode 120000 index 89a0106..0000000 --- a/docs/index.rst +++ /dev/null @@ -1 +0,0 @@ -../README.rst \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..135ee68 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,30 @@ +====================== +python-semanticversion +====================== + +.. include:: introduction.rst + + +Contents +======== + +.. toctree:: + :maxdepth: 2 + + introduction + guide + reference + django + changelog + credits + + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/docs/introduction.rst b/docs/introduction.rst new file mode 120000 index 0000000..89a0106 --- /dev/null +++ b/docs/introduction.rst @@ -0,0 +1 @@ +../README.rst \ No newline at end of file diff --git a/docs/reference.rst b/docs/reference.rst index 951bd9a..b2946d9 100644 --- a/docs/reference.rst +++ b/docs/reference.rst @@ -66,6 +66,7 @@ Representing a version (the Version class) ------------------------------------------ .. class:: Version(version_string[, partial=False]) + :noindex: Object representation of a `SemVer`_-compliant version. @@ -90,15 +91,6 @@ Representing a version (the Version class) .. rubric:: Attributes - .. attribute:: partial - - ``bool``, whether this is a 'partial' or a complete version number. - Partial version number may lack :attr:`minor` or :attr:`patch` version numbers. - - .. deprecated:: 2.7 - The ability to define a partial version will be removed in version 3.0. - Use :class:`SimpleSpec` instead: ``SimpleSpec('1.x.x')``. - .. attribute:: major ``int``, the major version number @@ -138,7 +130,25 @@ Representing a version (the Version class) The actual value of the attribute is considered an implementation detail; the only guarantee is that ordering versions by their precedence_key will comply with semver precedence rules. - Note that the :attr:`~Version.build` isn't included in the precedence_key computatin. + + .. warning:: + + .. versionchanged:: 2.10.0 + + The :attr:`~Version.build` is included in the precedence_key computation, but + only for ordering stability. + The only guarantee is that, for a given release of python-semanticversion, two versions' + :attr:`~Version.precedence_key` will always compare in the same direction if they include + build metadata; that ordering is an implementation detail and shouldn't be relied upon. + + .. attribute:: partial + + ``bool``, whether this is a 'partial' or a complete version number. + Partial version number may lack :attr:`minor` or :attr:`patch` version numbers. + + .. deprecated:: 2.7 + The ability to define a partial version will be removed in version 3.0. + Use :class:`SimpleSpec` instead: ``SimpleSpec('1.x.x')``. .. rubric:: Methods @@ -173,7 +183,7 @@ Representing a version (the Version class) >>> Version('1.1.0-alpha').next_minor() Version('1.1.0') - .. method:: next_patch(self): + .. method:: next_patch(self) Return the next patch version, i.e the smallest version strictly greater than the current one with empty :attr:`prerelease` and :attr:`build`. @@ -231,6 +241,7 @@ Representing a version (the Version class) - For non-:attr:`partial` versions, compare using the `SemVer`_ scheme - If any compared object is :attr:`partial`: + - Begin comparison using the `SemVer`_ scheme - If a component (:attr:`minor`, :attr:`patch`, :attr:`prerelease` or :attr:`build`) was absent from the :attr:`partial` :class:`Version` -- represented with :obj:`None` @@ -334,7 +345,7 @@ In order to solve this problem, each `SemVer`_-based package management platform python-semanticversion provides a couple of implementations of those range definition syntaxes: - ``'simple'`` (through :class:`SimpleSpec`): A python-semanticversion specific syntax, which supports simple / intuitive patterns, and some NPM-inspired extensions; -- ``'npm'`` (through :class:`NpmSpec`): The NPM syntax, based on https://docs.npmjs.com/misc/semver.html +- ``'npm'`` (through :class:`NpmSpec`): The NPM syntax, based on https://github.com/npm/node-semver#ranges - More might be added in the future. Each of those ``Spec`` classes provides a shared set of methods to work with versions: @@ -472,7 +483,7 @@ Each of those ``Spec`` classes provides a shared set of methods to work with ver * A clause of ``>0.1.2-rc.3`` will match versions strictly above ``0.1.2-rc.3``, including matching prereleases of ``0.1.2``: ``0.1.2-rc.10`` is included; * A clause of ``>=XXX`` will match versions that match ``>XXX`` or ``==XXX`` - ..rubric:: Wildcards + .. rubric:: Wildcards * A clause of ``==0.1.*`` is equivalent to ``>=0.1.0,<0.2.0`` * A clause of ``>=0.1.*`` is equivalent to ``>=0.1.0`` @@ -516,7 +527,7 @@ Each of those ``Spec`` classes provides a shared set of methods to work with ver .. versionadded:: 2.7 - A NPM-compliant version matching engine, based on the https://docs.npmjs.com/misc/semver.html specification. + A NPM-compliant version matching engine, based on the https://github.com/npm/node-semver#ranges specification. .. code-block:: pycon @@ -554,7 +565,7 @@ Each of those ``Spec`` classes provides a shared set of methods to work with ver , )> - Its keeps a list of :class:`SpecItem` objects, based on the initial expression + It keeps a list of :class:`SpecItem` objects, based on the initial expression components. .. method:: __iter__(self) @@ -705,7 +716,13 @@ Each of those ``Spec`` classes provides a shared set of methods to work with ver >>> Version('1.0.1') in Spec('!=1.0.1') False - The kind of 'Almost equal to' specifications + .. data:: KIND_COMPATIBLE + + The kind of `compatible release clauses`_ + specifications:: + + >>> Version('1.1.2') in Spec('~=1.1.0') + True diff --git a/semantic_version/base.py b/semantic_version/base.py index 871ccb0..6be5624 100644 --- a/semantic_version/base.py +++ b/semantic_version/base.py @@ -118,6 +118,12 @@ def __init__( self.partial = partial + # Cached precedence keys + # _cmp_precedence_key is used for semver-precedence comparison + self._cmp_precedence_key = self._build_precedence_key(with_build=False) + # _sort_precedence_key is used for self.precedence_key, esp. for sorted(...) + self._sort_precedence_key = self._build_precedence_key(with_build=True) + @classmethod def _coerce(cls, value, allow_none=False): if value is None and allow_none: @@ -126,14 +132,14 @@ def _coerce(cls, value, allow_none=False): def next_major(self): if self.prerelease and self.minor == self.patch == 0: - return Version( + return self.__class__( major=self.major, minor=0, patch=0, partial=self.partial, ) else: - return Version( + return self.__class__( major=self.major + 1, minor=0, patch=0, @@ -142,14 +148,14 @@ def next_major(self): def next_minor(self): if self.prerelease and self.patch == 0: - return Version( + return self.__class__( major=self.major, minor=self.minor, patch=0, partial=self.partial, ) else: - return Version( + return self.__class__( major=self.major, minor=self.minor + 1, patch=0, @@ -158,14 +164,14 @@ def next_minor(self): def next_patch(self): if self.prerelease: - return Version( + return self.__class__( major=self.major, minor=self.minor, patch=self.patch, partial=self.partial, ) else: - return Version( + return self.__class__( major=self.major, minor=self.minor, patch=self.patch + 1, @@ -175,9 +181,16 @@ def next_patch(self): def truncate(self, level='patch'): """Return a new Version object, truncated up to the selected level.""" if level == 'build': - return self + return self.__class__( + major=self.major, + minor=self.minor, + patch=self.patch, + prerelease=self.prerelease, + build=self.build, + partial=self.partial, + ) elif level == 'prerelease': - return Version( + return self.__class__( major=self.major, minor=self.minor, patch=self.patch, @@ -185,21 +198,21 @@ def truncate(self, level='patch'): partial=self.partial, ) elif level == 'patch': - return Version( + return self.__class__( major=self.major, minor=self.minor, patch=self.patch, partial=self.partial, ) elif level == 'minor': - return Version( + return self.__class__( major=self.major, minor=self.minor, patch=None if self.partial else 0, partial=self.partial, ) elif level == 'major': - return Version( + return self.__class__( major=self.major, minor=None if self.partial else 0, patch=None if self.partial else 0, @@ -253,7 +266,7 @@ def coerce(cls, version_string, partial=False): ) if match.end() == len(version_string): - return Version(version, partial=partial) + return cls(version, partial=partial) rest = version_string[match.end():] @@ -290,7 +303,8 @@ def coerce(cls, version_string, partial=False): @classmethod def parse(cls, version_string, partial=False, coerce=False): - """Parse a version string into a Version() object. + """Parse a version string into a tuple of components: + (major, minor, patch, prerelease, build). Args: version_string (str), the version string to parse @@ -407,11 +421,15 @@ def __hash__(self): # at least a field being `None`. return hash((self.major, self.minor, self.patch, self.prerelease, self.build)) - @property - def precedence_key(self): + def _build_precedence_key(self, with_build=False): + """Build a precedence key. + + The "build" component should only be used when sorting an iterable + of versions. + """ if self.prerelease: prerelease_key = tuple( - NumericIdentifier(part) if re.match(r'^[0-9]+$', part) else AlphaIdentifier(part) + NumericIdentifier(part) if part.isdigit() else AlphaIdentifier(part) for part in self.prerelease ) else: @@ -419,13 +437,31 @@ def precedence_key(self): MaxIdentifier(), ) + if not with_build: + return ( + self.major, + self.minor, + self.patch, + prerelease_key, + ) + + build_key = tuple( + NumericIdentifier(part) if part.isdigit() else AlphaIdentifier(part) + for part in self.build or () + ) + return ( self.major, self.minor, self.patch, prerelease_key, + build_key, ) + @property + def precedence_key(self): + return self._sort_precedence_key + def __cmp__(self, other): if not isinstance(other, self.__class__): return NotImplemented @@ -457,22 +493,22 @@ def __ne__(self, other): def __lt__(self, other): if not isinstance(other, self.__class__): return NotImplemented - return self.precedence_key < other.precedence_key + return self._cmp_precedence_key < other._cmp_precedence_key def __le__(self, other): if not isinstance(other, self.__class__): return NotImplemented - return self.precedence_key <= other.precedence_key + return self._cmp_precedence_key <= other._cmp_precedence_key def __gt__(self, other): if not isinstance(other, self.__class__): return NotImplemented - return self.precedence_key > other.precedence_key + return self._cmp_precedence_key > other._cmp_precedence_key def __ge__(self, other): if not isinstance(other, self.__class__): return NotImplemented - return self.precedence_key >= other.precedence_key + return self._cmp_precedence_key >= other._cmp_precedence_key class SpecItem(object): diff --git a/semantic_version/django_fields.py b/semantic_version/django_fields.py index caa7a8c..e5bd7eb 100644 --- a/semantic_version/django_fields.py +++ b/semantic_version/django_fields.py @@ -4,8 +4,14 @@ import warnings +import django from django.db import models -from django.utils.translation import ugettext_lazy as _ + +if django.VERSION >= (3, 0): + # See https://docs.djangoproject.com/en/dev/releases/3.0/#features-deprecated-in-3-0 + from django.utils.translation import gettext_lazy as _ +else: + from django.utils.translation import ugettext_lazy as _ from . import base diff --git a/setup.cfg b/setup.cfg index 42360d4..46a2673 100644 --- a/setup.cfg +++ b/setup.cfg @@ -1,6 +1,6 @@ [metadata] name = semantic_version -version = 2.8.6.dev0 +version = 2.10.1.dev0 description = A library implementing the 'SemVer' scheme. long_description = file: README.rst # https://docutils.sourceforge.io/FAQ.html#what-s-the-official-mime-type-for-restructuredtext-data @@ -26,6 +26,8 @@ classifiers = Programming Language :: Python :: 3.7 Programming Language :: Python :: 3.8 Programming Language :: Python :: 3.9 + Programming Language :: Python :: 3.10 + Programming Language :: Python :: 3.11 Topic :: Software Development :: Libraries :: Python Modules [options] diff --git a/tests/test_base.py b/tests/test_base.py index 4a844c3..4136045 100755 --- a/tests/test_base.py +++ b/tests/test_base.py @@ -229,6 +229,20 @@ def test_invalid_comparisons(self): self.assertTrue(v != '0.1.0') self.assertFalse(v == '0.1.0') + def test_stable_ordering(self): + a = [ + base.Version('0.1.0'), + base.Version('0.1.0+a'), + base.Version('0.1.0+a.1'), + base.Version('0.1.1-a1'), + ] + b = [a[1], a[3], a[0], a[2]] + + self.assertEqual( + sorted(a, key=lambda v: v.precedence_key), + sorted(b, key=lambda v: v.precedence_key), + ) + def test_bump_clean_versions(self): # We Test each property explicitly as the == comparator for versions # does not distinguish between prerelease or builds for equality. @@ -381,6 +395,25 @@ def test_bump_prerelease_versions(self): self.assertEqual(v.prerelease, ()) self.assertEqual(v.build, ()) + def test_truncate(self): + v = base.Version("3.2.1-pre+build") + self.assertEqual(v.truncate("build"), v) + self.assertIsNot(v.truncate("build"), v) + self.assertEqual(v.truncate("prerelease"), base.Version("3.2.1-pre")) + self.assertEqual(v.truncate("patch"), base.Version("3.2.1")) + self.assertEqual(v.truncate(), base.Version("3.2.1")) + self.assertEqual(v.truncate("minor"), base.Version("3.2.0")) + self.assertEqual(v.truncate("major"), base.Version("3.0.0")) + + def test_subclass(self): + """Custom subclasses of Version returns instances of themselves.""" + class MyVersion(base.Version): + pass + + v = MyVersion("3.2.1-pre") + subv = v.truncate() + self.assertEqual(type(subv), MyVersion) + class SpecItemTestCase(unittest.TestCase): if sys.version_info[0] <= 2: diff --git a/tox.ini b/tox.ini index f1cb1be..369cf12 100644 --- a/tox.ini +++ b/tox.ini @@ -1,9 +1,8 @@ [tox] envlist = - py{27,34,35,36,37}-django111 - py{35,36,37,38}-django22 - py{36,37,38,39}-django31 - pypy3-django{111,22,31} + py{37,38,39,310}-django32 + py{38,39,310,311}-django41 + pypy3-django{32} lint toxworkdir = {env:TOX_WORKDIR:.tox} @@ -11,15 +10,16 @@ toxworkdir = {env:TOX_WORKDIR:.tox} [testenv] extras = dev deps = - django111: Django>=1.11,<1.12 - django22: Django>=2.2,<2.3 - django31: Django>=3.1,<3.2 + django32: Django>=3.2,<3.3 + django41: Django>=4.1,<4.2 +allowlist_externals = make whitelist_externals = make commands = make test [testenv:lint] extras = dev +allowlist_externals = make whitelist_externals = make commands = make lint