File: version.rst

package info (click to toggle)
python-packaging 19.0-1
  • links: PTS
  • area: main
  • in suites: buster
  • size: 432 kB
  • sloc: python: 3,358; makefile: 127
file content (228 lines) | stat: -rw-r--r-- 7,834 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
Version Handling
================

.. currentmodule:: packaging.version

A core requirement of dealing with packages is the ability to work with
versions. `PEP 440`_ defines the standard version scheme for Python packages
which has been implemented by this module.

Usage
-----

.. doctest::

    >>> from packaging.version import Version, parse
    >>> v1 = parse("1.0a5")
    >>> v2 = Version("1.0")
    >>> v1
    <Version('1.0a5')>
    >>> v2
    <Version('1.0')>
    >>> v1 < v2
    True
    >>> v1.epoch
    0
    >>> v1.release
    (1, 0)
    >>> v1.pre
    ('a', 5)
    >>> v1.is_prerelease
    True
    >>> v2.is_prerelease
    False
    >>> Version("french toast")
    Traceback (most recent call last):
        ...
    InvalidVersion: Invalid version: 'french toast'
    >>> Version("1.0").post
    >>> Version("1.0").is_postrelease
    False
    >>> Version("1.0.post0").post
    0
    >>> Version("1.0.post0").is_postrelease
    True


Reference
---------

.. function:: parse(version)

    This function takes a version string and will parse it as a
    :class:`Version` if the version is a valid PEP 440 version, otherwise it
    will parse it as a :class:`LegacyVersion`.


.. class:: Version(version)

    This class abstracts handling of a project's versions. It implements the
    scheme defined in `PEP 440`_. A :class:`Version` instance is comparison
    aware and can be compared and sorted using the standard Python interfaces.

    :param str version: The string representation of a version which will be
                        parsed and normalized before use.
    :raises InvalidVersion: If the ``version`` does not conform to PEP 440 in
                            any way then this exception will be raised.

    .. attribute:: public

        A string representing the public version portion of this ``Version()``.

    .. attribute:: base_version

        A string representing the base version of this :class:`Version`
        instance. The base version is the public version of the project without
        any pre or post release markers.

    .. attribute:: epoch

        An integer giving the version epoch of this :class:`Version` instance

    .. attribute:: release

        A tuple of integers giving the components of the release segment of
        this :class:`Version` instance; that is, the ``1.2.3`` part of the
        version number, including trailing zeroes but not including the epoch
        or any prerelease/development/postrelease suffixes

    .. attribute:: local

        A string representing the local version portion of this ``Version()``
        if it has one, or ``None`` otherwise.

    .. attribute:: pre

        If this :class:`Version` instance represents a prerelease, this
        attribute will be a pair of the prerelease phase (the string ``"a"``,
        ``"b"``, or ``"rc"``) and the prerelease number (an integer).  If this
        instance is not a prerelease, the attribute will be `None`.

    .. attribute:: is_prerelease

        A boolean value indicating whether this :class:`Version` instance
        represents a prerelease and/or development release.

    .. attribute:: dev

        If this :class:`Version` instance represents a development release,
        this attribute will be the development release number (an integer);
        otherwise, it will be `None`.

    .. attribute:: is_devrelease

        A boolean value indicating whether this :class:`Version` instance
        represents a development release.

    .. attribute:: post

        If this :class:`Version` instance represents a postrelease, this
        attribute will be the postrelease number (an integer); otherwise, it
        will be `None`.

    .. attribute:: is_postrelease

        A boolean value indicating whether this :class:`Version` instance
        represents a post-release.


.. class:: LegacyVersion(version)

    This class abstracts handling of a project's versions if they are not
    compatible with the scheme defined in `PEP 440`_. It implements a similar
    interface to that of :class:`Version`.

    This class implements the previous de facto sorting algorithm used by
    setuptools, however it will always sort as less than a :class:`Version`
    instance.

    :param str version: The string representation of a version which will be
                        used as is.

    .. attribute:: public

        A string representing the public version portion of this
        :class:`LegacyVersion`. This will always be the entire version string.

    .. attribute:: base_version

        A string representing the base version portion of this
        :class:`LegacyVersion` instance. This will always be the entire version
        string.

    .. attribute:: epoch

        This will always be ``-1`` since without `PEP 440`_ we do not have the
        concept of version epochs.  The value reflects the fact that
        :class:`LegacyVersion` instances always compare less than
        :class:`Version` instances.

    .. attribute:: release

        This will always be ``None`` since without `PEP 440`_ we do not have
        the concept of a release segment or its components.  It exists
        primarily to allow a :class:`LegacyVersion` to be used as a stand in
        for a :class:`Version`.

    .. attribute:: local

        This will always be ``None`` since without `PEP 440`_ we do not have
        the concept of a local version. It exists primarily to allow a
        :class:`LegacyVersion` to be used as a stand in for a :class:`Version`.

    .. attribute:: pre

        This will always be ``None`` since without `PEP 440`_ we do not have
        the concept of a prerelease. It exists primarily to allow a
        :class:`LegacyVersion` to be used as a stand in for a :class:`Version`.

    .. attribute:: is_prerelease

        A boolean value indicating whether this :class:`LegacyVersion`
        represents a prerelease and/or development release.  Since without
        `PEP 440`_ there is no concept of pre or dev releases this will
        always be `False` and exists for compatibility with :class:`Version`.

    .. attribute:: dev

        This will always be ``None`` since without `PEP 440`_ we do not have
        the concept of a development release. It exists primarily to allow a
        :class:`LegacyVersion` to be used as a stand in for a :class:`Version`.

    .. attribute:: is_devrelease

        A boolean value indicating whether this :class:`LegacyVersion`
        represents a development release.  Since without `PEP 440`_ there is
        no concept of dev releases this will always be `False` and exists for
        compatibility with :class:`Version`.

    .. attribute:: post

        This will always be ``None`` since without `PEP 440`_ we do not have
        the concept of a postrelease. It exists primarily to allow a
        :class:`LegacyVersion` to be used as a stand in for a :class:`Version`.

    .. attribute:: is_postrelease

        A boolean value indicating whether this :class:`LegacyVersion`
        represents a post-release. Since without `PEP 440`_ there is no concept
        of post-releases this will always be ``False`` and exists for
        compatibility with :class:`Version`.


.. exception:: InvalidVersion

    Raised when attempting to create a :class:`Version` with a version string
    that does not conform to `PEP 440`_.


.. data:: VERSION_PATTERN

    A string containing the regular expression used to match a valid version.
    The pattern is not anchored at either end, and is intended for embedding
    in larger expressions (for example, matching a version number as part of
    a file name). The regular expression should be compiled with the
    ``re.VERBOSE`` and ``re.IGNORECASE`` flags set.


.. _`PEP 440`: https://www.python.org/dev/peps/pep-0440/