Fix #235: Shift focus on semver.VersionInfo.*

tomschr · tomschr · commit b145931366a0 · 2020-04-19T12:23:09.000+02:00
* Module level functions like `semver.bump_version` are still available in the documentation, but they play a much less important role now. The preferred way is to use semver.Versioninfo instances to use. * Replace 2.9.2 -> 2.10.0 due to #237 * Fix docstring examples
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -6,7 +6,7 @@ Change Log
 All notable changes to this code base will be documented in this file,
 in every released version.
 
-Version 2.9.x (WIP)
+Version 2.10.0 (WIP)
 ===================
 
 :Released: 2020-xx-yy
@@ -15,6 +15,10 @@ Version 2.9.x (WIP)
 Features
 --------
 
+* :pr:`235`: Improved documentation and shift focus on ``semver.VersionInfo`` instead of advertising
+  the old and deprecated module-level functions.
+
+
 Bug Fixes
 ---------
 
diff --git a/README.rst b/README.rst
@@ -9,18 +9,23 @@ A Python module for `semantic versioning`_. Simplifies comparing versions.
 
 .. teaser-end
 
-.. note::
+.. warning::
 
-   With version 2.9.0 we've moved the GitHub project. The project is now
-   located under the organization ``python-semver``.
-   The complete URL is::
+   As anything comes to an end, this project will focus on Python 3.x only.
+   New features and bugfixes will be integrated into the 3.x.y branch only.
 
-       https://github.com/python-semver/python-semver
+   Major version 3 of semver will contain some incompatible changes:
 
-   If you still have an old repository, correct your upstream URL to the new URL::
+   * removes support for Python 2.7 and 3.3
+   * removes deprecated functions (see :ref:`sec_replace_deprecated_functions` for
+     further information).
 
-       $ git remote set-url upstream git@github.com:python-semver/python-semver.git
+   The last version of semver which supports Python 2.7 and 3.4 will be
+   2.10.x. However, keep in mind, version 2.10.x is frozen: no new
+   features nor backports will be integrated.
 
+   We recommend to upgrade your workflow to Python 3.x to gain support,
+   bugfixes, and new features.
 
 The module follows the ``MAJOR.MINOR.PATCH`` style:
 
@@ -30,55 +35,36 @@ The module follows the ``MAJOR.MINOR.PATCH`` style:
 
 Additional labels for pre-release and build metadata are supported.
 
-
-.. warning::
-
-   Major version 3.0.0 of semver will remove support for Python 2.7 and 3.4.
-
-   As anything comes to an end, this project will focus on Python 3.x.
-   New features and bugfixes will be integrated only into the 3.x.y branch
-   of semver.
-
-   The last version of semver which supports Python 2.7 and 3.4 will be
-   2.9.x. However, keep in mind, version 2.9.x is frozen: no new
-   features nor backports will be integrated.
-
-   We recommend to upgrade your workflow to Python 3.x to gain support,
-   bugfixes, and new features.
-
-
 To import this library, use:
 
 .. code-block:: python
 
     >>> import semver
 
 Working with the library is quite straightforward. To turn a version string into the
-different parts, use the `semver.parse` function:
+different parts, use the ``semver.VersionInfo.parse`` function:
 
 .. code-block:: python
 
-    >>> ver = semver.parse('1.2.3-pre.2+build.4')
-    >>> ver['major']
+    >>> ver = semver.VersionInfo.parse('1.2.3-pre.2+build.4')
+    >>> ver.major
     1
-    >>> ver['minor']
+    >>> ver.minor
     2
-    >>> ver['patch']
+    >>> ver.patch
     3
-    >>> ver['prerelease']
+    >>> ver.prerelease
     'pre.2'
-    >>> ver['build']
+    >>> ver.build
     'build.4'
 
 To raise parts of a version, there are a couple of functions available for
