Specifiers

A core requirement of dealing with dependencies is the ability to specify what versions of a dependency are acceptable for you.

See Version Specifiers Specification for more details on the exact format implemented in this module, for use in Python Packaging tooling.

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')>
>>> # We can iterate over the SpecifierSet to recover the
>>> # individual specifiers
>>> sorted(combined_spec, key=str)
[<Specifier('!=1.1')>, <Specifier('>=1.0')>, <Specifier('~=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

exception packaging.specifiers.InvalidSpecifier

Raised when attempting to create a Specifier with a specifier string that is invalid.

>>> Specifier("lolwat")
Traceback (most recent call last):
    ...
packaging.specifiers.InvalidSpecifier: Invalid specifier: 'lolwat'

__weakref__

list of weak references to the object (if defined)

class packaging.specifiers.Specifier

This class abstracts handling of version specifiers.

Tip

It is generally not required to instantiate this manually. You should instead prefer to work with SpecifierSet instead, which can parse comma-separated version specifiers (which is what package metadata contains).

__init__(spec='', prereleases=None)

Initialize a Specifier instance.

Parameters:

• spec (str) – The string representation of a specifier which will be parsed and normalized before use.

• prereleases (bool | None) – This tells the specifier 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 specifier is invalid (i.e. bad syntax).

Return type:

None

property prereleases: bool

Whether or not pre-releases as a whole are allowed.

This can be set to either True or False to explicitly enable or disable prereleases or it can be set to None (the default) to use default semantics.

property operator: str

The operator of this specifier.

>>> Specifier("==1.2.3").operator
'=='

property version: str

The version of this specifier.

>>> Specifier("==1.2.3").version
'1.2.3'

__repr__()

A representation of the Specifier that shows all internal state.

>>> Specifier('>=1.0.0')
<Specifier('>=1.0.0')>
>>> Specifier('>=1.0.0', prereleases=False)
<Specifier('>=1.0.0', prereleases=False)>
>>> Specifier('>=1.0.0', prereleases=True)
<Specifier('>=1.0.0', prereleases=True)>

Return type:

str

__str__()

A string representation of the Specifier that can be round-tripped.

>>> str(Specifier('>=1.0.0'))
'>=1.0.0'
>>> str(Specifier('>=1.0.0', prereleases=False))
'>=1.0.0'

Return type:

str

__hash__()

Returns a hash value for this Specifier-like object.

Return type:

int

__eq__(other)

Whether or not the two Specifier-like objects are equal.

Parameters:

other (object) – The other object to check against.

Return type:

bool

The value of prereleases is ignored.

>>> Specifier("==1.2.3") == Specifier("== 1.2.3.0")
True
>>> (Specifier("==1.2.3", prereleases=False) ==
...  Specifier("==1.2.3", prereleases=True))
True
>>> Specifier("==1.2.3") == "==1.2.3"
True
>>> Specifier("==1.2.3") == Specifier("==1.2.4")
False
>>> Specifier("==1.2.3") == Specifier("~=1.2.3")
False

__contains__(item)

Return whether or not the item is contained in this specifier.

Parameters:

item (str | Version) – The item to check for.

Return type:

bool

This is used for the in operator and behaves the same as contains() with no prereleases argument passed.

>>> "1.2.3" in Specifier(">=1.2.3")
True
>>> Version("1.2.3") in Specifier(">=1.2.3")
True
>>> "1.0.0" in Specifier(">=1.2.3")
False
>>> "1.3.0a1" in Specifier(">=1.2.3")
False
>>> "1.3.0a1" in Specifier(">=1.2.3", prereleases=True)
True

contains(item, prereleases=None)

Return whether or not the item is contained in this specifier.

Parameters:

• item (Version | str) – The item to check for, which can be a version string or a Version instance.

• prereleases (bool | None) – Whether or not to match prereleases with this Specifier. If set to None (the default), it uses prereleases to determine whether or not prereleases are allowed.

Return type:

bool

>>> Specifier(">=1.2.3").contains("1.2.3")
True
>>> Specifier(">=1.2.3").contains(Version("1.2.3"))
True
>>> Specifier(">=1.2.3").contains("1.0.0")
False
>>> Specifier(">=1.2.3").contains("1.3.0a1")
False
>>> Specifier(">=1.2.3", prereleases=True).contains("1.3.0a1")
True
>>> Specifier(">=1.2.3").contains("1.3.0a1", prereleases=True)
True

filter(iterable, prereleases=None)

Filter items in the given iterable, that match the specifier.

Parameters:

• iterable (Iterable[UnparsedVersionVar]) – An iterable that can contain version strings and Version instances. The items in the iterable will be filtered according to the specifier.

• prereleases (bool | None) – Whether or not to allow prereleases in the returned iterator. If set to None (the default), it will be intelligently decide whether to allow prereleases or not (based on the prereleases attribute, and whether the only versions matching are prereleases).

Return type:

Iterator[UnparsedVersionVar]

This method is smarter than just filter(Specifier().contains, [...]) because it implements the rule from PEP 440 that a prerelease item SHOULD be accepted if no other versions match the given specifier.

>>> list(Specifier(">=1.2.3").filter(["1.2", "1.3", "1.5a1"]))
['1.3']
>>> list(Specifier(">=1.2.3").filter(["1.2", "1.2.3", "1.3", Version("1.4")]))
['1.2.3', '1.3', <Version('1.4')>]
>>> list(Specifier(">=1.2.3").filter(["1.2", "1.5a1"]))
['1.5a1']
>>> list(Specifier(">=1.2.3").filter(["1.3", "1.5a1"], prereleases=True))
['1.3', '1.5a1']
>>> list(Specifier(">=1.2.3", prereleases=True).filter(["1.3", "1.5a1"]))
['1.3', '1.5a1']

class packaging.specifiers.SpecifierSet

This class abstracts handling of a set of version specifiers.

It can be passed a single specifier (>=3.0), a comma-separated list of specifiers (>=3.0,!=3.1), or no specifier at all.

__init__(specifiers='', prereleases=None)

Initialize a SpecifierSet instance.

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 | None) – 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.

Return type:

None

property prereleases: bool | None

Whether or not pre-releases as a whole are allowed.

This can be set to either True or False to explicitly enable or disable prereleases or it can be set to None (the default) to use default semantics.

__repr__()

A representation of the specifier set that shows all internal state.

Note that the ordering of the individual specifiers within the set may not match the input string.

>>> SpecifierSet('>=1.0.0,!=2.0.0')
<SpecifierSet('!=2.0.0,>=1.0.0')>
>>> SpecifierSet('>=1.0.0,!=2.0.0', prereleases=False)
<SpecifierSet('!=2.0.0,>=1.0.0', prereleases=False)>
>>> SpecifierSet('>=1.0.0,!=2.0.0', prereleases=True)
<SpecifierSet('!=2.0.0,>=1.0.0', prereleases=True)>

Return type:

str

__str__()

A string representation of the specifier set that can be round-tripped.

Note that the ordering of the individual specifiers within the set may not match the input string.

>>> str(SpecifierSet(">=1.0.0,!=1.0.1"))
'!=1.0.1,>=1.0.0'
>>> str(SpecifierSet(">=1.0.0,!=1.0.1", prereleases=False))
'!=1.0.1,>=1.0.0'

Return type:

str

__hash__()

Returns a hash value for this Specifier-like object.

Return type:

int

__and__(other)

Return a SpecifierSet which is a combination of the two sets.

Parameters:

other (SpecifierSet | str) – The other object to combine with.

Return type:

SpecifierSet

>>> SpecifierSet(">=1.0.0,!=1.0.1") & '<=2.0.0,!=2.0.1'
<SpecifierSet('!=1.0.1,!=2.0.1,<=2.0.0,>=1.0.0')>
>>> SpecifierSet(">=1.0.0,!=1.0.1") & SpecifierSet('<=2.0.0,!=2.0.1')
<SpecifierSet('!=1.0.1,!=2.0.1,<=2.0.0,>=1.0.0')>

__eq__(other)

Whether or not the two SpecifierSet-like objects are equal.

Parameters:

other (object) – The other object to check against.

Return type:

bool

The value of prereleases is ignored.

>>> SpecifierSet(">=1.0.0,!=1.0.1") == SpecifierSet(">=1.0.0,!=1.0.1")
True
>>> (SpecifierSet(">=1.0.0,!=1.0.1", prereleases=False) ==
...  SpecifierSet(">=1.0.0,!=1.0.1", prereleases=True))
True
>>> SpecifierSet(">=1.0.0,!=1.0.1") == ">=1.0.0,!=1.0.1"
True
>>> SpecifierSet(">=1.0.0,!=1.0.1") == SpecifierSet(">=1.0.0")
False
>>> SpecifierSet(">=1.0.0,!=1.0.1") == SpecifierSet(">=1.0.0,!=1.0.2")
False

__len__()

Returns the number of specifiers in this specifier set.

Return type:

int

__iter__()

Returns an iterator over all the underlying Specifier instances in this specifier set.

>>> sorted(SpecifierSet(">=1.0.0,!=1.0.1"), key=str)
[<Specifier('!=1.0.1')>, <Specifier('>=1.0.0')>]

Return type:

Iterator[Specifier]

__contains__(item)

Return whether or not the item is contained in this specifier.

Parameters:

item (Version | str) – The item to check for.

Return type:

bool

This is used for the in operator and behaves the same as contains() with no prereleases argument passed.

>>> "1.2.3" in SpecifierSet(">=1.0.0,!=1.0.1")
True
>>> Version("1.2.3") in SpecifierSet(">=1.0.0,!=1.0.1")
True
>>> "1.0.1" in SpecifierSet(">=1.0.0,!=1.0.1")
False
>>> "1.3.0a1" in SpecifierSet(">=1.0.0,!=1.0.1")
False
>>> "1.3.0a1" in SpecifierSet(">=1.0.0,!=1.0.1", prereleases=True)
True

contains(item, prereleases=None, installed=None)

Return whether or not the item is contained in this SpecifierSet.

Parameters:

• item (Version | str) – The item to check for, which can be a version string or a Version instance.

• prereleases (bool | None) – Whether or not to match prereleases with this SpecifierSet. If set to None (the default), it uses prereleases to determine whether or not prereleases are allowed.

• installed (bool | None) –

Return type:

bool

>>> SpecifierSet(">=1.0.0,!=1.0.1").contains("1.2.3")
True
>>> SpecifierSet(">=1.0.0,!=1.0.1").contains(Version("1.2.3"))
True
>>> SpecifierSet(">=1.0.0,!=1.0.1").contains("1.0.1")
False
>>> SpecifierSet(">=1.0.0,!=1.0.1").contains("1.3.0a1")
False
>>> SpecifierSet(">=1.0.0,!=1.0.1", prereleases=True).contains("1.3.0a1")
True
>>> SpecifierSet(">=1.0.0,!=1.0.1").contains("1.3.0a1", prereleases=True)
True

filter(iterable, prereleases=None)

Filter items in the given iterable, that match the specifiers in this set.

Parameters:

• iterable (Iterable[UnparsedVersionVar]) – An iterable that can contain version strings and Version instances. The items in the iterable will be filtered according to the specifier.

• prereleases (bool | None) – Whether or not to allow prereleases in the returned iterator. If set to None (the default), it will be intelligently decide whether to allow prereleases or not (based on the prereleases attribute, and whether the only versions matching are prereleases).

Return type:

Iterator[UnparsedVersionVar]

This method is smarter than just filter(SpecifierSet(...).contains, [...]) because it implements the rule from PEP 440 that a prerelease item SHOULD be accepted if no other versions match the given specifier.

>>> list(SpecifierSet(">=1.2.3").filter(["1.2", "1.3", "1.5a1"]))
['1.3']
>>> list(SpecifierSet(">=1.2.3").filter(["1.2", "1.3", Version("1.4")]))
['1.3', <Version('1.4')>]
>>> list(SpecifierSet(">=1.2.3").filter(["1.2", "1.5a1"]))
[]
>>> list(SpecifierSet(">=1.2.3").filter(["1.3", "1.5a1"], prereleases=True))
['1.3', '1.5a1']
>>> list(SpecifierSet(">=1.2.3", prereleases=True).filter(["1.3", "1.5a1"]))
['1.3', '1.5a1']

An “empty” SpecifierSet will filter items based on the presence of prerelease versions in the set.

>>> list(SpecifierSet("").filter(["1.3", "1.5a1"]))
['1.3']
>>> list(SpecifierSet("").filter(["1.5a1"]))
['1.5a1']
>>> list(SpecifierSet("", prereleases=True).filter(["1.3", "1.5a1"]))
['1.3', '1.5a1']
>>> list(SpecifierSet("").filter(["1.3", "1.5a1"], prereleases=True))
['1.3', '1.5a1']