diff options
Diffstat (limited to 'doc/index.rst')
| -rw-r--r-- | doc/index.rst | 62 |
1 files changed, 28 insertions, 34 deletions
diff --git a/doc/index.rst b/doc/index.rst index cae45f5..952e30e 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -82,9 +82,9 @@ Obviously, :class:`Versions <Version>` can be compared:: Requirement specification ------------------------- -The :class:`SpecItem` object describes a range of accepted versions:: +The :class:`Spec` object describes a range of accepted versions:: - >>> s = SpecItem('>=0.1.1') # At least 0.1.1 + >>> s = Spec('>=0.1.1') # At least 0.1.1 >>> s.match(Version('0.1.1')) True >>> s.match(Version('0.1.1-alpha1')) # pre-release satisfy version spec @@ -94,61 +94,55 @@ The :class:`SpecItem` object describes a range of accepted versions:: Simpler test syntax is also available using the ``in`` keyword:: - >>> s = SpecItem('==0.1.1') + >>> s = Spec('==0.1.1') >>> Version('0.1.1-alpha1') in s True >>> Version('0.1.2') in s False +Combining specifications can be expressed in two ways: + +- Components separated by commas in a single string:: + + >>> Spec('>=0.1.1,<0.3.0') + +- Components given as different arguments:: + + >>> Spec('>=0.1.1', '<0.3.0') + +- A mix of both versions:: + + >>> Spec('>=0.1.1', '!=0.2.4-alpha,<0.3.0') + + Including pre-release identifiers in specifications """"""""""""""""""""""""""""""""""""""""""""""""""" -When testing a :class:`Version` against a :class:`SpecItem`, comparisons are only -performed for components defined in the :class:`SpecItem`; thus, a pre-release +When testing a :class:`Version` against a :class:`Spec`, comparisons are only +performed for components defined in the :class:`Spec`; thus, a pre-release version (``1.0.0-alpha``), while not strictly equal to the non pre-release -version (``1.0.0``), satisfies the ``==1.0.0`` :class:`SpecItem`. +version (``1.0.0``), satisfies the ``==1.0.0`` :class:`Spec`. -Pre-release identifiers will only be compared if included in the :class:`SpecItem` +Pre-release identifiers will only be compared if included in the :class:`Spec` definition or (for the empty pre-release number) if a single dash is appended (``1.0.0-``):: - >>> Version('0.1.0-alpha') in SpecItem('>=0.1.0') # No pre-release identifier + >>> Version('0.1.0-alpha') in Spec('>=0.1.0') # No pre-release identifier True - >>> Version('0.1.0-alpha') in SpecItem('>=0.1.0-') # Include pre-release in checks + >>> Version('0.1.0-alpha') in Spec('>=0.1.0-') # Include pre-release in checks False Including build identifiers in specifications """"""""""""""""""""""""""""""""""""""""""""" The same rule applies for the build identifier: comparisons will include it only -if it was included in the :class:`SpecItem` definition, or - for the unnumbered build +if it was included in the :class:`Spec` definition, or - for the unnumbered build version - if a single + is appended to the definition(``1.0.0+``, ``1.0.0-alpha+``):: - >>> Version('1.0.0+build2') in SpecItem('<=1.0.0') # Build identifier ignored + >>> Version('1.0.0+build2') in Spec('<=1.0.0') # Build identifier ignored True - >>> Version('1.0.0+build2') in SpecItem('<=1.0.0+') # Include build in checks - False - - -Combining requirements -====================== - -In order to express complex version specifications, use the :class:`Spec` class:: - - >>> # At least 0.1.1, not 0.2.0, avoid broken 0.1.5-alpha. - >>> sl = Spec('>=0.1.1,<0.2.0,!=0.1.5-alpha') - >>> sl.match(Version('0.1.1')) - True - >>> Version('0.1.1-rc1') in sl - True - >>> Version('0.1.2') in sl - True - >>> Version('0.2.0-alpha') in sl - False - >>> Version('0.1.5-alpha') in sl - False - >>> Version('0.1.5-alpha+build2') in sl + >>> Version('1.0.0+build2') in Spec('<=1.0.0+') # Include build in checks False @@ -156,7 +150,7 @@ Using with Django ================= The :mod:`semantic_version.django_fields` module provides django fields to -store :class:`Version`, :class:`SpecItem` or :class:`Spec` objects. +store :class:`Version` or :class:`Spec` objects. More documentation is available in the :doc:`django` section. |