specifiers.rst (8343B)
1 Specifiers 2 ========== 3 4 .. currentmodule:: packaging.specifiers 5 6 A core requirement of dealing with dependencies is the ability to specify what 7 versions of a dependency are acceptable for you. `PEP 440`_ defines the 8 standard specifier scheme which has been implemented by this module. 9 10 Usage 11 ----- 12 13 .. doctest:: 14 15 >>> from packaging.specifiers import SpecifierSet 16 >>> from packaging.version import Version 17 >>> spec1 = SpecifierSet("~=1.0") 18 >>> spec1 19 <SpecifierSet('~=1.0')> 20 >>> spec2 = SpecifierSet(">=1.0") 21 >>> spec2 22 <SpecifierSet('>=1.0')> 23 >>> # We can combine specifiers 24 >>> combined_spec = spec1 & spec2 25 >>> combined_spec 26 <SpecifierSet('>=1.0,~=1.0')> 27 >>> # We can also implicitly combine a string specifier 28 >>> combined_spec &= "!=1.1" 29 >>> combined_spec 30 <SpecifierSet('!=1.1,>=1.0,~=1.0')> 31 >>> # Create a few versions to check for contains. 32 >>> v1 = Version("1.0a5") 33 >>> v2 = Version("1.0") 34 >>> # We can check a version object to see if it falls within a specifier 35 >>> v1 in combined_spec 36 False 37 >>> v2 in combined_spec 38 True 39 >>> # We can even do the same with a string based version 40 >>> "1.4" in combined_spec 41 True 42 >>> # Finally we can filter a list of versions to get only those which are 43 >>> # contained within our specifier. 44 >>> list(combined_spec.filter([v1, v2, "1.4"])) 45 [<Version('1.0')>, '1.4'] 46 47 48 Reference 49 --------- 50 51 .. class:: SpecifierSet(specifiers="", prereleases=None) 52 53 This class abstracts handling specifying the dependencies of a project. It 54 can be passed a single specifier (``>=3.0``), a comma-separated list of 55 specifiers (``>=3.0,!=3.1``), or no specifier at all. Each individual 56 specifier will be attempted to be parsed as a PEP 440 specifier 57 (:class:`Specifier`) or as a legacy, setuptools style specifier 58 (deprecated :class:`LegacySpecifier`). You may combine 59 :class:`SpecifierSet` instances using the ``&`` operator 60 (``SpecifierSet(">2") & SpecifierSet("<4")``). 61 62 Both the membership tests and the combination support using raw strings 63 in place of already instantiated objects. 64 65 :param str specifiers: The string representation of a specifier or a 66 comma-separated list of specifiers which will 67 be parsed and normalized before use. 68 :param bool prereleases: This tells the SpecifierSet if it should accept 69 prerelease versions if applicable or not. The 70 default of ``None`` will autodetect it from the 71 given specifiers. 72 :raises InvalidSpecifier: If the given ``specifiers`` are not parseable 73 than this exception will be raised. 74 75 .. attribute:: prereleases 76 77 A boolean value indicating whether this :class:`SpecifierSet` 78 represents a specifier that includes a pre-release versions. This can be 79 set to either ``True`` or ``False`` to explicitly enable or disable 80 prereleases or it can be set to ``None`` (the default) to enable 81 autodetection. 82 83 .. method:: __contains__(version) 84 85 This is the more Pythonic version of :meth:`contains()`, but does 86 not allow you to override the ``prereleases`` argument. If you 87 need that, use :meth:`contains()`. 88 89 See :meth:`contains()`. 90 91 .. method:: contains(version, prereleases=None) 92 93 Determines if ``version``, which can be either a version string, a 94 :class:`Version`, or a deprecated :class:`LegacyVersion` object, is 95 contained within this set of specifiers. 96 97 This will either match or not match prereleases based on the 98 ``prereleases`` parameter. When ``prereleases`` is set to ``None`` 99 (the default) it will use the ``Specifier().prereleases`` attribute to 100 determine if to allow them. Otherwise it will use the boolean value of 101 the passed in value to determine if to allow them or not. 102 103 .. method:: __len__() 104 105 Returns the number of specifiers in this specifier set. 106 107 .. method:: __iter__() 108 109 Returns an iterator over all the underlying :class:`Specifier` (or 110 deprecated :class:`LegacySpecifier`) instances in this specifier set. 111 112 .. method:: filter(iterable, prereleases=None) 113 114 Takes an iterable that can contain version strings, :class:`~.Version`, 115 and deprecated :class:`~.LegacyVersion` instances and will then filter 116 it, returning an iterable that contains only items which match the 117 rules of this specifier object. 118 119 This method is smarter than just 120 ``filter(Specifier().contains, [...])`` because it implements the rule 121 from PEP 440 where a prerelease item SHOULD be accepted if no other 122 versions match the given specifier. 123 124 The ``prereleases`` parameter functions similarly to that of the same 125 parameter in ``contains``. If the value is ``None`` (the default) then 126 it will intelligently decide if to allow prereleases based on the 127 specifier, the ``Specifier().prereleases`` value, and the PEP 440 128 rules. Otherwise it will act as a boolean which will enable or disable 129 all prerelease versions from being included. 130 131 132 .. class:: Specifier(specifier, prereleases=None) 133 134 This class abstracts the handling of a single `PEP 440`_ compatible 135 specifier. It is generally not required to instantiate this manually, 136 preferring instead to work with :class:`SpecifierSet`. 137 138 :param str specifier: The string representation of a specifier which will 139 be parsed and normalized before use. 140 :param bool prereleases: This tells the specifier if it should accept 141 prerelease versions if applicable or not. The 142 default of ``None`` will autodetect it from the 143 given specifiers. 144 :raises InvalidSpecifier: If the ``specifier`` does not conform to PEP 440 145 in any way then this exception will be raised. 146 147 .. attribute:: operator 148 149 The string value of the operator part of this specifier. 150 151 .. attribute:: version 152 153 The string version of the version part of this specifier. 154 155 .. attribute:: prereleases 156 157 See :attr:`SpecifierSet.prereleases`. 158 159 .. method:: __contains__(version) 160 161 See :meth:`SpecifierSet.__contains__()`. 162 163 .. method:: contains(version, prereleases=None) 164 165 See :meth:`SpecifierSet.contains()`. 166 167 .. method:: filter(iterable, prereleases=None) 168 169 See :meth:`SpecifierSet.filter()`. 170 171 172 .. class:: LegacySpecifier(specifier, prereleases=None) 173 174 .. deprecated:: 20.5 175 176 Use :class:`Specifier` instead. 177 178 This class abstracts the handling of a single legacy, setuptools style 179 specifier. It is generally not required to instantiate this manually, 180 preferring instead to work with :class:`SpecifierSet`. 181 182 :param str specifier: The string representation of a specifier which will 183 be parsed and normalized before use. 184 :param bool prereleases: This tells the specifier if it should accept 185 prerelease versions if applicable or not. The 186 default of ``None`` will autodetect it from the 187 given specifiers. 188 :raises InvalidSpecifier: If the ``specifier`` is not parseable then this 189 will be raised. 190 191 .. attribute:: operator 192 193 The string value of the operator part of this specifier. 194 195 .. attribute:: version 196 197 The string version of the version part of this specifier. 198 199 .. attribute:: prereleases 200 201 See :attr:`SpecifierSet.prereleases`. 202 203 .. method:: __contains__(version) 204 205 See :meth:`SpecifierSet.__contains__()`. 206 207 .. method:: contains(version, prereleases=None) 208 209 See :meth:`SpecifierSet.contains()`. 210 211 .. method:: filter(iterable, prereleases=None) 212 213 See :meth:`SpecifierSet.filter()`. 214 215 216 .. exception:: InvalidSpecifier 217 218 Raised when attempting to create a :class:`Specifier` with a specifier 219 string that does not conform to `PEP 440`_. 220 221 222 .. _`PEP 440`: https://www.python.org/dev/peps/pep-0440/