packaging.specifiers.SpecifierSet Class Reference

Inheritance diagram for packaging.specifiers.SpecifierSet:

Collaboration diagram for packaging.specifiers.SpecifierSet:

Public Member Functions
None	__init__ (self, str|Iterable[Specifier] specifiers="", bool|None prereleases=None)
bool|None	prereleases (self)
None	prereleases (self, bool value)
str	__repr__ (self)
str	__str__ (self)
int	__hash__ (self)
SpecifierSet	__and__ (self, SpecifierSet|str other)
bool	__eq__ (self, object other)
int	__len__ (self)
Iterator[Specifier]	__iter__ (self)
bool	__contains__ (self, UnparsedVersion item)
bool	contains (self, UnparsedVersion item, bool|None prereleases=None, bool|None installed=None)
Iterator[UnparsedVersionVar]	filter (self, Iterable[UnparsedVersionVar] iterable, bool|None prereleases=None)

Protected Attributes
	_specs
	_prereleases

Detailed Description

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.

Constructor & Destructor Documentation

__init__()

None packaging.specifiers.SpecifierSet.__init__	(		self,
		str | Iterable[Specifier]	specifiers = "",
		bool | None	prereleases = None
	)

Initialize a SpecifierSet instance.

:param specifiers:
    The string representation of a specifier or a comma-separated list of
    specifiers which will be parsed and normalized before use.
    May also be an iterable of ``Specifier`` instances, which will be used
    as is.
:param prereleases:
    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.

Member Function Documentation

__and__()

SpecifierSet packaging.specifiers.SpecifierSet.__and__	(		self,
		SpecifierSet | str	other
	)

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

:param other: The other object to combine with.

>>> 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')>

__contains__()

bool packaging.specifiers.SpecifierSet.__contains__	(		self,
		UnparsedVersion	item
	)

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

:param item: The item to check for.

This is used for the ``in`` operator and behaves the same as
:meth:`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

__eq__()

bool packaging.specifiers.SpecifierSet.__eq__	(		self,
		object	other
	)

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

:param other: The other object to check against.

The value of :attr:`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

Reimplemented from packaging.specifiers.BaseSpecifier.

__hash__()

int packaging.specifiers.SpecifierSet.__hash__

(

self

)

Returns a hash value for this Specifier-like object.

Reimplemented from packaging.specifiers.BaseSpecifier.

__iter__()

Iterator[Specifier] packaging.specifiers.SpecifierSet.__iter__

(

self

)

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

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

__len__()

int packaging.specifiers.SpecifierSet.__len__

(

self

)

Returns the number of specifiers in this specifier set.

__repr__()

str packaging.specifiers.SpecifierSet.__repr__

(

self

)

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)>

__str__()

str packaging.specifiers.SpecifierSet.__str__

(

self

)

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'

Reimplemented from packaging.specifiers.BaseSpecifier.

contains()

bool packaging.specifiers.SpecifierSet.contains	(		self,
		UnparsedVersion	item,
		bool | None	prereleases = None,
		bool | None	installed = None
	)

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

:param item:
    The item to check for, which can be a version string or a
    :class:`Version` instance.
:param prereleases:
    Whether or not to match prereleases with this SpecifierSet. If set to
    ``None`` (the default), it uses :attr:`prereleases` to determine
    whether or not prereleases are allowed.

>>> 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

Reimplemented from packaging.specifiers.BaseSpecifier.

filter()

Iterator[UnparsedVersionVar] packaging.specifiers.SpecifierSet.filter	(		self,
		Iterable[UnparsedVersionVar]	iterable,
		bool | None	prereleases = None
	)

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

:param iterable:
    An iterable that can contain version strings and :class:`Version` instances.
    The items in the iterable will be filtered according to the specifier.
:param prereleases:
    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 :attr:`prereleases` attribute, and
    whether the only versions matching are prereleases).

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']

Reimplemented from packaging.specifiers.BaseSpecifier.

prereleases() [1/2]

bool | None packaging.specifiers.SpecifierSet.prereleases

(

self

)

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.

Reimplemented from packaging.specifiers.BaseSpecifier.

prereleases() [2/2]

None packaging.specifiers.SpecifierSet.prereleases	(		self,
		bool	value
	)

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.

Reimplemented from packaging.specifiers.BaseSpecifier.

---

The documentation for this class was generated from the following file:

• docs/help/help-venv/lib/python3.12/site-packages/packaging/specifiers.py