-you. The `semver.parse_version_info` function converts a version string
-into a `semver.VersionInfo` class. The function
-`semver.VersionInfo.bump_major` leaves the original object untouched, but
-returns a new `semver.VersionInfo` instance with the raised major part:
+you. The function :func:`semver.VersionInfo.bump_major` leaves the original object untouched, but
+returns a new :class:`semver.VersionInfo` instance with the raised major part:
 
 .. code-block:: python
 
-    >>> ver = semver.parse_version_info("3.4.5")
+    >>> ver = semver.VersionInfo.parse("3.4.5")
     >>> ver.bump_major()
     VersionInfo(major=4, minor=0, patch=0, prerelease=None, build=None)
 
diff --git a/docs/pysemver.rst b/docs/pysemver.rst
@@ -10,8 +10,7 @@ Synopsis
 
 .. code:: bash
 
-   pysemver compare <VERSION1> <VERSION2>
-   pysemver bump {major,minor,patch,prerelease,build} <VERSION>
+   pysemver <COMMAND> <OPTION>...
 
 
 Description
@@ -52,7 +51,7 @@ Bump a version.
 
 .. option:: <PART>
 
-    The part to bump. Valid strings can be ``major``, ``minor``,
+    The part to bump. Valid strings are ``major``, ``minor``,
     ``patch``, ``prerelease``, or ``build``. The part has the
     following effects:
 
diff --git a/docs/usage.rst b/docs/usage.rst
@@ -1,11 +1,8 @@
 Using semver
 ============
 
-The ``semver`` module can store a version in different types:
-
-* as a string.
-* as :class:`semver.VersionInfo`, a dedicated class for a version type.
-* as a dictionary.
+The ``semver`` module can store a version in the :class:`semver.VersionInfo` class.
+For historical reasons, a version can be also stored as a string or dictionary.
 
 Each type can be converted into the other, if the minimum requirements
 are met.
@@ -32,23 +29,22 @@ creating a version:
 * through an object oriented approach with the :class:`semver.VersionInfo`
   class. This is the preferred method when using semver.
 
-* through module level functions and builtin datatypes (usually strings
-  and dicts).
-  These method are still available for compatibility reasons, but are
-  marked as deprecated. Using one of these will emit a DeprecationWarning.
+* through module level functions and builtin datatypes (usually string
+  and dict).
+  This method is still available for compatibility reasons, but are
+  marked as deprecated. Using it will emit a :class:`DeprecationWarning`.
 
 
 .. warning:: **Deprecation Warning**
 
-    Module level functions are marked as *deprecated* in version 2.9.2 now.
+    Module level functions are marked as *deprecated* in version 2.10.0 now.
     These functions will be removed in semver 3.
     For details, see the sections :ref:`sec_replace_deprecated_functions` and
     :ref:`sec_display_deprecation_warnings`.
 
 
 A :class:`semver.VersionInfo` instance can be created in different ways:
 
-
 * From a string::
 
     >>> semver.VersionInfo.parse("3.4.5-pre.2+build.4")
@@ -173,6 +169,8 @@ If you do, you get an ``AttributeError``::
     ...
     AttributeError: attribute 'minor' is readonly
 
+If you need to replace different parts of a version, refer to section :ref:`sec.replace.parts`.
+
 In case you need the different parts of a version stepwise, iterate over the :class:`semver.VersionInfo` instance::
 
     >>> for item in semver.VersionInfo.parse("3.4.5-pre.2+build.4"):
@@ -186,24 +184,25 @@ In case you need the different parts of a version stepwise, iterate over the :cl
     [3, 4, 5, 'pre.2', 'build.4']
 
 
+.. _sec.replace.parts:
+
 Replacing Parts of a Version
 ----------------------------
 
 If you want to replace different parts of a version, but leave other parts
