version.rst (9787B)
1 Version Handling 2 ================ 3 4 .. currentmodule:: packaging.version 5 6 A core requirement of dealing with packages is the ability to work with 7 versions. `PEP 440`_ defines the standard version scheme for Python packages 8 which has been implemented by this module. 9 10 Usage 11 ----- 12 13 .. doctest:: 14 15 >>> from packaging.version import Version, parse 16 >>> v1 = parse("1.0a5") 17 >>> v2 = Version("1.0") 18 >>> v1 19 <Version('1.0a5')> 20 >>> v2 21 <Version('1.0')> 22 >>> v1 < v2 23 True 24 >>> v1.epoch 25 0 26 >>> v1.release 27 (1, 0) 28 >>> v1.pre 29 ('a', 5) 30 >>> v1.is_prerelease 31 True 32 >>> v2.is_prerelease 33 False 34 >>> Version("french toast") 35 Traceback (most recent call last): 36 ... 37 InvalidVersion: Invalid version: 'french toast' 38 >>> Version("1.0").post 39 >>> Version("1.0").is_postrelease 40 False 41 >>> Version("1.0.post0").post 42 0 43 >>> Version("1.0.post0").is_postrelease 44 True 45 46 47 Reference 48 --------- 49 50 .. function:: parse(version) 51 52 This function takes a version string and will parse it as a 53 :class:`Version` if the version is a valid PEP 440 version, otherwise it 54 will parse it as a deprecated :class:`LegacyVersion`. 55 56 57 .. class:: Version(version) 58 59 This class abstracts handling of a project's versions. It implements the 60 scheme defined in `PEP 440`_. A :class:`Version` instance is comparison 61 aware and can be compared and sorted using the standard Python interfaces. 62 63 :param str version: The string representation of a version which will be 64 parsed and normalized before use. 65 :raises InvalidVersion: If the ``version`` does not conform to PEP 440 in 66 any way then this exception will be raised. 67 68 .. attribute:: public 69 70 A string representing the public version portion of this ``Version()``. 71 72 .. attribute:: base_version 73 74 A string representing the base version of this :class:`Version` 75 instance. The base version is the public version of the project without 76 any pre or post release markers. 77 78 .. attribute:: epoch 79 80 An integer giving the version epoch of this :class:`Version` instance 81 82 .. attribute:: release 83 84 A tuple of integers giving the components of the release segment of 85 this :class:`Version` instance; that is, the ``1.2.3`` part of the 86 version number, including trailing zeroes but not including the epoch 87 or any prerelease/development/postrelease suffixes 88 89 .. attribute:: major 90 91 An integer representing the first item of :attr:`release` or ``0`` if unavailable. 92 93 .. attribute:: minor 94 95 An integer representing the second item of :attr:`release` or ``0`` if unavailable. 96 97 .. attribute:: micro 98 99 An integer representing the third item of :attr:`release` or ``0`` if unavailable. 100 101 .. attribute:: local 102 103 A string representing the local version portion of this ``Version()`` 104 if it has one, or ``None`` otherwise. 105 106 .. attribute:: pre 107 108 If this :class:`Version` instance represents a prerelease, this 109 attribute will be a pair of the prerelease phase (the string ``"a"``, 110 ``"b"``, or ``"rc"``) and the prerelease number (an integer). If this 111 instance is not a prerelease, the attribute will be `None`. 112 113 .. attribute:: is_prerelease 114 115 A boolean value indicating whether this :class:`Version` instance 116 represents a prerelease and/or development release. 117 118 .. attribute:: dev 119 120 If this :class:`Version` instance represents a development release, 121 this attribute will be the development release number (an integer); 122 otherwise, it will be `None`. 123 124 .. attribute:: is_devrelease 125 126 A boolean value indicating whether this :class:`Version` instance 127 represents a development release. 128 129 .. attribute:: post 130 131 If this :class:`Version` instance represents a postrelease, this 132 attribute will be the postrelease number (an integer); otherwise, it 133 will be `None`. 134 135 .. attribute:: is_postrelease 136 137 A boolean value indicating whether this :class:`Version` instance 138 represents a post-release. 139 140 141 .. class:: LegacyVersion(version) 142 143 .. deprecated:: 20.5 144 145 Use :class:`Version` instead. 146 147 This class abstracts handling of a project's versions if they are not 148 compatible with the scheme defined in `PEP 440`_. It implements a similar 149 interface to that of :class:`Version`. 150 151 This class implements the previous de facto sorting algorithm used by 152 setuptools, however it will always sort as less than a :class:`Version` 153 instance. 154 155 :param str version: The string representation of a version which will be 156 used as is. 157 158 .. note:: 159 160 :class:`LegacyVersion` instances are always ordered lower than :class:`Version` instances. 161 162 >>> from packaging.version import Version, LegacyVersion 163 >>> v1 = Version("1.0") 164 >>> v2 = LegacyVersion("1.0") 165 >>> v1 > v2 166 True 167 >>> v3 = LegacyVersion("1.3") 168 >>> v1 > v3 169 True 170 171 Also note that some strings are still valid PEP 440 strings (:class:`Version`), even if they look very similar to 172 other versions that are not (:class:`LegacyVersion`). Examples include versions with `Pre-release spelling`_ and 173 `Post-release spelling`_. 174 175 >>> from packaging.version import parse 176 >>> v1 = parse('0.9.8a') 177 >>> v2 = parse('0.9.8beta') 178 >>> v3 = parse('0.9.8r') 179 >>> v4 = parse('0.9.8rev') 180 >>> v5 = parse('0.9.8t') 181 >>> v1 182 <Version('0.9.8a0')> 183 >>> v1.is_prerelease 184 True 185 >>> v2 186 <Version('0.9.8b0')> 187 >>> v2.is_prerelease 188 True 189 >>> v3 190 <Version('0.9.8.post0')> 191 >>> v3.is_postrelease 192 True 193 >>> v4 194 <Version('0.9.8.post0')> 195 >>> v4.is_postrelease 196 True 197 >>> v5 198 <LegacyVersion('0.9.8t')> 199 >>> v5.is_prerelease 200 False 201 >>> v5.is_postrelease 202 False 203 204 .. attribute:: public 205 206 A string representing the public version portion of this 207 :class:`LegacyVersion`. This will always be the entire version string. 208 209 .. attribute:: base_version 210 211 A string representing the base version portion of this 212 :class:`LegacyVersion` instance. This will always be the entire version 213 string. 214 215 .. attribute:: epoch 216 217 This will always be ``-1`` since without `PEP 440`_ we do not have the 218 concept of version epochs. The value reflects the fact that 219 :class:`LegacyVersion` instances always compare less than 220 :class:`Version` instances. 221 222 .. attribute:: release 223 224 This will always be ``None`` since without `PEP 440`_ we do not have 225 the concept of a release segment or its components. It exists 226 primarily to allow a :class:`LegacyVersion` to be used as a stand in 227 for a :class:`Version`. 228 229 .. attribute:: local 230 231 This will always be ``None`` since without `PEP 440`_ we do not have 232 the concept of a local version. It exists primarily to allow a 233 :class:`LegacyVersion` to be used as a stand in for a :class:`Version`. 234 235 .. attribute:: pre 236 237 This will always be ``None`` since without `PEP 440`_ we do not have 238 the concept of a prerelease. It exists primarily to allow a 239 :class:`LegacyVersion` to be used as a stand in for a :class:`Version`. 240 241 .. attribute:: is_prerelease 242 243 A boolean value indicating whether this :class:`LegacyVersion` 244 represents a prerelease and/or development release. Since without 245 `PEP 440`_ there is no concept of pre or dev releases this will 246 always be `False` and exists for compatibility with :class:`Version`. 247 248 .. attribute:: dev 249 250 This will always be ``None`` since without `PEP 440`_ we do not have 251 the concept of a development release. It exists primarily to allow a 252 :class:`LegacyVersion` to be used as a stand in for a :class:`Version`. 253 254 .. attribute:: is_devrelease 255 256 A boolean value indicating whether this :class:`LegacyVersion` 257 represents a development release. Since without `PEP 440`_ there is 258 no concept of dev releases this will always be `False` and exists for 259 compatibility with :class:`Version`. 260 261 .. attribute:: post 262 263 This will always be ``None`` since without `PEP 440`_ we do not have 264 the concept of a postrelease. It exists primarily to allow a 265 :class:`LegacyVersion` to be used as a stand in for a :class:`Version`. 266 267 .. attribute:: is_postrelease 268 269 A boolean value indicating whether this :class:`LegacyVersion` 270 represents a post-release. Since without `PEP 440`_ there is no concept 271 of post-releases this will always be ``False`` and exists for 272 compatibility with :class:`Version`. 273 274 275 .. exception:: InvalidVersion 276 277 Raised when attempting to create a :class:`Version` with a version string 278 that does not conform to `PEP 440`_. 279 280 281 .. data:: VERSION_PATTERN 282 283 A string containing the regular expression used to match a valid version. 284 The pattern is not anchored at either end, and is intended for embedding 285 in larger expressions (for example, matching a version number as part of 286 a file name). The regular expression should be compiled with the 287 ``re.VERBOSE`` and ``re.IGNORECASE`` flags set. 288 289 290 .. _PEP 440: https://www.python.org/dev/peps/pep-0440/ 291 .. _Pre-release spelling : https://www.python.org/dev/peps/pep-0440/#pre-release-spelling 292 .. _Post-release spelling : https://www.python.org/dev/peps/pep-0440/#post-release-spelling