Skip to content

Shift focus on semver.VersionInfo.* functions #235

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 20, 2020
Merged

Shift focus on semver.VersionInfo.* functions #235

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion CHANGELOG.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
---------

Expand Down
58 changes: 22 additions & 36 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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)

Expand Down
5 changes: 2 additions & 3 deletions docs/pysemver.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,7 @@ Synopsis

.. code:: bash

pysemver compare <VERSION1> <VERSION2>
pysemver bump {major,minor,patch,prerelease,build} <VERSION>
pysemver <COMMAND> <OPTION>...


Description
Expand Down Expand Up @@ -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:

Expand Down
66 changes: 34 additions & 32 deletions docs/usage.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Expand All @@ -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")
Expand Down Expand Up @@ -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"):
Expand All @@ -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)
Expand Down Expand Up @@ -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
------------------
Expand Down Expand Up @@ -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
Expand Down
Loading