-unmodified, use one of the functions :func:`semver.replace` or
-:func:`semver.VersionInfo.replace`:
-
-* From a version string::
-
-   >>> semver.replace("1.4.5-pre.1+build.6", major=2)
-   '2.4.5-pre.1+build.6'
+unmodified, use the function :func:`semver.VersionInfo.replace` or :func:`semver.replace`:
 
 * From a :class:`semver.VersionInfo` instance::
 
    >>> version = semver.VersionInfo.parse("1.4.5-pre.1+build.6")
    >>> version.replace(major=2, minor=2)
    VersionInfo(major=2, minor=2, patch=5, prerelease='pre.1', build='build.6')
 
+* From a version string::
+
+   >>> semver.replace("1.4.5-pre.1+build.6", major=2)
+   '2.4.5-pre.1+build.6'
+
 If you pass invalid keys you get an exception::
 
    >>> semver.replace("1.2.3", invalidkey=2)
@@ -251,29 +250,31 @@ Increasing Parts of a Version
 The ``semver`` module contains the following functions to raise parts of
 a version:
 
-* :func:`semver.bump_major`: raises the major part and set all other parts to
+* :func:`semver.VersionInfo.bump_major`: raises the major part and set all other parts to
   zero. Set ``prerelease`` and ``build`` to ``None``.
-* :func:`semver.bump_minor`: raises the minor part and sets ``patch`` to zero.
+* :func:`semver.VersionInfo.bump_minor`: raises the minor part and sets ``patch`` to zero.
   Set ``prerelease`` and ``build`` to ``None``.
-* :func:`semver.bump_patch`: raises the patch part. Set ``prerelease`` and
+* :func:`semver.VersionInfo.bump_patch`: raises the patch part. Set ``prerelease`` and
   ``build`` to ``None``.
-* :func:`semver.bump_prerelease`: raises the prerelease part and set
+* :func:`semver.VersionInfo.bump_prerelease`: raises the prerelease part and set
   ``build`` to ``None``.
-* :func:`semver.bump_build`: raises the build part.
+* :func:`semver.VersionInfo.bump_build`: raises the build part.
 
 .. code-block:: python
 
-    >>> semver.bump_major("3.4.5-pre.2+build.4")
+    >>> str(semver.VersionInfo.parse("3.4.5-pre.2+build.4").bump_major())
     '4.0.0'
-    >>> semver.bump_minor("3.4.5-pre.2+build.4")
+    >>> str(semver.VersionInfo.parse("3.4.5-pre.2+build.4").bump_minor())
     '3.5.0'
-    >>> semver.bump_patch("3.4.5-pre.2+build.4")
+    >>> str(semver.VersionInfo.parse("3.4.5-pre.2+build.4").bump_patch())
     '3.4.6'
-    >>> semver.bump_prerelease("3.4.5-pre.2+build.4")
+    >>> str(semver.VersionInfo.parse("3.4.5-pre.2+build.4").bump_prerelease())
     '3.4.5-pre.3'
-    >>> semver.bump_build("3.4.5-pre.2+build.4")
+    >>> str(semver.VersionInfo.parse("3.4.5-pre.2+build.4").bump_build())
     '3.4.5-pre.2+build.5'
 
+Likewise the module level functions :func:`semver.bump_major`.
+
 
 Comparing Versions
 ------------------
@@ -405,11 +406,12 @@ For example:
 Replacing Deprecated Functions
 ------------------------------
 
-The development team of semver has decided to deprecate certain functions on
-the module level. The preferred way of using semver is through the
-:class:`semver.VersionInfo` class.
+.. versionchanged:: 2.10.0
+   The development team of semver has decided to deprecate certain functions on
+   the module level. The preferred way of using semver is through the
+   :class:`semver.VersionInfo` class.
 
-The deprecated functions can still be used in version 2.x.y. In version 3 of
+The deprecated functions can still be used in version 2.10.0 and above. In version 3 of
 semver, the deprecated functions will be removed.
 
 The following list shows the deprecated functions and how you can replace
diff --git a/semver.py b/semver.py
