From ccc85ec6bdbaa518b2e78c8e694e3aca0241f08d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rapha=C3=ABl=20Barrois?= Date: Fri, 22 Mar 2013 13:23:28 +0100 Subject: Merge README and index.rst. --- Makefile | 2 +- README | 306 ++++++++++++++++++++++++++++++++++++++++++++++++---------- doc/index.rst | 246 +--------------------------------------------- 3 files changed, 258 insertions(+), 296 deletions(-) mode change 100644 => 120000 doc/index.rst diff --git a/Makefile b/Makefile index 22e50d8..9ccf1e7 100644 --- a/Makefile +++ b/Makefile @@ -21,7 +21,7 @@ coverage: coverage html "--include=$(PACKAGE_DIR)/*.py,tests/*.py" doc: - $(MAKE) -C docs html + $(MAKE) -C doc html .PHONY: all default clean coverage doc test diff --git a/README b/README index 37692e0..9d64887 100644 --- a/README +++ b/README @@ -1,85 +1,291 @@ +.. python-semanticversion documentation master file, created by + sphinx-quickstart on Wed May 16 10:41:34 2012. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + python-semanticversion ====================== +This small python library provides a few tools to handle `SemVer`_ in Python. +It follows strictly the 2.0.0-rc1 version of the SemVer scheme. + .. image:: https://secure.travis-ci.org/rbarrois/python-semanticversion.png?branch=master :target: http://travis-ci.org/rbarrois/python-semanticversion/ -This small python library provides a few tools to handle `SemVer `_ in Python. +semantic_version supports Python 2.6, 2.7, 3.2, 3.3, and is distributed under the two-clause BSD licence. +Links +----- -Handles the full 2.0.0-rc1 version of the SemVer scheme, and provides tools to declare version ranges. +- Package on `PyPI`_: http://pypi.python.org/pypi/semantic_version/ +- Doc on `ReadTheDocs `_: http://readthedocs.org/docs/python-semanticversion/ +- Source on `GitHub `_: http://github.com/rbarrois/python-semanticversion/ +- Build on `Travis CI `_: http://travis-ci.org/rbarrois/python-semanticversion/ +- Semantic Version specification: `SemVer`_ -The full doc is available on http://python-semanticversion.readthedocs.org/; simple usage is described below. +Getting started +=============== -The semantic_version library supports Python 2.6, 2.7, 3.2, 3.3. +Intall the package from `PyPI`_, using pip: +.. code-block:: sh -Usage -===== + pip install semantic_version +Or from GitHub: -Install:: +.. code-block:: sh - $ pip install semantic_version - $ + $ git clone git://github.com/rbarrois/python-semanticversion.git -Define a Version:: - >>> from semantic_version import Version - >>> v = Version('0.1.1') +Import it in your code: -Compare it to other versions:: - >>> v < Version('0.1.2') - True - >>> sorted([Version('0.1.1'), Version('0.11.1'), Version('0.1.1-alpha')]) - [Version('0.1.1-alpha'), Version('0.1.1'), Version('0.11.1')] +.. code-block:: python -Define a simple specification:: + import semantic_version - >>> from semantic_version import Spec - >>> s = Spec('>=0.1.1') - >>> Version('0.1.1') in s - True - >>> Version('0.1.1-alpha') in s - False -Define complex specifications:: +.. currentmodule:: semantic_version - >>> s = Spec('>=0.1.1,<0.2.0') - >>> Version('0.1.2') in s - True - >>> Version('0.3.0') in s - False - >>> Version('0.2.0') in s - False +This module provides two classes to handle semantic versions: +- :class:`Version` represents a version number (``0.1.1-alpha+build.2012-05-15``) +- :class:`Spec` represents a requirement specification (``>=0.1.1,<0.3.0``) -Select the best compatible version from a list:: +Versions +-------- - >>> s = Spec('>=0.1.1,<0.2.0') - >>> s.select([Version('0.1.1'), Version('0.1.9-alpha'), Version('0.1.9-alpha+1')) - Version('0.1.9-alpha+1') +Defining a :class:`Version` is quite simple: -Framework integration -===================== +.. code-block:: pycon -Integrates with `Django `_, through the ``VersionField`` and ``SpecField`` custom fields:: + >>> import semantic_version + >>> v = semantic_version.Version('0.1.1') + >>> v.major + 0 + >>> v.minor + 1 + >>> v.patch + 1 + >>> v.prerelease + [] + >>> v.build + [] + >>> list(v) + [0, 1, 1, [], []] - from semantic_version import django_fields as semver_fields +If the provided version string is invalid, a :exc:`ValueError` will be raised: - class MyComputer(models.Model): - name = models.CharField(max_length=40) - kernel_version = semver_fields.VersionField() +.. code-block:: pycon + >>> semantic_version.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' -Links -===== +In order to define "relaxed" version strings, you must pass in ``partial=True``: + +.. code-block:: pycon + + >>> v = semantic_version.Version('0.1', partial=True) + >>> list(v) + [0, 1, None, None, None] + + +Obviously, :class:`Versions ` can be compared: + + +.. code-block:: pycon + + >>> semantic_version.Version('0.1.1') < semantic_version.Version('0.1.2') + True + >>> semantic_version.Version('0.1.1') > semantic_version.Version('0.1.1-alpha') + True + >>> semantic_version.Version('0.1.1') <= semantic_version.Version('0.1.1-alpha') + False + + +Requirement specification +------------------------- + +The :class:`Spec` object describes a range of accepted versions: + + +.. code-block:: pycon + + >>> 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 + True + >>> s.match(Version('0.1.0')) + False + +Simpler test syntax is also available using the ``in`` keyword: + +.. code-block:: pycon + + >>> 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: + + .. code-block:: pycon + + >>> Spec('>=0.1.1,<0.3.0') + +- Components given as different arguments: + + .. code-block:: pycon + + >>> Spec('>=0.1.1', '<0.3.0') + +- A mix of both versions: + + .. code-block:: pycon + + >>> Spec('>=0.1.1', '!=0.2.4-alpha,<0.3.0') + + +Using a specification +""""""""""""""""""""" + +The :func:`Spec.filter` method filters an iterable of :class:`Version`: + +.. code-block:: pycon + + >>> s = Spec('>=0.1.0,<0.4.0') + >>> versions = (Version('0.%d.0' % i) for i in range(6)) + >>> for v in s.filter(versions): + ... print v + 0.1.0 + 0.2.0 + 0.3.0 + +It is also possible to select the 'best' version from such iterables: + + +.. code-block:: pycon + + >>> s = Spec('>=0.1.0,<0.4.0') + >>> versions = (Version('0.%d.0' % i) for i in range(6)) + >>> s.select(versions) + 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:`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:`Spec`. + +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-``): + + +.. code-block:: pycon + + >>> Version('0.1.0-alpha') in Spec('>=0.1.0') # No pre-release identifier + True + >>> 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:`Spec` definition, or - for the unnumbered build +version - if a single + is appended to the definition(``1.0.0+``, ``1.0.0-alpha+``): + + +.. code-block:: pycon + + >>> Version('1.0.0+build2') in Spec('<=1.0.0') # Build identifier ignored + True + >>> Version('1.0.0+build2') in Spec('<=1.0.0+') # Include build in checks + False + + +Using with Django +================= + +The :mod:`semantic_version.django_fields` module provides django fields to +store :class:`Version` or :class:`Spec` objects. + +More documentation is available in the :doc:`django` section. + + +Contents +======== + +.. toctree:: + :maxdepth: 2 + + reference + django + changelog + + +Contributing +============ + +In order to contribute to the source code: + +- Open an issue on `GitHub`_: https://github.com/rbarrois/python-semanticversion/issues +- Fork the `repository `_ + and submit a pull request on `GitHub`_ +- Send me a patch (mailto:raphael.barrois@polytechnique.org) + +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` + + +.. _SemVer: http://semver.org/ +.. _PyPI: http://pypi.python.org/ + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` -- Package on `PyPI `_: http://pypi.python.org/pypi/semantic_version/ -- Doc on `ReadTheDocs `_: http://readthedocs.org/docs/python-semanticversion/ -- Source on `GitHub `_: http://github.com/rbarrois/python-semanticversion/ -- Build on `Travis CI `_: http://travis-ci.org/rbarrois/python-semanticversion/ -- Semantic Version specification: http://semver.org/ diff --git a/doc/index.rst b/doc/index.rst deleted file mode 100644 index 0e19004..0000000 --- a/doc/index.rst +++ /dev/null @@ -1,245 +0,0 @@ -.. python-semanticversion documentation master file, created by - sphinx-quickstart on Wed May 16 10:41:34 2012. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -python-semanticversion -====================== - -This small python library provides a few tools to handle `SemVer`_ in Python. - - -It follows strictly the 2.0.0-rc1 version of the SemVer scheme. - - -Getting started -=============== - -Intall the package from `PyPI`_, using pip:: - - pip install semantic_version - - -Import it in your code:: - - import semantic_version - -.. currentmodule:: semantic_version - -This module provides two classes to handle semantic versions: - -- :class:`Version` represents a version number (``0.1.1-alpha+build.2012-05-15``) -- :class:`Spec` represents a requirement specification (``>=0.1.1,<0.3.0``) - -Versions --------- - -Defining a :class:`Version` is quite simple:: - - >>> import semantic_version - >>> v = semantic_version.Version('0.1.1') - >>> v.major - 0 - >>> v.minor - 1 - >>> v.patch - 1 - >>> v.prerelease - [] - >>> v.build - [] - >>> list(v) - [0, 1, 1, [], []] - -If the provided version string is invalid, a :exc:`ValueError` will be raised:: - - >>> semantic_version.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' - -In order to define "relaxed" version strings, you must pass in ``partial=True``:: - - >>> v = semantic_version.Version('0.1', partial=True) - >>> list(v) - [0, 1, None, None, None] - - -Obviously, :class:`Versions ` can be compared:: - - >>> semantic_version.Version('0.1.1') < semantic_version.Version('0.1.2') - True - >>> semantic_version.Version('0.1.1') > semantic_version.Version('0.1.1-alpha') - True - >>> semantic_version.Version('0.1.1') <= semantic_version.Version('0.1.1-alpha') - False - - -Requirement specification -------------------------- - -The :class:`Spec` object describes a range of accepted versions:: - - >>> 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 - True - >>> s.match(Version('0.1.0')) - False - -Simpler test syntax is also available using the ``in`` keyword:: - - >>> 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') - - -Using a specification -""""""""""""""""""""" - -The :func:`Spec.filter` method filters an iterable of :class:`Version`:: - - >>> s = Spec('>=0.1.0,<0.4.0') - >>> versions = (Version('0.%d.0' % i) for i in range(6)) - >>> for v in s.filter(versions): - ... print v - 0.1.0 - 0.2.0 - 0.3.0 - -It is also possible to select the 'best' version from such iterables:: - - >>> s = Spec('>=0.1.0,<0.4.0') - >>> versions = (Version('0.%d.0' % i) for i in range(6)) - >>> s.select(versions) - 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:: - - >>> 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:`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:`Spec`. - -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 Spec('>=0.1.0') # No pre-release identifier - True - >>> 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:`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 Spec('<=1.0.0') # Build identifier ignored - True - >>> Version('1.0.0+build2') in Spec('<=1.0.0+') # Include build in checks - False - - -Using with Django -================= - -The :mod:`semantic_version.django_fields` module provides django fields to -store :class:`Version` or :class:`Spec` objects. - -More documentation is available in the :doc:`django` section. - - -Contents -======== - -.. toctree:: - :maxdepth: 2 - - reference - django - changelog - - -Contributing -============ - -In order to contribute to the source code: - -- Open an issue on `GitHub`_: https://github.com/rbarrois/python-semanticversion/issues -- Fork the `repository `_ - and submit a pull request on `GitHub`_ -- Send me a patch (mailto:raphael.barrois@polytechnique.org) - -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` - -.. note:: 'raw' patches / pull requests will be accepted too, but will require more - cooperative work to bring them to the expected standard. - - -Links -===== - -- Package on `PyPI`_: http://pypi.python.org/pypi/semantic_version/ -- Doc on `ReadTheDocs `_: http://readthedocs.org/docs/python-semanticversion/ -- Source on `GitHub `_: http://github.com/rbarrois/python-semanticversion/ -- Build on `Travis CI `_: http://travis-ci.org/rbarrois/python-semanticversion/ -- Semantic Version specification: `SemVer`_ - -.. _SemVer: http://semver.org/ -.. _PyPI: http://pypi.python.org/ - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - diff --git a/doc/index.rst b/doc/index.rst new file mode 120000 index 0000000..59a23c4 --- /dev/null +++ b/doc/index.rst @@ -0,0 +1 @@ +../README \ No newline at end of file -- cgit v1.2.1