Specifiers¶
A core requirement of dealing with dependencies is the ability to specify what versions of a dependency are acceptable for you. PEP 440 defines the standard specifier scheme which has been implemented by this module.
Usage¶
>>> from packaging.specifiers import SpecifierSet
>>> from packaging.version import Version
>>> spec1 = SpecifierSet("~=1.0")
>>> spec1
<SpecifierSet('~=1.0')>
>>> spec2 = SpecifierSet(">=1.0")
>>> spec2
<SpecifierSet('>=1.0')>
>>> # We can combine specifiers
>>> combined_spec = spec1 & spec2
>>> combined_spec
<SpecifierSet('>=1.0,~=1.0')>
>>> # We can also implicitly combine a string specifier
>>> combined_spec &= "!=1.1"
>>> combined_spec
<SpecifierSet('!=1.1,>=1.0,~=1.0')>
>>> # Create a few versions to check for contains.
>>> v1 = Version("1.0a5")
>>> v2 = Version("1.0")
>>> # We can check a version object to see if it falls within a specifier
>>> v1 in combined_spec
False
>>> v2 in combined_spec
True
>>> # We can even do the same with a string based version
>>> "1.4" in combined_spec
True
>>> # Finally we can filter a list of versions to get only those which are
>>> # contained within our specifier.
>>> list(combined_spec.filter([v1, v2, "1.4"]))
[<Version('1.0')>, '1.4']
Reference¶
-
class
packaging.specifiers.
SpecifierSet
(specifiers, prereleases=None)[source]¶ This class abstracts handling specifying the dependencies of a project. It can be passed a single specifier (
>=3.0
), a comma-separated list of specifiers (>=3.0,!=3.1
), or no specifier at all. Each individual specifier will be attempted to be parsed as a PEP 440 specifier (Specifier
) or as a legacy, setuptools style specifier (deprecatedLegacySpecifier
). You may combineSpecifierSet
instances using the&
operator (SpecifierSet(">2") & SpecifierSet("<4")
).Both the membership tests and the combination support using raw strings in place of already instantiated objects.
- Parameters
specifiers (str) – The string representation of a specifier or a comma-separated list of specifiers which will be parsed and normalized before use.
prereleases (bool) – This tells the SpecifierSet if it should accept prerelease versions if applicable or not. The default of
None
will autodetect it from the given specifiers.
- Raises
InvalidSpecifier – If the given
specifiers
are not parseable than this exception will be raised.
-
prereleases
¶ A boolean value indicating whether this
SpecifierSet
represents a specifier that includes a pre-release versions. This can be set to eitherTrue
orFalse
to explicitly enable or disable prereleases or it can be set toNone
(the default) to enable autodetection.
-
__contains__
(version)[source]¶ This is the more Pythonic version of
contains()
, but does not allow you to override theprereleases
argument. If you need that, usecontains()
.See
contains()
.
-
contains
(version, prereleases=None)[source]¶ Determines if
version
, which can be either a version string, aVersion
, or a deprecatedLegacyVersion
object, is contained within this set of specifiers.This will either match or not match prereleases based on the
prereleases
parameter. Whenprereleases
is set toNone
(the default) it will use theSpecifier().prereleases
attribute to determine if to allow them. Otherwise it will use the boolean value of the passed in value to determine if to allow them or not.
-
__iter__
()[source]¶ Returns an iterator over all the underlying
Specifier
(or deprecatedLegacySpecifier
) instances in this specifier set.
-
filter
(iterable, prereleases=None)[source]¶ Takes an iterable that can contain version strings,
Version
, and deprecatedLegacyVersion
instances and will then filter it, returning an iterable that contains only items which match the rules of this specifier object.This method is smarter than just
filter(Specifier().contains, [...])
because it implements the rule from PEP 440 where a prerelease item SHOULD be accepted if no other versions match the given specifier.The
prereleases
parameter functions similarly to that of the same parameter incontains
. If the value isNone
(the default) then it will intelligently decide if to allow prereleases based on the specifier, theSpecifier().prereleases
value, and the PEP 440 rules. Otherwise it will act as a boolean which will enable or disable all prerelease versions from being included.
-
class
packaging.specifiers.
Specifier
(specifier, prereleases=None)[source]¶ This class abstracts the handling of a single PEP 440 compatible specifier. It is generally not required to instantiate this manually, preferring instead to work with
SpecifierSet
.- Parameters
- Raises
InvalidSpecifier – If the
specifier
does not conform to PEP 440 in any way then this exception will be raised.
-
operator
¶ The string value of the operator part of this specifier.
-
version
¶ The string version of the version part of this specifier.
-
prereleases
¶
-
__contains__
(version)¶
-
contains
(version, prereleases=None)¶
-
filter
(iterable, prereleases=None)¶
-
class
packaging.specifiers.
LegacySpecifier
(specifier, prereleases=None)[source]¶ Deprecated since version 20.5: Use
Specifier
instead.This class abstracts the handling of a single legacy, setuptools style specifier. It is generally not required to instantiate this manually, preferring instead to work with
SpecifierSet
.- Parameters
- Raises
InvalidSpecifier – If the
specifier
is not parseable then this will be raised.
-
operator
¶ The string value of the operator part of this specifier.
-
version
¶ The string version of the version part of this specifier.
-
prereleases
¶
-
__contains__
(version)¶
-
contains
(version, prereleases=None)¶
-
filter
(iterable, prereleases=None)¶