openstack/deb-python-semantic-version
Code Issues Proposed changes

Improve doc.

Browse Source 
Signed-off-by: Raphaël Barrois <raphael.barrois@polyconseil.fr>
This commit is contained in:
Raphaël Barrois
2012-05-16 14:00:44 +02:00
parent 2d1150000b
commit 9d9fb70936
4 changed files with 335 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
doc/conf.py
View File

@@ -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.

23
doc/django.rst
View File

@@ -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`.

65
doc/index.rst
View File

@@ -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
-------------------------
Contents:
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
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

244
doc/reference.rst
View File

@@ -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/