diff options
author | Raphaël Barrois <raphael.barrois@polyconseil.fr> | 2012-05-16 14:00:44 +0200 |
---|---|---|
committer | Raphaël Barrois <raphael.barrois@polyconseil.fr> | 2012-05-16 14:00:44 +0200 |
commit | 9d9fb70936ed3933431fcdf38131d8837991774e (patch) | |
tree | c5fa22d82676005becca6cf82c5a53dfaa50340a | |
parent | 2d1150000bc51bae7208871a304ab75b137261ba (diff) | |
download | semantic-version-9d9fb70936ed3933431fcdf38131d8837991774e.tar.gz |
Improve doc.
Signed-off-by: Raphaël Barrois <raphael.barrois@polyconseil.fr>
-rw-r--r-- | doc/conf.py | 17 | ||||
-rw-r--r-- | doc/django.rst | 23 | ||||
-rw-r--r-- | doc/index.rst | 65 | ||||
-rw-r--r-- | doc/reference.rst | 244 |
4 files changed, 335 insertions, 14 deletions
diff --git a/doc/conf.py b/doc/conf.py index 94d1fea..ab788e3 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -47,10 +47,19 @@ copyright = u'2012, Raphaël Barrois' # |version| and |release|, also used in various other places throughout the # built documents. # -# The short X.Y version. -version = '1.0' -# The full version, including alpha/beta/rc tags. -release = '1.0.0-alpha' +root_dir = os.path.abspath(os.path.dirname(__file__)) +def get_version(): + import re + version_re = re.compile(r"^__version__ = '([\w_.-]+)'$") + with open(os.path.join(root_dir, os.pardir, 'src', 'semantic_version', '__init__.py')) as f: + for line in f: + match = version_re.match(line[:-1]) + if match: + return match.groups()[0] + return '0.0.0' + +release = get_version() +version = '.'.join(release.split('.')[:2]) # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/doc/django.rst b/doc/django.rst index e69de29..5fc65f8 100644 --- a/doc/django.rst +++ b/doc/django.rst @@ -0,0 +1,23 @@ +Interaction with Django +======================= + +.. module:: semantic_version.django_fields + +The ``python-semanticversion`` package provides two custom fields for Django: + +- :class:`VersionField`: stores a :class:`semantic_version.Version` object +- :class:`SpecField`: stores a :class:`semantic_version.Spec` object + + +.. class:: VersionField + + Stores a :class:`semantic_version.Version`. + + .. attribute:: partial + + Boolean; whether :attr:`~semantic_version.Version.partial` versions are allowed. + + +.. class:: SpecField + + Stores a :class:`semantic_version.Spec`. diff --git a/doc/index.rst b/doc/index.rst index fc8ba9d..dceb265 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -6,7 +6,7 @@ python-semanticversion ====================== -This small python library provides a few tools to handle `SemVer <http://semver.org>`_ in Python. +This small python library provides a few tools to handle `SemVer`_ in Python. The first release (1.0.0) should handle the 2.0.0-rc1 version of the SemVer scheme. @@ -15,6 +15,15 @@ The first release (1.0.0) should handle the 2.0.0-rc1 version of the SemVer sche Getting started =============== +Intall the package from `PyPI`_, using pip:: + + pip install python-semanticversion + + +Import it in your code:: + + import semantic_version + .. currentmodule:: semantic_version This module provides two classes to handle semantic versions: @@ -22,6 +31,8 @@ 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``) +Versions +-------- Defining a :class:`Version` is quite simple:: @@ -67,23 +78,57 @@ Obviously, :class:`Versions <Version>` can be compared:: >>> semantic_version.Version('0.1.1') <= semantic_version.Version('0.1.1-alpha') False -Links -===== -- Package on `PyPI <http://pypi.python.org/>`_: http://pypi.python.org/semantic_version/ -- Doc on `ReadTheDocs <http://readthedocs.org/>`_: http://readthedocs.org/docs/python-semanticversion/ -- Source on `GitHub <http://github.com/>`_: http://github.com/rbarrois/python-semanticversion/ -- Build on `Travis CI <http://travis-ci.org/>`_: http://travis-ci.org/rbarrois/python-semanticversion/ -- Semantic Version specification: http://semver.org/ +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')) + False -Contents: +It is also possible to define 'approximate' version specifications:: + + >>> s = Spec('~0.1') # Matches 0.1.* + >>> s.match(Version('0.1.0-alpha1')) + True + >>> s.match(Version('0.1.9999999999+build99')) + True + >>> s.match(Version('0.2.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 + + +Contents +======== .. toctree:: :maxdepth: 2 - django reference + django + +Links +===== + +- Package on `PyPI`_: http://pypi.python.org/semantic_version/ +- Doc on `ReadTheDocs <http://readthedocs.org/>`_: http://readthedocs.org/docs/python-semanticversion/ +- Source on `GitHub <http://github.com/>`_: http://github.com/rbarrois/python-semanticversion/ +- Build on `Travis CI <http://travis-ci.org/>`_: http://travis-ci.org/rbarrois/python-semanticversion/ +- Semantic Version specification: `SemVer`_ +.. _SemVer: http://semver.org/ +.. _PyPI: http://pypi.python.org/ Indices and tables diff --git a/doc/reference.rst b/doc/reference.rst index e69de29..ba5d71c 100644 --- a/doc/reference.rst +++ b/doc/reference.rst @@ -0,0 +1,244 @@ +Reference +========= + + +.. module:: semantic_version + + +Module-level functions +---------------------- + +.. function:: compare(v1, v2) + + Compare two version strings, and return a result similar to that of :func:`cmp`:: + + >>> compare('0.1.1', '0.1.2') + -1 + >>> compare('0.1.1', '0.1.1') + 0 + >>> compare('0.1.1', '0.1.1-alpha') + 1 + + :param str v1: The first version to compare + :param str v2: The second version to compare + :raises: :exc:`ValueError`, if any version string is invalid + :rtype: ``int``, -1 / 0 / 1 as for a :func:`cmp` comparison + + + +.. function:: match(spec, version) + + Check whether a version string matches a specification string:: + + >>> match('>=0.1.1', '0.1.2') + True + >>> match('>=0.1.1', '0.1.1-alpha') + False + >>> match('~0.1.1', '0.1.1-alpha') + True + + :param str spec: The specification to use, as a string + :param str version: The version string to test against the spec + :raises: :exc:`ValueError`, if the ``spec`` or the ``version`` is invalid + :rtype: ``bool`` + + +Representing a version +---------------------- + +.. class:: Version + + Object representation of a `SemVer`_-compliant version. + + Constructed from a textual version string:: + + >>> Version('1.1.1') + <SemVer(1, 1, 1, [], [])> + >>> str(Version('1.1.1')) + '1.1.1' + + + .. 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. + + .. attribute:: major + + ``int``, the major version number + + .. attribute:: minor + + ``int``, the minor version number. + + May be ``None`` for a :attr:`partial` version number in a ``<major>`` format. + + .. attribute:: patch + + ``int``, the patch version number. + + May be ``None`` for a :attr:`partial` version number in a ``<major>`` or ``<major>.<minor>`` format. + + .. attribute:: prerelease + + ``list`` of ``strings``, the prerelease component. + + It contains the various dot-separated identifiers in the prerelease component. + + May be ``None`` for a :attr:`partial` version number in a ``<major>``, ``<major>.<minor>`` or ``<major>.<minor>.<patch>`` format. + + .. attribute:: build + + ``list`` of ``strings``, the build component. + + It contains the various dot-separated identifiers in the build component. + + May be ``None`` for a :attr:`partial` version number in a ``<major>``, ``<major>.<minor>``, + ``<major>.<minor>.<patch>`` or ``<major>.<minor>.<patch>-<prerelease>`` format. + + + .. rubric:: Methods + + + .. method:: __iter__(self) + + Iterates over the version components (:attr:`major`, :attr:`minor`, + :attr:`patch`, :attr:`prerelease`, :attr:`build`). + + .. method:: __cmp__(self, other) + + Provides comparison methods with other :class:`Version` objects. + + The rules are: + + - For non-:attr:`partial` versions, compare using the `SemVer`_ scheme + - If any compared object is :attr:`partial`, compare using the `SemVer`_ scheme, + but stop at the first component undefined in the :attr:`partial` :class:`Version`; + that is, a component whose value is ``None``. + + + .. method:: __str__(self) + + Returns the standard text representation of the version. + + .. code-block:: pycon + + >>> v = Version('0.1.1-rc2+build4.4') + >>> v + <SemVer(0, 1, 1, ['rc2'], ['build4', '4'])> + >>> str(v) + '0.1.1-rc2+build4.4' + + + .. rubric:: Class methods + + + .. classmethod:: parse(cls, version_string[, partial=False]) + + Parse a version string into a ``(major, minor, patch, prerelease, build)`` tuple. + + :param str version_string: The version string to parse + :param bool partial: Whether this should be considered a :attr:`partial` version + :raises: :exc:`ValueError`, if the :attr:`version_string` is invalid. + :rtype: (major, minor, patch, prerelease, build) + + +Version specifications +---------------------- + + +Version specifications describe a 'range' of accepted versions: +older than, equal, similar to, … + +.. class:: Spec + + Stores a version specification, defined from a string:: + + >>> Spec('>=0.1.1') + <Spec: >= <SemVer(0, 1, 1, [], [])>> + + This allows to test :class:`Version` objects against the :class:`Spec`:: + + >>> Spec('>=0.1.1').match(Version('0.1.1-rc1')) # pre-release have lower precedence + False + >>> Version('0.1.1+build2') in Spec('>=0.1.1') # build version have higher precedence + True + + + .. rubric:: Attributes + + + .. attribute:: kind + + One of :data:`KIND_LT`, :data:`KIND_LTE`, :data:`KIND_EQUAL`, :data:`KIND_GTE`, + :data:`KIND_GT`, :data:`KIND_ALMOST`. + + .. attribute:: spec + + :class:`Version` in the :class:`Spec` description. + + If :attr:`kind` is :data:`KIND_ALMOST`, this will be a :attr:`~Version.partial` :class:`Version`. + + + .. rubric:: Class methods + + + .. classmethod:: parse(cls, requirement_string) + + Retrieve a ``(kind, version)`` tuple from a string. + + :param str requirement_string: The textual description of the specification + :raises: :exc:`ValueError`: if the ``requirement_string`` is invalid. + :rtype: (``kind``, ``version``) tuple + + + .. rubric:: Methods + + + .. method:: match(self, version) + + Test whether a given :class:`Version` matches this :class:`Spec`. + + :param version: The version to test against the spec + :type version: :class:`Version` + :rtype: ``bool`` + + + .. method:: __contains__(self, version) + + Allows the use of the ``version in spec`` syntax. + Simply an alias of the :func:`match` method. + + + .. rubric:: Class attributes + + + .. data:: KIND_LT + + The kind of 'Less than' specifications + + .. data:: KIND_LTE + + The kind of 'Less or equal to' specifications + + .. data:: KIND_EQUAL + + The kind of 'equal to' specifications + + .. data:: KIND_GTE + + The kind of 'Greater or equal to' specifications + + .. data:: KIND_GT + + The kind of 'Greater than' specifications + + .. data:: KIND_ALMOST + + The kind of 'Almost equal to' specifications + + +.. _SemVer: http://semver.org/ |